engrim
local SQLite memory store for AI coding agents
TLDR
SYNOPSIS
engrim [--db path] command [options]
DESCRIPTION
engrim is a local-first, project-scoped memory engine for AI coding agents. It stores curated records (decisions, facts, feedback, state) in a SQLite database and reloads a small working set at session start so you can switch models or clear a chat without losing project context.Recall combines SQLite FTS5 (bm25) with optional static embeddings (`model2vec`) via reciprocal-rank fusion. Set `ENGRIM_EMBED=off` for lexical-only search with no extra model load. The default database is `~/.engrim/memory.db` with owner-only file permissions.setup can install Google Antigravity hooks, Claude Code SessionStart/Stop hooks, and a Cursor MCP entry. The MCP tools include `engrimrecall`, `engrimadd`, `engrimcontext`, and `engrimreview`.Project tags default to the nearest VCS or `.claude` directory. `$ENGRIM_PROJECT` overrides that when host and container paths differ.
PARAMETERS
--db path
SQLite store path. Default: `$ENGRIM_DB` or `~/.engrim/memory.db`.add -t type -s summary
Insert a memory. Types: `decision`, `fact`, `feedback`, `state`, `user`, `reference`.recall -q query
Ranked hybrid search (FTS5 bm25 plus optional embeddings). -k sets the hit count.context [-b budget]
Print a budget-capped session-boot pack (default 4000 characters).list [-k n]
List recent memories for the current project.setup [--agy|--claude|--cursor|--all]
Wire hooks and MCP config. With no flags, auto-detects installed environments.serve --mcp
Run the JSON-RPC MCP server on stdio (`engrim mcp` is the same).review
Scan the transcript log for decisions not yet stored as memories.supersede --id n [--status status]
Change a record's status (`active`, `superseded`, `done`).hook [--agent {claude,agy,antigravity}] [--event {boot,stop}]
Lifecycle hook used by agent integrations; prints JSON for the host.-p, --project tag
Project scope. Default `auto` (git/hg/svn/`.claude` root, else cwd). --global on add writes the shared user layer.
CONFIGURATION
ENGRIM_DB
Path to the SQLite store.ENGRIM_PROJECT
Stable project tag (overrides path detection).ENGRIM_EMBED
Set to `off` to disable embeddings.ENGRIM_EMBED_MODEL
Hugging Face id for the static embedder (default `minishlab/potion-base-8M`).ENGRIM_NO_GLOBAL
Disable the shared user-layer that otherwise loads in every project.ENGRIM_ORIGIN_AGENT
Default `origin_agent` on add (`antigravity`, `claude-code`, `cursor`, `cli`, `user`).
CAVEATS
Python 3.10+ and a `pip install engrim` (or equivalent) install. Memory is local only; there is no cloud sync. Agent hook installation writes files under `~/.gemini`, `~/.claude`, or `~/.cursor`. Embedding download happens on first semantic recall unless `ENGRIM_EMBED=off`. Not affiliated with Anthropic, Google, or Cursor.
HISTORY
Written by Tim Gordon and released under the MIT license. Distributed on PyPI as engrim.
