# Memory Protocol

> Persistent cross-session memory using Memento MCP knowledge graph (mcp__memento__* tools). Recall-before-acting: search memory before starting tasks, on errors, and when receiving corrections. Multi-dimensional search: two queries per recall event (technical topic + process/workflow learnings). Store-after-discovery: persist solutions, conventions, and corrections immediately. Three-step recall: search, open_nodes, traverse relations. WORKING_STATE.md for crash recovery. Self-reminder protocol every 5-10 messages. Activate on task start, errors, corrections, session boundaries, or explicit memory requests. See references/agents-md-setup.md for AGENTS.md integration.

- Skill: `jwilger/memory-protocol` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add jwilger/memory-protocol`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jwilger/memory-protocol/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: CC0-1.0
- Author: jwilger (https://skillmd.com/u/jwilger)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/jwilger/memory-protocol

---


# Memory Protocol

**Value:** Feedback -- accumulated knowledge creates compound feedback loops
across sessions. What you learn today should accelerate tomorrow's work.

## Purpose

Teaches the agent to systematically store and recall project knowledge across
sessions using the Memento MCP knowledge graph.

Your long-term memory (training data) and short-term memory (context window)
are excellent, but mid-term memory for project-specific knowledge outside the
current context is poor. Memento addresses this gap by persisting a knowledge
graph across sessions and projects.

Solves: context loss between sessions, repeated debugging of known issues,
rediscovery of established conventions, repeated user corrections for the
same mistakes.

## Practices

### Verify Memento MCP Availability

Before proceeding, confirm that Memento MCP tools are available
(`mcp__memento__semantic_search`, `mcp__memento__create_entities`, etc.).

If Memento MCP tools are NOT available, **stop and inform the user:**

> "The memory-protocol skill requires Memento MCP, but I don't have access
> to mcp__memento__* tools. To enable memory persistence, install and
> configure the Memento MCP server
> (https://github.com/gannonh/memento-mcp). Without it, this skill cannot
> function and I will proceed without cross-session memory."

Then continue working without memory protocol practices — do not attempt
a file-based workaround.

### Anti-Pattern: File-Based Memory When Memento Is Available

When this skill is active and Memento MCP tools are available, do NOT use any
file-based memory system for cross-session knowledge storage. This includes
the built-in `memory/` directory, `MEMORY.md` index, auto-memory features, or
any other file-based persistence mechanism. All cross-session memory storage
goes through Memento MCP tools exclusively.

File-based memory systems and Memento serve the same purpose — persisting
knowledge across sessions. Using both creates split-brain: knowledge stored in
files is invisible to Memento searches, and knowledge in Memento is invisible
to file reads. Pick one. When this skill is loaded, Memento is the one.

Note: this does NOT prohibit `WORKING_STATE.md` (which is crash-recovery
infrastructure, not cross-session memory) or project documentation files
(which are deliverables, not memory).

### Recall Before Acting — NON-NEGOTIABLE

Before starting any non-trivial task, recall relevant past knowledge. This
step is mandatory. Do not skip it because "this seems simple" or because
you believe you remember from a prior session — you do not retain memory
between sessions.

**Recall triggers:**
- Starting any non-trivial task
- Making architectural or design decisions
- Unsure about a project convention
- Before asking the user a question (it may already be answered)

For error-triggered recall, see the dedicated section below.

Apply Multi-Dimensional Search (next section) to every recall event.

**How to recall — all three steps are required:**

1. **Search:** `mcp__memento__semantic_search` — query describing the current
   work, limit 10. This returns summaries only — not the full picture.

2. **Open:** `mcp__memento__open_nodes` — for EVERY relevant entity returned
   by search, call `open_nodes` to retrieve the complete entity: all
   observations, all relations, full context. Do NOT skip this step.
   Semantic search returns partial data; the full entity often contains
   critical details (caveats, corrections, related warnings) that the search
   summary omits. Skipping `open_nodes` means you are acting on incomplete
   information.

3. **Traverse:** Follow `relations` on opened entities to discover connected
   knowledge. Call `open_nodes` on each related entity. Continue traversing
   until results are no longer relevant. Relations like `depends_on`,
   `contradicts`, `supersedes`, and `part_of` frequently point to information
   that changes how you should act — a fix that depends on a workaround, a
   convention that was later corrected, a decision that was superseded.

Skipping steps 2 or 3 defeats the purpose of a knowledge graph. A flat
keyword search could do step 1 alone — the graph's value is in the
connections between knowledge. If you only search and never open or traverse,
you will miss counter-information, corrections, and dependencies that would
have prevented mistakes.

**IMPORTANT:** Do NOT use `mcp__memento__read_graph` — memories span all
projects and the graph is too large to be useful.

### Multi-Dimensional Search

Every recall event requires **at least two searches** — not just one. The
reason: agents consistently search for the technical topic but miss process
and workflow learnings that would prevent repeated mistakes. Prior session
logs show patterns of the same user corrections recurring (team member usage,
ADR process, TDD workflow, build commands, approval process) because agents
only searched for the feature name and never for process learnings about the
*type of work* being done.

**Required search dimensions:**
1. **Technical query:** the specific topic, error, feature, or domain concept
2. **Process query:** learnings about this *type of work* — mistakes,
   corrections, workflow insights, conventions for this kind of task

| About to...                | Also search for...                                    |
|----------------------------|-------------------------------------------------------|
| Do TDD work                | "TDD process mistakes", "ping-pong pairing lessons"   |
| Spawn agents/subagents     | "team member usage", "agent coordination issues"      |
| Debug an error             | "debugging workflow mistakes", prior error occurrences |
| Create an ADR              | "ADR process", "ADR mistakes"                         |
| Commit/PR/merge            | "commit conventions", "approval process"              |
| Any process step           | "[process] corrections", "[process] lessons learned"  |

This table is non-exhaustive. The principle: always ask "what have I learned
about doing *this kind of thing*?" in addition to "what do I know about
*this specific thing*?"

### Error-Triggered Recall — NON-NEGOTIABLE

This is separated from the general recall triggers because error-triggered
recall is where agents most consistently fail to search memory. The pattern:
an error occurs, the agent immediately starts debugging from scratch, burns
through multiple fix attempts, and only much later (if ever) thinks to check
whether this problem was solved before. This wastes time and repeats past work.

**Fires on:**
- Any error message, stack trace, or unexpected behavior
- Any test failure
- Any hook failure (pre-commit, CI, linter)
- Any process correction from the user ("no, you should do X instead")
- Any issue not resolved by the immediate obvious fix

**The rule:** Search memory BEFORE attempting a fix. Not after three failed
attempts. Not after spending 10 minutes debugging. Before.

**Apply multi-dimensional search:**
- Search for the specific error message or symptom
- Search for process learnings about this type of situation (e.g., "debugging
  Node.js module errors", "test failure patterns in this project")

**If you've been corrected by the user:** search for whether this correction
(or a similar one) was already stored in memory. If it was, you failed to
recall — acknowledge this and reinforce the memory with updated context.

### Store After Discovery

After solving a non-obvious problem, learning a convention, or making a
decision, store it immediately — do not wait, you will lose context.

**What to store:**
- Solutions to non-obvious problems (with error message as search term)
- Project conventions discovered while working
- Architectural decisions and their rationale
- User preferences for workflow or style
- Tool quirks and workarounds
- User corrections — especially process corrections

**What not to store:**
- Obvious or well-documented information
- Temporary values or session-specific facts
- Verbose narratives (keep entries concise and searchable)

Always search before creating — `mcp__memento__semantic_search` first. If a
related entity exists, extend it with `mcp__memento__add_observations` rather
than creating a duplicate.

**Entity naming:** `<Descriptive Name> <Project> <YYYY-MM>`
(e.g., "Cargo Test Timeout Fix TaskFlow 2026-01")

**Observation format:**
- Project-specific: `"Project: <name> | Path: <path> | Scope: PROJECT_SPECIFIC | Date: YYYY-MM-DD | <insight>"`
- General: `"Scope: GENERAL | Date: YYYY-MM-DD | <insight>"`
- Each observation must be a complete, self-contained statement

**Relationships — ALWAYS create at least one** after creating or updating an
entity. Use `mcp__memento__create_relations` to link to related entities.
Active-voice relation types: `implements`, `extends`, `depends_on`,
`discovered_during`, `contradicts`, `supersedes`, `validates`, `part_of`,
`related_to`, `derived_from`.

See `references/memento-protocol.md` for entity type table, observation
format guide, relationship table, traversal strategy, and examples.

### Subagent Responsibilities

This protocol applies to both the main agent AND any subagents to which work
is delegated. When instructing a subagent, include the memory protocol
requirement explicitly.

Subagents must:
- Search Memento before beginning their delegated task
- Apply multi-dimensional search (technical + process queries)
- Store any new insights discovered during their work
- Create relationships to existing entities when applicable

### Factory Memory

When running inside a pipeline or factory workflow, the pipeline stores
operational learnings in `.factory/memory/` to optimize future runs.

**Types of learnings tracked:**
- **CI patterns:** Which change types cause CI failures
- **Rework patterns:** Common rework causes by gate
- **Pair effectiveness:** Which engineer pairs are most effective in which domains
- **Domain hotspots:** Files and modules that frequently trigger findings

Standalone users can ignore factory memory; the standard memory practices
above remain unchanged.

### Prune Stale Knowledge

When you encounter a memory that is no longer accurate (API changed, convention
abandoned, bug fixed upstream), update or delete it. Wrong memories are worse
than no memories.

**Pruning triggers:**
- Memory contradicts current observed behavior
- Referenced files or APIs no longer exist
- Convention has clearly changed

### Store Before Context Loss

Before context compaction or at natural stopping points, **proactively store
any unsaved discoveries** before knowledge is lost to truncation. This is your
last chance before the knowledge evaporates.

### WORKING_STATE.md for Long-Running Sessions

For sessions lasting beyond a single task (pipeline runs, multi-slice TDD,
team coordination), maintain a WORKING_STATE.md file as insurance against
context compaction and crashes.

- **Location:** `.factory/WORKING_STATE.md` (pipeline mode) or project root
- **Update cadence:** after every significant state change
- **Read cadence:** at session start, after compaction, after any interruption

See `references/working-state.md` for the full format and examples.

### Self-Reminder Protocol

See `CONSTRAINT-RESOLUTION.md` in the template directory for the
consolidated self-reminder protocol (frequency, combined re-read list,
and post-compaction rules).

## Enforcement Note

Advisory in all modes. Recall and storage discipline are self-enforced.
The constraint against `read_graph` is gating: the tool will return
unhelpful results, acting as a natural deterrent.

**Hard constraints:**
- Recall before acting on non-trivial tasks: `[RP]` -- if Memento is
  unavailable, document the gap, continue without memory, inform user.

## Constraints

- **"At least two searches -- not just one"**: Two searches means two
  semantically different queries exploring different dimensions of the
  problem. Searching "auth middleware" and "authentication middleware" is
  one search with a synonym, not two searches. The spirit is: explore
  both the technical dimension (what technology/pattern) and the process
  dimension (what decisions/conventions exist).
- **"Non-trivial task" threshold**: A task is non-trivial if its outcome
  depends on project context -- conventions, prior decisions, architectural
  choices, or domain knowledge. A task is trivial if any competent agent
  would produce the same output regardless of project history. When in
  doubt, recall. The cost of an unnecessary search is seconds; the cost
  of missing relevant context is rework.

## Verification

After completing work guided by this skill, verify:

- [ ] Searched memory (semantic_search) before starting the task
- [ ] Searched for process/workflow learnings, not just technical topic (multi-dimensional search)
- [ ] Searched memory on every non-trivial error before attempting fixes
- [ ] Stored discoveries as Memento entities with structured observations
- [ ] Related entities linked with `create_relations`
- [ ] Subagents instructed to follow the memory protocol
- [ ] No stale or contradicted memories left uncorrected
- [ ] WORKING_STATE.md maintained for long-running sessions
- [ ] Self-reminder protocol followed (state re-read every 5-10 messages)

## Dependencies

This skill requires Memento MCP. For enhanced workflows, it integrates with:

- **debugging-protocol:** Search memory before starting the 4-phase investigation
- **user-input-protocol:** Store user answers to avoid re-asking the same questions
- **tdd:** Store test patterns and domain modeling insights between sessions
- **pipeline:** Pipeline controllers use WORKING_STATE.md and self-reminder to
  maintain role discipline across long autonomous runs
- **ensemble-team:** Team coordinators use self-reminder to prevent role drift
  during multi-agent sessions

Missing a dependency? Install with:
```
npx skills add jwilger/agent-skills --skill debugging-protocol
```