Memory

Memory System Skill

Thin router across the tiered memory system. Each operation lives in a focused sub-skill (ADR-063 memory-skill decomposition); this router points you at the right one so a caller loads only the surface it needs.

When to Use This Skill

See the context-gather skill for the multi-source pre-work gather and its references/context-retrieval.md for the source-priority strategy (Issue #2103 folded the former context-retrieval agent into that reference; #5574 moved it here from the retired knowledge-graph skill).

Related Sub-Skills

The router delegates every operation to a focused sub-skill. Load the one that matches your task; each carries a smaller context than the full memory surface.

Triggers

Use this skill when the user says:

• search memory for semantic search across tiers (routes to memory-search)
• check memory health for system status (routes to memory-maintenance)
• extract episode from session for session replay (routes to memory-reflexion)
• memory-first gate before changing an existing system (routes to memory-gate)
• consolidate memory for a periodic durable/dated review and index tidy (routes to memory-consolidate)

Decision Tree

What do you need?
│
├─► Current facts, patterns, or rules?
│   └─► memory-search sub-skill (Tier 1)
│
├─► About to change existing code, a constraint, or a protocol?
│   └─► memory-gate sub-skill (search the "why" first, BLOCKING)
│
├─► Record what happened in a completed session?
│   └─► memory-reflexion sub-skill (Tier 2 episode extraction)
│
├─► Store new factual knowledge directly?
│   └─► Write a Serena memory (mcp__serena__write_memory), then
│       curating-memories to keep it accurate
│
├─► Check health, count tokens, benchmark, or improve graph density?
│   └─► memory-maintenance sub-skill
│
├─► Periodic pass: separate durable from dated, merge overlaps, tidy the index?
│   └─► memory-consolidate sub-skill
│
└─► Not sure which tier?
    └─► Start with memory-search (Tier 1), escalate if insufficient

For deeper guidance on picking a tier, see references/tier-selection-guide.md.

Progressive Disclosure

The memory system uses progressive disclosure: list names, read details, deep dive on cross-references. This prevents loading a large memory when a small slice answers the query (up to an 87% token reduction). The memory-search sub-skill owns the Tier 1 index-then-read flow; start there.

Atomic files plus indexes are deliberate: there are no embeddings, so the filename is the activation vocabulary. Do NOT consolidate atomic memories to cheapen listing; it breaks discovery and cross-links. On add, update the domain *-index so the next agent finds the memory by name.

Serena Write Conventions

These conventions govern writing a new Serena memory and registering it in its domain index. They are the load-bearing rules absorbed from the former memory agent (Issue #2102). For obsolete-marking, deduplication, and bidirectional linking, use the curating-memories skill.

Naming

• File name: [domain]-[descriptive-name].md, lowercase with hyphens (for example pr-review-security.md).
• Entity ID inside the file: {domain}-{description}, kebab-case, no prefix (for example pr-enum-001). File name and entity ID are separate; do not conflate them.

Index-Table Insertion (hazard)

Domain index files (skills-*-index.md) contain ONLY a two-column table. When you add a memory you MUST insert AFTER the last existing DATA row, never after the header or the delimiter:

| Keywords | File |    <-- header row
|----------|------|    <-- delimiter row (SKIP THIS)
| existing | file |    <-- data rows; insert after the LAST one

Inserting after the header or delimiter corrupts the table and breaks name-based discovery for every reader. Do not add titles, statistics, or prose to an index file.

Relations (encoded in the memory body)

## Relations

- **supersedes**: [previous-file-name]
- **depends_on**: [dependency-file-name]
- **related_to**: [related-file-name]

supersedes (new version replaces old), depends_on (requires another memory), related_to (loose association).

Source Tracking (required on every observation)

[YYYY-MM-DD] [Source]: [Observation content]

Source forms: [agent-name], [doc:path], [decision:ADR-NNN], [user], [ext:source]. Reasoning over actions: record WHY a choice was made, not just WHAT was done.

Conflict Resolution

When observations contradict, prefer the most recent, create a new memory with a supersedes relation, and prefix with [REVIEW] when accuracy is uncertain.

Storage Locations

Anti-Patterns

See Also

Router-owned references, shared across the memory sub-skills. Operation-specific references travel with their sub-skill (ADR-063).

Verification

Verification checklist:

• Correct sub-skill selected from the decision tree
• Operation ran through the sub-skill, not inline in the router

Process

Phase 1: Route

Match the request to a sub-skill using the decision tree and When-to-Use matrix.

Phase 2: Delegate

Load the selected sub-skill and run its operation against the canonical scripts.

Phase 3: Report

Return structured results to the caller with source attribution.

Scripts

The router owns the canonical memory scripts. Sub-skills delegate to these paths (ADR-063); the router does not duplicate them.

Invoke via the portable root form:

"${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/memory/scripts/test_memory_health.py" --format table

Related Skills