engram-memory

Files (1)

• SKILL.md

SKILL.md (first lines)

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

From Gentleman-Programming/engram, MIT.

More from Gentleman-Programming/engram