Persistent, cross-session memory for AI agents
Engram — Persistent Memory for Claude Code
An engram is a unit of cognitive information imprinted in neural tissue — the physical trace of a memory.
Why Engram?
Claude Code forgets everything when the context window compacts. Your decisions, your debugging breakthroughs, your "always use X instead of Y" — gone. You repeat the same mistakes, re-explain the same architecture, re-discover the same solutions.
Engram fixes this. After compaction, Claude continues working like it never happened — with your decisions, pitfalls, and project context intact.
You Don't Need Memory MCP
If you're using Memory MCP or similar knowledge-graph memory servers, Engram replaces them entirely:
| Memory MCP | Engram | |
|---|---|---|
| Encoding | Manual — Claude must decide to call create_entities |
Automatic — hooks capture errors, corrections, decisions without tool calls |
| Recall | Manual — Claude must call search_nodes |
Automatic — pitfalls injected before writes, corrections on session start |
| After compaction | Nothing — Claude doesn't know the memory server exists | Full recovery — briefing auto-injected with task, files, decisions, pitfalls |
| Context cost | Every tool call burns tokens | Zero-token hooks — hooks run outside the context window |
| Learning | Store and retrieve | Encode, decay, and surface — confidence scoring, relevance matching, natural forgetting |
| Noise | Grows forever, no curation | Self-maintaining — confidence decay, dedup, stale detection |
| Error prevention | None | Pitfall surfacing — warns before you repeat known mistakes |
The Compaction Problem (and Why Hooks Solve It)
When Claude Code's context window fills up, it compacts — summarizing the conversation to free space. This destroys:
- What you were doing and why
- Decisions you made and their rationale
- Errors you hit and how you fixed them
- Files you were working on
Tool-based memory servers can't help because after compaction, Claude doesn't remember the server exists until something reminds it to call a tool. There's no automatic trigger.
Engram's hooks fire automatically:
SessionStarthook injects a briefing with your active plan, recent pitfalls, and project context — Claude picks up exactly where it left offPreCompacthook saves a snapshot of what you were doing before compaction happensUserPromptSubmithook surfaces relevant memories on every prompt — no tool call neededPreToolUsehook warns about known pitfalls before every Write/Edit/Bash
The result: compaction becomes invisible. Claude continues working with full context of your decisions, your mistakes, and your project's pitfalls.
How Much Context Does Engram Use?
Engram's post-compaction injection is ~180 tokens — just task, domain, files, and critical decisions. Everything else is pulled on-demand per prompt. Compare this to the 2000+ tokens that narrative-style memory systems inject, displacing space you need for actual work.
How It Works
┌─────────────────────────────────────────────────────┐
│ Claude Code │
│ │
│ Hooks (automatic, zero-token): │
│ SessionStart → inject briefing + pitfalls │
│ PreCompact → save snapshot before compaction │
│ PreToolUse → warn on known pitfalls │
│ UserPrompt → surface relevant memories │
│ PostToolFail → learn from errors automatically │
│ PostToolUse → boost pitfalls you avoided │
│ SessionEnd → close session, promote pitfalls │
│ │
│ MCP Tools (discretionary): │
│ engram_recall → search memories │
│ engram_learn → store a lesson │
│ engram_plan → track multi-step tasks │
│ engram_remind → "when X, remind me Y" │
│ + correct, forget, strengthen, weaken │
│ │
│ StatusLine: │
│ Engram: normal | 42 mem 3 rem │
└────────────────────┬────────────────────────────────┘
│
┌──────┴──────┐
│ SQLite DB │
│ + FTS5 │
│ ~/.engram/ │
└─────────────┘
Quick Start
1. Clone and build
git clone https://github.com/vedtechsolutions/engram-mcp.git
cd engram-mcp
pnpm install
npx tsup
2. Configure MCP server
Add to your project's .mcp.json:
{
"mcpServers": {
"engram": {
"command": "node",
"args": ["/path/to/engram-mcp/dist/server.js"]
}
}
}
3. Configure hooks
Add to your project's `.claude/setting
Tools (4)
engram_recallSearch through stored memories and project context.engram_learnManually store a specific lesson or piece of information.engram_planTrack and manage multi-step tasks.engram_remindSet a conditional reminder for future sessions.Configuration
{"mcpServers": {"engram": {"command": "node", "args": ["/path/to/engram-mcp/dist/server.js"]}}}