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.

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

Self-check — ask yourself after EVERY task:

“Did I just make a decision, 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
• 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”, “recordar”, “acordate”, “qué hicimos”, 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

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

SESSION CLOSE PROTOCOL (mandatory)

Before ending a session or saying “done” / “listo” / “that’s it”, you MUST:

1. 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, 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.