engram-memory

# 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_summary` - `mem_get_observation`, `mem_save_prompt`, `mem_current_project`, `mem_judge`, `mem_compare` - `mem_update`, `mem_review`, `mem_pin`, `mem_unpin`, `mem_suggest_topic_key` - `mem_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: 1. First call `mem_context` — checks recent session history (fast, cheap) 2. If not found, call `mem_search` with relevant keywords (FTS5 full-text search) 3. If you find a match, use `mem_get_observation` for 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: 1. IMMEDIATELY call `mem_session_summary` with the compacted summary content — this persists what was done before compaction 2. Then call `mem_context` to recover any additional context from previous sessions 3. 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. **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.