Claude Engram

Persistent memory and session intelligence for AI coding assistants. Hooks into Claude Code's lifecycle to auto-track mistakes, decisions, and context — then mines your full session history to surface patterns, predict what you'll need, and search across everything you've ever discussed.

Zero manual effort. Works with any MCP-compatible client.

What It Does

Automatic (hooks — zero invocation):

• Tracks every edit, error, test result, and session event
• Auto-captures decisions from your prompts ("let's use X", "switch to Y")
• Injects the 3 most relevant memories before every file edit
• Warns when you're about to repeat a past mistake
• Detects edit loops (same file 3+ times without progress)
• Survives context compaction — checkpoints before, re-injects after
• Mines your session history in the background after every session
• Verifies imports in proposed edits against a per-project code index (AST, no LLM) — <engram-precheck> with closest-name suggestions
• Shows blast radius before editing a shared module — lists its importers (<engram-blast-radius>)
• Measures injection precision — tracks which injected context precedes passing tests (view via session_mine(reflect))

Session Mining (automatic, background):

• Parses Claude Code's full conversation logs (JSONL) after every session — including subagent conversations (Explore, Plan, code-reviewer, etc.)
• Extracts decisions, mistakes, approaches, and user corrections using structural analysis + AllMiniLM semantic scoring (typo-tolerant)
• Builds a searchable index across all past conversations (20k+ chunks with subagents)
• Detects recurring struggles, error patterns, and file edit correlations
• Predicts what files and context you'll need before edits
• Logs which injected context precedes passing tests; session_mine(reflect) reports that precision + LLM-synthesized patterns
• On first install, retroactively mines your entire session history

On-demand (MCP tools):

• memory — store, search, archive, and manage memories
• session_mine — search past conversations (taggable by kind: decision / next-step / error), find decisions, replay file history, detect patterns, and surface what you said you'd do this session (commitments)
• work — log decisions and mistakes with reasoning
• Plus: scope guard, context checkpoints (checkpoint_save/restore/list; handoff_* are deprecated aliases), convention tracking, impact analysis

All MCP tools carry annotations (read-only / idempotent hints + a title), so clients and permission systems know which are safe to call without a prompt.

A Note From the Author

How I actually use it, since I built it:

Mostly it just works in the background — you don't have to think about it. The few things worth doing on purpose:

• Pull /engram when you want Claude to actively reach for the tools — the command loads the reference so Claude knows what's there and uses it. (Background tracking happens either way; this is for the on-demand stuff.)
• When you half-remember something from a while back ("what did we decide about X?"), ask Claude to mine the sessions for it — it searches everything you've ever discussed, not just what's in context.
• If there's something it should never forget, save it as a rule. Rules are scoped: a per-project rule applies to that project; a global one (saved at your workspace root) cascades down to every project under it. Broad conventions → global, project-specific → per-project.
• Before compacting, it auto-saves a checkpoint — but I make one with what I'm doing + what's left and ask it to pull that back up after. Resumes a lot cleaner.
• When you come back, ask what you said you'd do this session — it skims the live conversation for open loops vs. what's done. It's a best-effort read (not a perfect list), but a quick way to reorient.

The less you poke at it, the better it works.

This is a work in progress — if something's off or you hit a bug, please open an issue.

How It Works

Claude Code
    |
    +-- Hooks (remind.py)                    <- Intercepts every tool call
    |   SessionStart / Edit / Bash / Error / Compact / Stop
    |
    +-- Session Mining (mining/)             <- Background intelligence
    |   JSONL parser -> Extractors -> Search index -> Pattern detection
    |
    +-- MCP Server (server.py)              <- Tools for manual operations
    |   memory, session_mine, work, scope, context, ...
    |
    +-- Scorer Server (scorer_server.py)    <- Persistent AllMiniLM process
        TCP localhost, ~90MB RAM, batch embeddings

Hooks fire on every tool call (1-2s budget each). Heavy processing happens in a background subprocess after session end. The scorer server stays loaded in memory for fast semantic scoring.

Benchmarks

Retrieval (recall@k): LongMemEval 0.966 R@5 / 0.982 R@10 (500 questions), ConvoMem 0.960 (250 items), LoCoMo 0.649 R@10 (~2k questions); ~43ms/query, 112ms cross-session over 7,310 chunks.

Product behavior: eight integration suites green — decision capture (97.8% precision), error auto-capture (100% recall), compaction survival (6/6), multi-project isolation (11/11), edit-loop detection (12/12), session mining (27/27), Obsidian-vault compat (25/25).

Full tables and the tests/bench_*.py reproduction commands are in the library-book.

Compatibility

Install

git clone https://github.com/20alexl/claude-engram.git
cd claude-engram
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows

pip install -e .                # Core
pip install -e ".[semantic]"    # + AllMiniLM for vector search and semantic scoring

python install.py               # Configure hooks, MCP server, and /engram skill

Per-Project Setup

python install.py --setup /path/to/your/project

Or copy .mcp.json to your project root.

Note: The CLAUDE.md in this repo is engram-specific documentation — it's not required for engram to work. Hooks fire automatically and the /engram skill provides a quick reference on demand. If you already have a CLAUDE.md for your project, keep it as-is and don't copy ours over it. If you want engram docs alongside your project rules, rename it to CLAUDE-ENGRAM.md (or similar) so it doesn't clobber your existing file — Claude will see it when relevant.

Updating

cd claude-engram
git pull
pip install -e ".[semantic]"    # Reinstall if dependencies changed
python install.py               # Re-run to update hooks and /engram skill

Hooks and MCP tools pick up code changes immediately (editable install). Reconnect the MCP server in Claude Code (/mcp) to reload the server process.

Data migrations run automatically: a cheap inline check fires on the next SessionStart, and a full migration runs in the background. install.py also runs migrations synchronously (step 9). Migrations are forward-only, idempotent, and downgrade-safe — no data is lost.

Mid-Project Adoption

Already deep in a project? Install normally. On first session, engram auto-detects your existing Claude Code session history and mines it in the background — extracting decisions, mistakes, and patterns from all past conversations. No manual effort.

Key Features

Memory — hybrid search (keyword + AllMiniLM vector + rerank, no ChromaDB); path-aware scored injection (top 3 by file/tags/recency/importance, with age shown); tiered hot/cold storage (rules and mistakes never archive); per-sub-project scoping with cascading workspace rules.

Session mining — structural extraction (conversation flow, not template matching) over conversation and tool content; cross-session semantic/keyword/hybrid search, typed by kind (decision / next-step / error) and filterable; session_mine(commitments) reads the live transcript for open loops the post-session index can't see; pattern detection, predictive context, cross-project learning; retroactive bootstrap on first install.

Lifecycle — auto-captured decisions + mistakes; survives compaction (per-project checkpoints in a durable ring); edit-loop detection; subagent-aware; automatic, idempotent, downgrade-safe migrations on upgrade.

Internals, the full feature list, gotchas, and API reference live in the library-book.

Configuration

Reindexing

If search quality is poor or you want to rebuild after an update:

python scripts/reindex.py "/path/to/your/workspace" --force            # rebuild search index
python scripts/reindex.py "/path/to/your/workspace" --force --extract   # also re-extract decisions/mistakes

Or via MCP: session_mine(operation="reindex", mode="bootstrap")

Documentation

Library Book — design philosophy, internals, full usage guide, API reference, gotchas, and changelog.

/engram — slash command with quick tool reference (installed by install.py).

License

MIT