engram

Engram — project memory (Normal)

Engram is a local, user-owned graph of why things are the way they are in this project: decisions and their reasons, gotchas that bit us, problems and how they were solved, stable preferences. Not code structure, not implementation detail — the codebase already holds those.

What good capture buys. A session that recalls well starts where the last one stopped: settled decisions don't get relitigated, known rakes don't get stepped on twice, and "why is it like this?" gets a real answer instead of archaeology. A session that captures well pays that forward. And because the graph is a pane the user curates — not hidden plumbing — every node you write is something they will see. That's also the failure mode to respect: a graph that's noisy or wrong stops being trusted, and an untrusted graph stops being read. Quality of nodes, honesty of edges, and closed loops matter more than volume.

This is the Normal variant: balanced capture. Save what a future session would genuinely want to know; skip noise.

Claude Code already has memory of its own (CLAUDE.md, auto-memory) — don't mirror it. Engram is additional: it holds the project's reasoning — decisions with reasons, conflicts, gotchas — not user preferences, session workflow, or code structure.

You interact with it through the engram MCP tools. Three jobs: recall (read before you act), capture (write durable knowledge after you act), and maintenance (keep what's already there honest).

Recall — brief first, then search

• At the start of a session, call brief once: a compact digest of the canon — unresolved conflicts, suspects to judge, recent changes, the open worklist, principles, decisions, cautions. Every record carries its node id; act on ids directly. If the session already opens with an injected "# Engram brief" (the session-start hook provides it), that IS the brief — read it and don't call the tool again.
• Before any non-trivial decision, call search with a natural-language description of what you're about to do. Hits carry their 1-hop neighbors, conflicts-with/replaces first — read those especially. Search takes a detail level — start compact (id/title/score only) when scanning broadly, default snippet when working, full (bodies attached) only for the hits you'll actually act on: expand on demand instead of paying for depth up front. If a prior Decision or Caution covers your situation, follow it or, if you're about to contradict it, surface that to the user.
• Respect the reply's confidence verdict. strong — the top hit cleared the calibrated line; act on it. weak — likely not in memory: nothing cleared this graph's calibrated line (auto-tune fits it per graph), so the hits are the nearest candidates rather than a found answer — they are never cut, but verify against the code or the user before relying on one. none — the graph is silent: say so instead of inventing a memory, and capture the fact once this session establishes it. Weak tail hits and the noise past the score cliff are already trimmed before delivery, so what arrives is what deserves your attention.
• On a weak or none verdict, reformulate before concluding absence. One phrasing is one probe, and the graph's register is rarely the user's: try two or three angles before deciding the memory isn't there — entity-first (name the thing: "tepin store lock", not "why won't the daemon start"), paraphrased into the graph's vocabulary (the words a note would have used, not the words the question used), and date-anchored (after: "last week", or during_version when you roughly know the cycle). Each is one cheap call. Only after that is "the graph is silent" an honest answer rather than a failed first guess.
• Scope in time when the question is temporal. search takes after / before — a day (2026-08-14), an ISO instant, or a relative expression the daemon resolves (today, yesterday, last week, last 3 days, 2 hours ago, a month ago, this year) — plus during_version ("0.8.4", resolved from the graph's own recorded version switches) and order (chronological to read how something developed, recent for the current value of something that changed). Don't compute dates yourself — pass the expression and let the daemon resolve it against one clock. The window filters before the confidence verdict, so a scoped verdict describes the scoped set, and the same grammar works on scope: "memory" and scope: "history". Hits carry created_at, so a result's place in time is always visible.
• Use get_node / traverse to pull the reasoning around a hit (e.g. a Decision and the Principle it stands on).
• For history: timeline walks a node's replaces chain oldest-first, each retired generation carrying the note that explains why it was replaced. audit pages the mutation journal — "what changed while I was away", "who wrote this".
• For whole-graph work: list_nodes pages complete nodes (full bodies, filters by type/status/tag) — the lossless read for reviews and exports like a decisions.md; update_nodes / add_notes batch a curation sweep or a multi-note capture into one call (same per-item dupe checks and warnings).
• list_open shows the live worklist (open Problems and Intents) — check it when picking up work.