使用说明
Engram
Git-aware session memory for coding agents.
Engram is an MCP server that gives a coding agent memory across sessions. At the end of a session the agent writes a handoff: what it decided, what blocks it, what it tried and abandoned. The next session on that branch starts from it, with the project's open todos alongside.
Everything stays on your machine: one SQLite file and a small local embedding model. Nothing is sent to a cloud service, and storing a memory never calls an LLM.
A session, resumed
$ engram-cli handoff resume
Branch: feat/auth
Latest handoff: mem_a5b0…
Chain (2 handoffs, oldest to newest):
mem_e8cc…
mem_a5b0…
Open todos (3 total):
- [ ] Rotate the signing key before the 2.0 tag (mem_65e6…)
...
Open blockers:
- Staging has no OAuth client for the new callback URL
Top sections:
─────────────────────────────────────────
[mem_a5b0…] tried (score: 0.94)
Refreshing tokens in middleware: every request raced the refresh and logged users out
─────────────────────────────────────────
...
An agent gets the same thing from the handoff_resume tool, or from the /mcp__engram__resume prompt in Claude Code.
Install
cargo install engram_mcp
claude mcp add -s user engram $(which engram)
This installs two binaries. engram is the MCP server, which your client starts. engram-cli is for you and for scripts. For Claude Desktop, the session hooks and the handoff skills, see setup.
What it does
- Handoffs are structured into sections and chained per git branch, so context from
feat/authdoes not leak intofix/billing. - Todos live on a durable per-project list with an explicit done or dropped state, so finished work and forgotten work stay distinguishable.
- Facts, decisions, patterns and debug findings are searched with BM25 and embeddings combined. A store reports existing memories it may repeat or replace.
- Old knowledge fades as newer knowledge about the same project arrives, not with the calendar. A project you leave for a year is as fresh as the day you left it.
- Architecture decisions are kept as numbered ADRs that move through proposed, accepted and superseded, and export as Markdown files.
- A memory can be superseded by a newer one, which retrieval then returns in its place. Deletions go to a trash you can restore from.
- Project ids come from the git remote, so the same repo is the same project on every machine.
engram-cli sync user@hostkeeps two machines in step over plainssh.
Documentation
| Setup | Clients, hooks, skills, syncing two machines |
| MCP tools | Every tool, its arguments, project and branch scoping |
| CLI | engram-cli commands and --json output |
| Configuration | Environment variables |
| How it works | Retrieval, decay, dedup, handoff chains, sync rules, benchmark |
| Compared to other tools | Mem0, mcp-memory-service, Zep, Letta |
| Hooks | Passive capture from Claude Code lifecycle events |
| Changelog |
Limits
Single user, single node, no auth: it is a local MCP server. Sync is pairwise between machines you can ssh into, and deletions do not sync.
Development
cargo build --release
cargo test
cargo clippy --all-targets
cargo fmt --check
