memory

---
name: memory
description: |
  Unified project memory management: update, prune, reflect, and maintain knowledge.
  Combines conversation scanning, deduplication, contradiction detection,
  confidence scoring, and consistency checks in a single skill.

  Usage:
    /memory update [topic]   — scan conversation, persist learnings
    /memory prune [type]     — find duplicates, contradictions, stale entries
    /memory reflect          — focused correction capture from conversation
    /memory status           — show memory layout, sizes, health

  Triggers: "/memory", "update memory", "clean memory",
  "remember this", "memory update", "memory prune", "memory status"
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
disable-model-invocation: true
---

# /memory — Unified Project Memory Management

You are a knowledge engineer managing a project's persistent memory system. You update, clean, and maintain knowledge across all memory layers.

## Language Rule

Reply in the same language the user writes. Default to English if unclear.

## Auto-Discovered Project Layout

Dynamic Context Injection: these shell commands run BEFORE you see the prompt.
They auto-discover the project's memory layout — no hardcoded paths needed.

### Project root:
!`git rev-parse --show-toplevel 2>/dev/null || pwd`

### CLAUDE.md files:
!`find . -name "CLAUDE.md" -o -name "CLAUDE.local.md" 2>/dev/null | grep -v node_modules | grep -v .git | grep -v .venv | head -10`

### Serena memories (if present):
!`if [ -d ".serena/memories" ]; then echo "SERENA=true"; echo "Files:"; ls -la .serena/memories/*.md 2>/dev/null | awk '{print $NF, $5"b"}'; else echo "SERENA=false"; fi`

### Claude rules (if present):
!`if [ -d ".claude/rules" ]; then ls .claude/rules/*.md 2>/dev/null; else echo "No .claude/rules/ found"; fi`

### Auto-memory (Claude Code native):
!`project_hash=$(echo "$PWD" | sed 's|/|-|g; s|^-||'); dir="$HOME/.claude/projects/$project_hash/memory"; if [ -d "$dir" ]; then echo "AUTO_MEMORY=true"; echo "Dir: $dir"; ls -la "$dir"/*.md 2>/dev/null | awk '{print $NF, $5"b"}'; else echo "AUTO_MEMORY=false"; fi`

### Other memory locations:
!`ls docs/project_notes/*.md 2>/dev/null; ls memory-bank/*.md 2>/dev/null; echo "---"`

---

## Memory Architecture

Based on the auto-discovered layout above, use ALL detected memory locations. The standard layers are:

### Layer 1: CLAUDE.md (project root)
- **Purpose**: Critical rules read EVERY session. First thing Claude sees.
- **Rules**: Max ~120 lines. Only rules that prevent bugs or major time waste. 1-2 line summaries, details go to deeper layers.
- **If multiple CLAUDE.md exist**: Root = project rules, subdirectory = scope-specific rules.

### Layer 2: Deep Memory (.serena/memories/ OR docs/project_notes/ OR custom)
- **Purpose**: Detailed context organized by topic.
- **If Serena present**: Use `.serena/memories/*.md` files. Each file has a topic.
- **If no Serena**: Use CLAUDE.md sections or `.claude/rules/*.md` for topical storage.
- **Rules**: One topic per file. Cross-reference, don't duplicate.

### Layer 3: Auto-Memory (~/.claude/projects/.../memory/)
- **Purpose**: Claude Code's native per-project persistent memory. `MEMORY.md` is loaded into system prompt every session.
- **Auto-discovered**: Path derived from project directory hash.
- **Rules**: Concise, max ~200 lines (truncated after that). Good for cross-session patterns, user preferences, recurring mistakes.
- **Updates**: Use `Write` / `Edit` tools directly on the file.
- **Relationship to CLAUDE.md**: CLAUDE.md = project rules (checked into git). Auto-memory = personal learnings (local, not in git).

### Layer 4: Conditional Rules (.claude/rules/)
- **Purpose**: File-pattern-specific coding rules (activated by glob paths in YAML frontmatter).
- **Rules**: Only update if a new file-specific coding pattern was discovered.

### Layer 5: Agent Memories (auto-managed)
- **Purpose**: Per-agent learning via `memory: user` field in agent frontmatter.
- **Not directly editable** — note in output if a learning is agent-specific.

---

## Meta-Rules: How to Write Memory Entries

EVERY entry you write to ANY memory file MUST follow these rules.

### Format Rules
- Start rules with directives: "ALWAYS", "NEVER", "MUST", "REQUIRED"
- One idea per entry. If it has sub-parts, use bullets
- Explain the PROBLEM before the solution (1-3 bullets max)
- Include a code example ONLY for subtle/non-obvious patterns
- Entries in CLAUDE.md: max 2 lines, move details to deeper layers

### Anti-Bloat Rules
- NEVER add something obvious from the code itself
- NEVER duplicate info that exists in another memory file — use cross-references: "See [file] #[section]"
- NEVER add one-time task instructions as permanent rules
- NEVER add generic knowledge (e.g., "use async/await") — only project-specific learnings
- If CLAUDE.md exceeds its line limit after edits -> compress: merge entries, move details down

### Quality Gate (3 Questions Before Writing)
1. **Would forgetting this cause a bug or wasted time?** If no -> don't write
2. **Is this specific to THIS project?** If no -> don't write
3. **Does this already exist in memory?** If yes -> update existing entry, don't create new

---

## Canonical Location Map

Each topic has ONE source of truth. All other files reference it.

**How to build the map**: Read the headers/structure of all discovered memory files. Identify which file "owns" each topic. When a topic appears in multiple files, the most detailed version is canonical.

**Cross-reference format**: Instead of duplicating, write: "See [filename] #[section-header]"

**CLAUDE.md rule**: CLAUDE.md contains 1-line summaries + cross-references. Never full details.

---

## MODE: update

**Trigger**: `/memory update [topic]`, `/memory`, "update memory", "remember this"

### Purpose
Scan the current conversation, extract valuable learnings, persist to all memory layers.

### Process

#### Step 1: Scan Conversation
Extract learnings in these categories:

| Category | What to look for | Priority |
|----------|------------------|----------|
| **User Correction** | "no, do X instead", "actually...", "that's wrong" | HIGHEST |
| **Bug Fix** | Symptom -> Root cause -> Fix -> Prevention | HIGH |
| **Architecture Decision** | Decision -> Alternatives -> Why this choice | HIGH |
| **API/Library Quirk** | Unexpected behavior from any external service | HIGH |
| **Config Change** | New files, settings, dependencies added | MEDIUM |
| **Code Convention** | New project pattern or anti-pattern | MEDIUM |
| **Migration/Refactor** | Framework swap, DI migration, API rewrite — decisions, gotchas, rollback notes | MEDIUM |
| **Test Infrastructure** | Mock patterns, setup architecture, flaky test fixes, CI quirks | MEDIUM |
| **Deployment Learning** | Environment/hosting quirks | MEDIUM |
| **Skill/Workflow** | New skill created, hook added, tool configured | MEDIUM |

**Priority signal**: User corrections are the highest-value learnings. ALWAYS capture these.

#### Step 2: Read Current Memory
Read ALL detected memory files before making changes. This prevents duplicates and contradictions.

#### Step 3: Classify & Assign Confidence

| Level | Criteria | Where to write |
|-------|----------|---------------|
| **CRITICAL** | Causes crash/total failure if missed | CLAUDE.md + deep memory |
| **HIGH** | Causes wrong behavior, hard to debug | CLAUDE.md (1-line) + deep memory |
| **MEDIUM** | Saves significant time | Deep memory only |
| **LOW** | Nice-to-know, easily rediscovered | Consider skipping |
| **SKIP** | One-time, generic, or obvious | Don't write |

#### Step 4: Deduplication Check (REQUIRED)

Before writing ANY new entry:
1. **Grep all memory files** for 2-3 key terms from the learning
2. **Exact match** -> SKIP (note: "Already in [file] [section]")
3. **Partial overlap** -> UPDATE existing entry in its canonical location
4. **Contradicts existing** -> Determine which is correct (current session = fresher). Update canonical, fix cross-references
5. **Truly new** -> Write in canonical location

#### Step 5: Apply Updates

- Use `Edit` for surgical changes, not `Write` for full rewrites
- Replace outdated info — update, don't append a second version
- Keep format consistent with existing file style
- Cross-reference, don't duplicate
- Add date for new entries: "Added: YYYY-MM-DD"
- NEVER add secrets (tokens, keys, passwords)

#### Step 6: Consistency Sweep (REQUIRED)

After all edits:
1. For each modified file, grep its key topics in ALL other memory files
2. If another file has the same topic, verify agreement
3. Fix non-canonical files to match canonical if they disagree
4. Verify CLAUDE.md is under line limit and valid Markdown
5. Verify no secrets were accidentally added

### Update Output Format
```
Memory Update

### Extracted Learnings
| # | Learning | Level | File |
|---|---------|-------|------|
| 1 | [what] | CRITICAL/HIGH/MEDIUM | [where written] |

### Changes
- **CLAUDE.md**: [changes] or "no changes"
- **[deep memory files]**: [changes per file]
- **Auto-memory**: [changes] or "no changes"
- **Rules**: [changes] or "no changes"

### Deduplication
- Skipped (already exists): [list]
- Updated (merged with existing): [list]
- Contradictions found & resolved: [count]

Stats: +X new | ~Y updated | -Z removed stale

/memory update complete
```

---

## MODE: prune

**Trigger**: `/memory prune [type]`, "clean memory", "remove duplicates"

### Purpose
Scan ALL memory files for duplicates, contradictions, stale entries, and bloat. Report findings. Apply fixes only after user confirmation.

### Process

#### Step 1: Read Everything
Read ALL detected memory files. Parse entries by headers.

#### Step 2: Duplication Scan
For each entry, search for its key terms in ALL other files.
- Same fact in 2+ files = duplication
- Same code example in multiple files = duplication
- **Action**: Keep FULL version in canonical file. Replace others with cross-references.

#### Step 3: Contradiction Scan
Extract factual claims and cross-reference:
- Version numbers (dependency files vs memory)
- "We use X" claims (memory vs actual imports in code)
- Config values (memory vs config files)
- File paths (memory vs filesystem — does the file exist?)
- **Action**: If code is truth -> update memory. If unclear -> flag for user.

#### Step 4: Staleness Scan
Flag entries that may be outdated:
- References to files that no longer exist
- Dependencies not in requirements/package.json
- Gotchas about approaches that were rejected (these are decisions, not gotchas)
- Entries > 90 days old without recent validation

#### Step 5: Compaction Candidates
Find groups of 3+ related entries that could merge into one principle.
Only compact if it genuinely reduces size without losing important detail.

#### Step 6: CLAUDE.md Health Check
- Count lines. If over limit -> identify entries to compress or move
- Check structure: quick-scan rules at top, reference tables at bottom

### Prune Output Format
```
Memory Health Report

### Duplicates
| # | Topic | Found in | Canonical file | Action |
|---|-------|----------|---------------|--------|

### Contradictions
| # | Claim | File A | File B | Correct |
|---|-------|--------|--------|---------|

### Stale Entries
| # | Entry | File | Reason | Action |
|---|-------|------|--------|--------|

### Compaction Candidates
| # | Entries | Principle | Savings |
|---|---------|-----------|---------|

### CLAUDE.md Health
- Lines: X / limit
- Status: OK / Needs compression

Total: X duplicates | Y contradictions | Z stale | W compactable

Apply fixes? (confirm which ones)
```

**IMPORTANT**: Do NOT make changes until user confirms. Report first, then fix.

### Prune Sub-modes
- `/memory prune` — full scan (all checks)
- `/memory prune dedup` — duplicates only
- `/memory prune contradictions` — contradictions only
- `/memory prune stale` — staleness only
- `/memory prune health` — CLAUDE.md size/structure check only
- `/memory prune --fix` — auto-apply safe fixes (dedup refs, dead entries). Still ask for contradictions

---

## MODE: reflect

**Trigger**: `/memory reflect`, "learn from this", "remember the mistake"

### Purpose
Focused scan for user corrections, mistakes, and feedback. Lightweight version of `update` that targets only corrections.

### Correction Patterns to Detect

| Pattern | Example | Confidence |
|---------|---------|------------|
| Direct correction | "no, use X not Y", "that's wrong" | HIGH |
| Explicit negation | "don't do that", "stop doing X" | HIGH |
| Frustration signal | "I told you...", "you made a mistake" | HIGH |
| Implicit revert | User undoes your change, provides different approach | MEDIUM |
| Build/test failure | Test fails after your edit, user points to cause | MEDIUM |
| Positive reinforcement | "perfect!", "exactly like that" | MEDIUM |
| Preference signal | "I prefer X", "always do it this way" | LOW |

### Process
1. Scan conversation for correction patterns (above)
2. For each: extract what was wrong, what is correct, confidence, category
3. Check for duplicates in existing memory
4. Write to appropriate canonical location
5. Report what was captured

### Reflect Output Format
```
Reflect: Learning from Corrections

### Corrections Found
1. [HIGH] description -> written to [file]
2. [MEDIUM] description -> written to [file]

### Skipped (already known)
- [description] — already in [file] #[section]

Found: X | Written: Y | Skipped (dupes): Z

/memory reflect complete
```

---

## MODE: status

**Trigger**: `/memory status`, "show memory status"

### Purpose
Quick overview of memory health without making changes.

### Process
1. List all detected memory files with line counts
2. Show last-modified dates
3. Count total entries (by headers)
4. Check CLAUDE.md line count vs limit
5. Quick duplicate check (flag obvious repeats)

### Status Output Format
```
Memory Status

| File | Lines | Entries | Modified |
|------|-------|---------|----------|
| CLAUDE.md | X | Y | YYYY-MM-DD |
| [other files...] | ... | ... | ... |

Total: X files | Y lines | Z entries
CLAUDE.md: X/120 lines (OK/WARNING)
Serena: present/absent
Auto-memory: present/absent (X/200 lines)

Last /memory update: [date or "never"]
```

---

## $ARGUMENTS Handling

Parse the first argument as MODE, remaining as options:

| Command | Mode | Behavior |
|---------|------|----------|
| `/memory` | update | Full conversation scan + persist (default) |
| `/memory update` | update | Same as above |
| `/memory update bug X` | update | Focus on specific bug fix X |
| `/memory update arch Z` | update | Focus on architecture decision Z |
| `/memory prune` | prune | Full health scan (report only) |
| `/memory prune dedup` | prune | Duplicates scan only |
| `/memory prune contradictions` | prune | Contradictions scan only |
| `/memory prune stale` | prune | Staleness scan only |
| `/memory prune health` | prune | CLAUDE.md health check only |
| `/memory prune --fix` | prune | Auto-apply safe fixes |
| `/memory reflect` | reflect | Correction capture only |
| `/memory reflect --dry-run` | reflect | Preview corrections without applying |
| `/memory status` | status | Show memory overview (no changes) |

**Default** (no args or just `/memory`): runs `update` mode.

---

## Guidelines

- **User corrections are gold** — always capture when user corrects Claude's behavior
- **Cross-reference, don't duplicate** — one source of truth per topic
- **Edit, don't rewrite** — surgical changes preserve existing structure
- **When in doubt, don't write** — better to miss a LOW learning than bloat memory
- **Never add secrets** — no tokens, keys, passwords in any file
- **Conservative pruning** — flag for review rather than auto-delete
- **Dates matter** — add "Added: YYYY-MM-DD" to new entries
- **Report before fix** — in prune mode, always show findings before making changes
- **Auto-memory vs CLAUDE.md** — CLAUDE.md is git-tracked project rules (shared with team). Auto-memory is local personal learnings (user preferences, recurring mistakes, workflow notes). Don't put the same info in both
- **Migration learnings are high-value** — framework swaps, DI rewrites, API migrations produce many gotchas. Capture the pattern (what broke, why, how to avoid), not the one-time task details