normal

Engram — durable project memory (MCP server: engram)

This project keeps a local, user-owned knowledge graph of its reasoning: Decisions and their reasons, Principles, Cautions that bit us, Problems and Resolutions, Insights, open Intents, Anchors that cluster them. Not code structure — the code holds that. What good capture buys: the next session starts already knowing why things are the way they are, and the user sees and curates everything in the pane.

Recall. Call the brief tool once at session start and read it before planning — unless the session already opens with an injected "# Engram brief" (a session-start hook provides it); then read that and skip the tool call. If the brief's first line says the session is bound by fallback — or it names a project that is not your workspace (a client that never answered MCP roots) — call brief again with project set to this workspace's ABSOLUTE path: it rebinds the session and returns the right project's brief. Before any non-trivial decision, search the graph; hits carry their 1-hop neighbors — read conflicts-with / replaces edges first, and pass parents/children to get_node when you need the reasoning chain. For history: timeline walks a node's replaces chain, audit pages the mutation journal. For whole-graph reviews or exports (a decisions.md), page list_nodes — complete nodes with full bodies; batch cleanups and multi-note captures go through update_nodes / add_notes. A hit marked stale: true has decayed trust: verify it before relying on it, and refresh it with update_node if it's still accurate.

Capture. Capture the load-bearing knowledge: Decisions with reasons, Principles and conventions, Cautions and gotchas, resolved Problems, selective non-obvious Insights, and Intents worth surviving the session. Skip anything the code or docs already state verbatim. Node type is one of exactly 9: Decision, Principle, Caution, Problem, Resolution, Insight, Intent, Anchor, Tombstone — a record that knowledge was deliberately removed; don't resurrect it (call describe_ontology if this graph runs a custom set). Write shapes: add_note {"type": "Decision", "title": "...", "body": "..."}; link {"from": "<id>", "to": "<id>", "type": "because"}; add_notes {"notes": [...]} items carry NO links — link the returned ids in a second pass. If describe_ontology lists custom fields, pass "fields": {"name": value} — refusals teach the roster; follow them. Connect notes with link using sentence-shaped edges (because / answers / about / builds-on / replaces / conflicts-with / needs; about targets Anchors only). Every write's response is a verdict, not a receipt: on {matched, created: false} merge into the match with update_node instead of duplicating; on warnings you are near contradicted or superseded canon — check it before piling on; on suspects the write queued unjudged look-alike pairs — judge each immediately with resolve_suspect (conflict | replaces | dismiss) and tell the user when one genuinely contradicts standing canon (the one exception to silent capture). When several notes share a subject, create/reuse an Anchor and attach them — anchors never accrue by themselves. Batch the writing at natural stopping points, never the noticing: every real decision gets captured unprompted — a feature request usually hides one (library picked, shape chosen, tradeoff accepted). Don't narrate writes. Never store secrets, credentials, or volatile implementation detail (line numbers, transient state).

Maintain. Judge the brief's suspected conflicts with resolve_suspect: contradiction → conflict; fresher restatement → replaces; complementary (a Resolution implementing an Intent) → dismiss, then ensure the answers edge exists. When a Resolution answers a Problem/Intent, also set that node's status to resolved. list_drift names nodes whose code_refs no longer exist: fix the paths via update_node and re-check the claim itself.