Engram Persistent Memory — Protocol
You have access to Engram, a persistent memory system that survives across sessions and compactions.
This protocol is MANDATORY and ALWAYS ACTIVE — not something you activate on demand.
AVAILABLE TOOLS
Core tools are loaded automatically at session start by the UserPromptSubmit hook.
They are available immediately — no manual ToolSearch needed.
mem_save, mem_search, mem_context, mem_session_summary
mem_get_observation, mem_save_prompt, mem_current_project, mem_judge, mem_compare
Deferred tools (use ToolSearch only if needed):
mem_update, mem_review, mem_pin, mem_unpin, mem_suggest_topic_key
mem_session_start, mem_session_end, mem_doctor, mem_capture_passive
Fallback: If tools are unexpectedly unavailable, run engram setup codex
again and restart Codex. Setup repairs the durable MCP config and
permissions allowlist for the mcp__engram__... server ids.
PROACTIVE SAVE TRIGGERS (mandatory — do NOT wait for user to ask)
Call mem_save IMMEDIATELY and WITHOUT BEING ASKED after any of these:
After decisions or conventions
- Architecture or design decision made
- Team convention documented or established
- Workflow change agreed upon
- Tool or library choice made with tradeoffs
After completing work
- Bug fix completed (include root cause)
- Feature implemented with non-obvious approach
- Notion/Jira/GitHub artifact created or updated with significant content
- Configuration change or environment setup done
After discoveries
- Non-obvious discovery about the codebase
- Gotcha, edge case, or unexpected behavior found
- Pattern established (naming, structure, convention)
- User preference or constraint learned
After user confirmation or rejection
- User confirms a recommendation you made ("go with that", "let's do that", "sounds good", "agreed", "perfect", or the equivalent in the user's language)
- User rejects an option or approach ("no, better X", "not that one", or the equivalent in the user's language)
- User expresses a preference ("I prefer X over Y", "always do it this way", or the equivalent in the user's language)
- User makes a decision after you presented tradeoffs or options
- A discussion concludes with a clear direction chosen — even if the agent proposed it
Self-check — ask yourself after EVERY task:
"Did I or the user just make a decision, confirm a recommendation, express a preference, fix a bug, learn something non-obvious, or establish a convention? If yes, call mem_save NOW."
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 (mandatory)
- Different topics MUST NOT overwrite each other (example: architecture decision vs bugfix)
- If the same topic evolves, call
mem_save with the same topic_key so memory is updated (upsert) instead of creating a new observation
- If unsure about the key, call
mem_suggest_topic_key first, then reuse that key consistently
- If you already know the exact ID to fix, use
mem_update
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_search with relevant keywords (FTS5 full-text search)
- If you find a match, use
mem_get_observation for full untruncated content
Also search memory PROACTIVELY when:
- Starting work on something that might have been done before
- The user mentions a topic you have no context on — check if past sessions covered it
- The user's FIRST message references the project, a feature, or a problem — call
mem_search with keywords from their message to check for prior work before responding
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 (mandatory)
Before ending a session or saying "done" / "that's it", you MUST:
- Call
mem_session_summary with this structure:
Goal
[What we were working on this session]
Instructions
[User preferences or constraints discovered — skip if none]
Discoveries
- [Technical findings, gotchas, non-obvious learnings]
Accomplished
- [Completed items with key details]
Next Steps
- [What remains to be done — for the next session]
Relevant Files
- path/to/file — [what it does or what changed]
This is NOT optional. If you skip this, the next session starts blind.
AFTER COMPACTION
If you see a message about compaction or context reset:
- IMMEDIATELY call
mem_session_summary with the compacted summary content — this persists what was done before compaction
- Then call
mem_context to 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.
All core tools are loaded automatically by the hook at session start. If they are unexpectedly missing, rerun engram setup codex and restart Codex.
1---2name: engram-memory3description: "ALWAYS ACTIVE — Persistent memory protocol. You MUST save decisions, conventions, bugs, and discoveries to engram proactively. Do NOT wait for the user to ask."4metadata:5 source: https://skillmd.com/skills/gentleman-programming-engram/engram-memory6---78# Engram Persistent Memory — Protocol910You have access to Engram, a persistent memory system that survives across sessions and compactions.11This protocol is MANDATORY and ALWAYS ACTIVE — not something you activate on demand.1213## AVAILABLE TOOLS1415Core tools are loaded automatically at session start by the UserPromptSubmit hook.16They are available immediately — no manual ToolSearch needed.1718- `mem_save`, `mem_search`, `mem_context`, `mem_session_summary`19- `mem_get_observation`, `mem_save_prompt`, `mem_current_project`, `mem_judge`, `mem_compare`2021Deferred tools (use ToolSearch only if needed):22- `mem_update`, `mem_review`, `mem_pin`, `mem_unpin`, `mem_suggest_topic_key`23- `mem_session_start`, `mem_session_end`, `mem_doctor`, `mem_capture_passive`2425**Fallback**: If tools are unexpectedly unavailable, run `engram setup codex`26again and restart Codex. Setup repairs the durable MCP config and27permissions allowlist for the `mcp__engram__...` server ids.2829## PROACTIVE SAVE TRIGGERS (mandatory — do NOT wait for user to ask)3031Call `mem_save` IMMEDIATELY and WITHOUT BEING ASKED after any of these:3233### After decisions or conventions34- Architecture or design decision made35- Team convention documented or established36- Workflow change agreed upon37- Tool or library choice made with tradeoffs3839### After completing work40- Bug fix completed (include root cause)41- Feature implemented with non-obvious approach42- Notion/Jira/GitHub artifact created or updated with significant content43- Configuration change or environment setup done4445### After discoveries46- Non-obvious discovery about the codebase47- Gotcha, edge case, or unexpected behavior found48- Pattern established (naming, structure, convention)49- User preference or constraint learned5051### After user confirmation or rejection52- User confirms a recommendation you made ("go with that", "let's do that", "sounds good", "agreed", "perfect", or the equivalent in the user's language)53- User rejects an option or approach ("no, better X", "not that one", or the equivalent in the user's language)54- User expresses a preference ("I prefer X over Y", "always do it this way", or the equivalent in the user's language)55- User makes a decision after you presented tradeoffs or options56- A discussion concludes with a clear direction chosen — even if the agent proposed it5758### Self-check — ask yourself after EVERY task:59> "Did I or the user just make a decision, confirm a recommendation, express a preference, fix a bug, learn something non-obvious, or establish a convention? If yes, call mem_save NOW."6061Format for `mem_save`:62- **title**: Verb + what — short, searchable (e.g. "Fixed N+1 query in UserList", "Chose Zustand over Redux")63- **type**: bugfix | decision | architecture | discovery | pattern | config | preference64- **scope**: `project` (default) | `personal` | `global`65- **topic_key** (optional but recommended for evolving topics): stable key like `architecture/auth-model`66- **content**:67 **What**: One sentence — what was done68 **Why**: What motivated it (user request, bug, performance, etc.)69 **Where**: Files or paths affected70 **Learned**: Gotchas, edge cases, things that surprised you (omit if none)7172### Topic update rules (mandatory)7374- Different topics MUST NOT overwrite each other (example: architecture decision vs bugfix)75- If the same topic evolves, call `mem_save` with the same `topic_key` so memory is updated (upsert) instead of creating a new observation76- If unsure about the key, call `mem_suggest_topic_key` first, then reuse that key consistently77- If you already know the exact ID to fix, use `mem_update`7879## WHEN TO SEARCH MEMORY8081When the user asks to recall something — any variation of "remember", "recall", "what did we do",82"how did we solve", or the equivalent in the user's language, or references to past work:831. First call `mem_context` — checks recent session history (fast, cheap)842. If not found, call `mem_search` with relevant keywords (FTS5 full-text search)853. If you find a match, use `mem_get_observation` for full untruncated content8687Also search memory PROACTIVELY when:88- Starting work on something that might have been done before89- The user mentions a topic you have no context on — check if past sessions covered it90- The user's FIRST message references the project, a feature, or a problem — call `mem_search` with keywords from their message to check for prior work before responding9192## DELIVERY GUARANTEE9394Memory 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.9596## SESSION CLOSE PROTOCOL (mandatory)9798Before ending a session or saying "done" / "that's it", you MUST:991. Call `mem_session_summary` with this structure:100101## Goal102[What we were working on this session]103104## Instructions105[User preferences or constraints discovered — skip if none]106107## Discoveries108- [Technical findings, gotchas, non-obvious learnings]109110## Accomplished111- [Completed items with key details]112113## Next Steps114- [What remains to be done — for the next session]115116## Relevant Files117- path/to/file — [what it does or what changed]118119This is NOT optional. If you skip this, the next session starts blind.120121## AFTER COMPACTION122123If you see a message about compaction or context reset:1241. IMMEDIATELY call `mem_session_summary` with the compacted summary content — this persists what was done before compaction1252. Then call `mem_context` to recover any additional context from previous sessions1263. Only THEN continue working127128Do not skip step 1. Without it, everything done before compaction is lost from memory.129All core tools are loaded automatically by the hook at session start. If they are unexpectedly missing, rerun `engram setup codex` and restart Codex.