Claude Engram
Persistent memory and session intelligence for Claude Code. Engram hooks into the session lifecycle and tracks mistakes, decisions, edits, tests and context on its own. It mines your full session history so past work comes back when it is relevant. It keeps long sessions safe across compaction. And it brackets Claude Code's /goal loop so an unattended run cannot poll all night, lose its record, or die silently.
Most of it runs through hooks with nothing to call. The rest is MCP tools, so any MCP client can use the tools, and Claude Code gets the hooks as well.
Contents: What runs on its own · Install · Day to day · The tools · Memory · Checkpoints and compaction · Unattended runs · Rules with detectors · Project defaults · Run report · Session mining · Configuration · Storage · Compatibility · Benchmarks
What runs on its own
Every row is a hook. You call nothing.
| Moment | What engram does |
|---|---|
| Session start | Prints the banner: the project's rules (inherited ones marked), its own past mistakes with a count of the pooled ones (every count names the project it was read for, the same store the prompt hook counts), the latest deliberate checkpoint with its /goal and how far the repo moved since, on this branch and on other local branches since the checkpoint was saved (worktrees included), last session's files (narrowed to the sub-project most of its edits belong to when the session spanned several, and labeled so) and activity, recurring errors with their known fixes, and the project's known-good test commands that currently pass. Runs data migrations. Every block is scoped to the project the session is about, which engram reads from the session's own Edit and Write calls in the transcript, not from the working directory. On a resume or after a compaction that project is known at start; on a fresh start the recurring errors and known-good commands wait for the first edit, when the file names the project. Engram's own failures never appear as a project's recurring errors. On a project's first session, finds existing Claude Code history and mines it in the background. Seeds the default pack once (see Project defaults) and announces a pending rotation. Warns when Claude Code's transcript format is no longer recognized, and when no statusline records context usage |
| Every prompt | Captures decisions from what you type ("let's use X", "switch to Y", "from now on always Z") by semantic scoring with a regex fallback, then a shape gate shared with the transcript miner: a declarative sentence with a deciding word, never a question, an acknowledgement, a count or a table row. Questions and requests for information are not captured. Delivers any staged nudge |
| Before an edit | Injects the three memories most relevant to the file (a rule only when it names the file, an entry older than a month only when it names the full path), warns before a past mistake tied to that file (a code exception is never predicted for a non-code file), warns after three edits to the same file in one session (edit loop), verifies that a proposed import resolves against the per-project code index (<engram-precheck>, with the closest name), lists the modules that import the file (<engram-blast-radius>), shows related files and likely errors from history, and checks the declared task scope |
| Before a read | Once per file per session: an orientation from the code index plus the file's most relevant memories (<engram-read-context>) |
| Before a shell command | Matches the command against every rule that carries a detector and injects the rule before the command runs (<engram-rule>). Under a goal run a deny detector refuses the command |
| After an edit | Counts the edit for the loop warning and prints nothing. Files under node_modules, a virtualenv or a listed non_project_dirs name never warn |
| After a shell command | Tracks test runs and says so only on the first result and on each flip, with a status that lasts the whole session (the output counts when the command names a test runner, or when nothing in the chain merely reads: cat run.log; bash count.sh is never a test run, wrappers like timeout and uv run are looked through, and a bare "N errors" is not a verdict; a failure's mistake attaches to the traceback's files, else the session's edited code files), warns after three failed searches in a row (search spiral), and records which injections preceded a passing test (the outcome feedback loop) |
| After any batch of tool calls | Accounts the calls to the turn for stall detection and records detector matches on non-shell tools (path globs on edits, MCP tools by name) |
| After a failed tool | Logs the error as a mistake, unless it was a failing test run. When the failure matches a recurring error from past sessions or a stored mistake, injects the past fix at once ("Deja vu: TypeError hit in 3 past sessions, fix: ...") |
| After ExitPlanMode or a task update | Asks for the approved plan to be banked as a checkpoint with its steps pending. A task marked completed counts as a milestone claim |
| Stop (end of a turn) | Saves the handoff (last message, files), reads the final message for a completion claim without a checkpoint behind it, judges the turn for stall detection, brings the /goal bracket in step with the transcript, and ticks the live miner (debounced, CLAUDE_ENGRAM_LIVE_MINE) |
| Before compaction | Writes the automatic checkpoint (the floor) |
| After compaction | States the pressure rhythm (heads-up, checkpoint, auto-compaction). The session-start banner that follows re-injects the rules, the mistakes and the checkpoint banked before the compaction |
| An API failure | Records the failure with its type and, for a usage limit, the reset time. Sends an alert during a goal run |
| A notification | A permission prompt, a needs-input or an idle notification during a goal run sends an alert |
| Session end | Writes the session summary, the run report for a substantial session, the rotation plan, and spawns the background miner |
