engrim plugin
Local project memory for coding agents: decisions and current state survive a model switch or a cleared chat
- 301 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Hooks run on every start and prompt, and `engrim setup` edits agent configs and `~/.claude/CLAUDE.md`
- The database collects project decisions and details, so keep the file out of shared folders
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/engrimDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Hooks run on every start and prompt, and `engrim setup` edits agent configs and `~/.claude/CLAUDE.md`
- The database collects project decisions and details, so keep the file out of shared folders
This is third-party code. Review the repository files before installing.
What it does
engrim keeps a project's decisions, constraints and current state in a local SQLite database and hands the agent a short digest instead of replaying the whole conversation. When a session starts and on every prompt, hooks inject a memory pack of about 4,000 characters. Records come in six types: decision, fact, feedback, state, user and reference. The agent writes them itself through the `engrim_add` tool, or you add them with `engrim add`. Retrieval is hybrid: lexical bm25 plus vector similarity on static model2vec embeddings. The tools `engrim_recall`, `engrim_context` and `engrim_review` search records, return the memory pack and check whether the log still holds uncaptured decisions before you clear the chat with `/clear`. One database serves seven agents, from Claude Code and Cursor to Codex CLI and Google Antigravity, and every record carries a mark of the agent that wrote it.
Who it is for. For developers who work on one repository across several agents and do not want to re-explain past decisions after every cleared chat.
Good fit when
- The session has grown, you are about to run `/clear` and want to keep decisions and the next step
- Claude Code, Cursor and Codex take turns on one project and need a shared memory
- Decisions should be stored with their reasons, for example why you moved from MongoDB to PostgreSQL
- Data must stay on the machine: no cloud sync, no API key, no telemetry
- After moving your setup to another machine you want to confirm that hooks and MCP are in place
Not a fit when
- The whole team needs the memory: the database sits in one user's home folder, though `engrim merge` can fold another database in
- Nobody is going to capture decisions: the quality of memory depends on what the agent or you recorded
- The agent has no hooks or MCP, for example a web chat: there is nothing to attach engrim to
- You need an index of the whole codebase: engrim searches memory records and does not index source code
Example request
Record the decision: we are moving to PostgreSQL for transactions, and pin the migration move as the next step. Then I will clear the chat and you will continue from there.Limitations
Python 3.10 or newer is required. The agent reads hooks at startup, so open a new session after `engrim setup`. In Codex the hooks must be reviewed and trusted with `/hooks` before they run, and the MCP server is connected with a separate `--codex-mcp` flag. GitHub Copilot CLI does not publish its event file format as a stable contract, and engrim warns when records are incompatible. The author measured the context savings shown on the project site on one of his own projects, with no independent check. A connection to PyPI is needed for installation; afterwards the tool works offline.
How to disable. For Codex, `engrim uninstall --codex` removes only the engrim hooks, the guidance block and the mcp_servers.engrim entry. Disable or remove the Claude Code plugin through /plugin, and delete the remaining entries in other agents' configs by hand. The `~/.engrim/memory.db` file stays on disk, so delete it if you no longer need the memory.
FAQ
How do I install engrim in Claude Code?
As a plugin: `/plugin marketplace add timgordontg/engrim`, then `/plugin install engrim@engrim`. The plugin installs itself on first run and needs no API key. The other route is `pip install engrim` followed by `engrim setup --claude`, which writes the hooks into `~/.claude/settings.json`.
What happens to context after /clear?
The new session boots from the memory database: the pack starts with a record tagged resume-pointer under the heading "RESUME HERE". `engrim retire` closes such a record once the work is done.
Where does engrim store data and does anything leave the machine?
Data lives in the SQLite file `~/.engrim/memory.db` with 0600 permissions on POSIX systems. The project has no telemetry and no cloud sync.
How do I connect engrim to Cursor or Windsurf?
For Cursor run `engrim setup --cursor`: it adds the server to `~/.cursor/mcp.json` with the launch command `engrim serve --mcp`. For Windsurf paste the same block into `~/.codeium/windsurf/mcp_config.json` by hand.
How can I check that hooks survived a move to another computer?
Run `engrim doctor`; with `--fix` it repairs stale binary paths. Hook commands also fall back to a PATH lookup, so a session does not fail silently.
Discussion
No questions or reviews yet.
Related
PluginsEngram by Gentleman Programming
Engram (Gentleman Programming)
Persistent memory for AI coding agents in a single Go binary: an MCP server on SQLite with full-text search that remembers your project across sessions
Shared semantic memory for agents: conversations are saved as markdown and recalled by search across Claude Code, Codex and other agents
Shared local memory for AI agents: Claude Code, Codex, Cursor and others find the agreements of past sessions in it and record new ones
Persistent agent memory in a folder of linked markdown notes, so Claude Code remembers a project across sessions
Shared cloud memory for a team's agents: stores session traces and turns repeated patterns into skills
Local persistent memory for coding agents: hooks record every session, and Claude Code, Codex or Cursor recall past decisions through 54 MCP tools
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| engrim (this entry) | no | 301 | ||
| Claude-Mem | no | 104,106 | a plugin that saves session observations and injects context | |
| projectmem | yes | not required | 870 | a memory MCP server that stores problems, attempts and fixes |
README in short
The core idea is the continue-as-clear mode: before clearing the chat you pin the next task, and the new session starts from it. For GitHub Agentic Workflows the examples folder shows memory across runs through artifacts and `engrim merge`.