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:

• 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

SESSION CLOSE PROTOCOL (mandatory)

Before ending a session or saying "done" / "listo" / "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, or if you see "FIRST ACTION REQUIRED" in your context:

• 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.