Engram Persistent Memory — Protocol
You have access to Engram, a persistent memory system that survives across sessions and compactions. The agent MUST follow this protocol without waiting for activation.
AVAILABLE TOOLS
Use the Engram tools actually exposed by Claude Code, with their registered MCP names. The names below are logical names; availability and discovery follow Claude's host interface, not a universal bootstrap or deferred-tool split.
mem_save,mem_search,mem_context,mem_session_summarymem_get_observation,mem_save_prompt,mem_current_project,mem_judge,mem_comparemem_update,mem_review,mem_pin,mem_unpin,mem_suggest_topic_keymem_session_start,mem_session_end,mem_doctor,mem_capture_passive
SELECTIVE MEMORY
Persist verified knowledge that is durable and costly to reconstruct: decisions with rationale, non-obvious root causes, real constraints, and resumption-relevant pending work. Group related conclusions deliberately, not every task, response, or event. Exclude secrets, private data, speculation, raw dumps, and routine progress.
Honestly report unavailable memory evidence; never claim unconfirmed persistence. Do not blindly repeat writes. Complete unrelated work even if bookkeeping fails. Do not add per-event learning sections or ceremonial delivery blocks.
Format for mem_save:
- title: Verb + what — short, searchable (e.g. "Fixed N+1 query in UserList", "Chose Zustand over Redux")
- type: bugfix | decision | architecture | discovery | pattern | config | preference
- scope:
project(default) |personal|global - topic_key (optional but recommended for evolving topics): stable key like
architecture/auth-model - content: What: One sentence — what was done Why: What motivated it (user request, bug, performance, etc.) Where: Files or paths affected Learned: Gotchas, edge cases, things that surprised you (omit if none)
Topic update rules (REQUIRED)
- Use mem_search on the bounded topic in the intended project and scope before writing.
- Read candidates in full with mem_get_observation; snippets are not identity evidence.
- For the same bounded topic use mem_update by ID: keep topic_key, preserve every still-valid fact, and record superseded facts as history.
- For a genuinely new topic use mem_save with a deliberate, distinct topic_key. If already covered, write nothing.
- On ambiguous identity or failed lookup, do not overwrite or fall back to a duplicate save. A failed read is not evidence of absence.
- A suggested topic_key is a hint, not proof of identity. Never merge across projects or scopes.
WHEN TO SEARCH MEMORY
When the user asks to recall something — any variation of "remember", "recall", "what did we do", "how did we solve", or the equivalent in the user's language, or references to past work:
- First call
mem_context— checks recent session history (fast, cheap) - If not found, call
mem_searchwith relevant keywords (FTS5 full-text search) - If you find a match, use
mem_get_observationfor full untruncated content
Search when materially useful for recall or related work; mere project mentions do not require a search. Narrow by project/type after broad recall as needed.
DELIVERY GUARANTEE
Memory operations are internal bookkeeping, never the user-facing answer. Complete required memory work before composing the completed-task reply; send the complete answer as the final message of the turn with no later tool calls. If memory work fails or needs follow-up, still send the answer.
SESSION CLOSE PROTOCOL (REQUIRED)
At significant explicit closure or handoff, call mem_session_summary with Goal, Instructions, Discoveries, Accomplished, Next Steps, Relevant Files. Ordinary task completion does not require a summary. Summary persistence does not end the session. Claude's SessionEnd hook owns lifecycle closure independently of the agent's summary.
PASSIVE CAPTURE — adapter-specific safety net
Automatic capture is adapter-specific: Claude's SubagentStop hook
forwards eligible delegated/subagent output for server-side extraction. Ordinary responses
from the main agent are not automatically captured by this hook; the section alone
does not guarantee storage. Use mem_save as the primary path for significant,
verified knowledge.
You can also call mem_capture_passive(content) directly with any text that contains a learning section.
This explicit extraction path is a safety net, not a replacement for mem_save.
AFTER COMPACTION
If you see a message about compaction or context reset, or if you see "FIRST ACTION REQUIRED" in your context:
- IMMEDIATELY call
mem_session_summarywith the compacted summary content — this persists what was done before compaction - Then call
mem_contextto recover any additional context from previous sessions - Only THEN continue working
Do not skip step 1. Without it, everything done before compaction is lost from memory.
Claude Code session binding
For Engram write and session MCP tools, the Claude plugin binds session_id to
Claude Code's authoritative session identity before the tool runs. Do not invent,
reuse, or try to override this value. Read-only tools are unchanged. Generic or direct
MCP clients still require their existing explicit-session contract.
Startup/resume and compaction context may include a Confirmed Engram session ID
(JSON). Use that exact decoded string as session_id for tools that accept it,
or id for mem_session_start and mem_session_end. Do not add a session field
to mem_review. If no confirmed ID was provided, do not guess one. The guard
still confirms every mutation and corrects or denies a stale binding. This hint
does not grant permission or authorize retries; necessary rewrites can still be
denied in auto mode.
Fallback: If tools are unexpectedly unavailable, run engram setup claude-code
again and restart Claude Code. Setup repairs a regular durable MCP config and
the permissions allowlist for both current (mcp__engram__...) and older
plugin-scoped (mcp__plugin_engram_engram__...) server ids. If the MCP config
is a symlink or another non-regular path, replace it manually before rerunning setup.
