Memory pruner

memory-pruner

A periodic audit and pruning skill for Claude Code's auto-memory system.

Keeps your memory index healthy by detecting:

• Orphans — memory files not listed in MEMORY.md
• Broken links — MEMORY.md entries pointing to missing files
• Duplicates — the same fact captured in multiple files
• Staleness — facts that contradict the current state of the project
• Bloat — MEMORY.md approaching the 200-line front-load cap, or individual files drifting beyond focused scope

The skill reports first, acts only on approval. Memory deletion is never automatic.

Trigger keywords

English: memory audit, memory prune, clean memory, memory cleanup, audit memory, prune stale memory

日本語: メモリ整理, メモリ監査, プルーニング, 記憶整理, メモリ統合, 古い記憶を消して, メモリを整理して

Where memory lives

Claude Code writes auto-memory to a per-project directory:

~/.claude/projects/<encoded-project-path>/memory/
├── MEMORY.md          ← index, reloaded every turn (truncated past line 200)
├── user_*.md          ← role, preferences, knowledge
├── project_*.md       ← ongoing work, initiatives, decisions
├── feedback_*.md      ← guidance corrections and validated approaches
└── reference_*.md     ← pointers to external systems

The exact encoding of <encoded-project-path> depends on your Claude Code version — ask Claude to locate it with ls ~/.claude/projects/ if unsure.

Audit workflow

Step 1 — Load everything

1. Read MEMORY.md.
2. Glob all *.md files in the memory directory.
3. For each file, parse the YAML frontmatter (name / description / type) and body.
4. Cross-check: every indexed entry maps to a real file, every real file appears in the index.

Step 2 — Detect issues

Classify findings into five buckets:

2a. Orphan files

Files present on disk but missing from MEMORY.md. → Add to index, or delete if obsolete.

2b. Broken links

MEMORY.md entries whose target file does not exist. → Remove from index.

2c. Duplicate content

The same fact appears in more than one file. → Merge into a single file, delete the rest.

2d. Stale content

Body contradicts the current state:

• project: dated statements older than ~3 months, unfinished plans whose target date has passed
• feedback: referenced files/skills/commands that have been deleted or significantly changed
• user: user's situation has evolved (role change, new responsibilities, finished project)
• reference: the external system's purpose or location has shifted

→ Update body, or remove entirely.

2e. Bloat

• MEMORY.md over 200 lines (front-load truncation risk)
• Individual files over ~50 lines (focus has drifted, consider splitting)

→ Compress, split, or summarize.

Step 3 — Produce a report

Present findings in a structured report before touching any file:

## Memory audit report — <date>

### Stats
- Total files: N
- MEMORY.md lines: N / 200
- Issues detected: N

### Findings

#### Orphans (N)
- filename.md — short description

#### Stale (N)
- filename.md — "XXX" no longer matches YYY
  → suggest: update body to ZZZ

#### Duplicates (N)
- file_a.md ⇄ file_b.md — both cover "XXX"
  → suggest: merge into file_a.md

### Recommended actions
1. …
2. …

Step 4 — Wait for approval

Walk through each recommended action. The user approves or rejects per-item. No file is modified without explicit approval.

Step 5 — Apply approved changes

• Body edits → Edit tool
• Deletions → shell rm (approved items only)
• Index updates → Edit on MEMORY.md
• Merges → create the merged file, delete originals in a single confirmed step

Step 6 — Post-audit summary

Report back:

• Files updated / deleted / merged
• New MEMORY.md line count
• Suggested next audit cadence

Staleness heuristics by memory type

project memories

• Phrases like "planned for next month", "will ship by" — check if the target date has passed
• Relative dates ("tomorrow", "this week") — memory type should have stored absolute dates; flag if not
• Strategy / direction statements — compare against current repo state before assuming they are still load-bearing

feedback memories

• Grep for the skill, file, or command referenced — if it no longer exists, the feedback is stranded
• Workflow guidance where the underlying workflow has been restructured

user memories

• Cross-check against recent journal entries or user statements in the same session
• Role changes, new projects, finished projects

reference memories

• Skip external URL liveness checks (expensive)
• Check that the described purpose still matches nearby context in memory

Scheduling

Recommended triggers:

• Manual — user asks for a memory audit.
• Periodic — monthly cadence works well. Most users batch it with other housekeeping (calendar review, backups).

Automated execution must still produce a report first — do not let a scheduled prune delete files autonomously.

Guardrails

• Never auto-delete. Every destructive action waits for approval.
• Keep MEMORY.md at or under 200 lines; past that, front-load gets truncated.
• Keep individual memory files focused — ~50 lines is a healthy ceiling.
• Flag content that should not be in memory at all: code snippets, git history summaries, ephemeral task state, anything derivable from reading the current project.

Credits

• The auto-memory system shape (MEMORY.md + typed files) follows Claude Code's built-in memory conventions.
• Inspired by the "AutoDream" concept (sub-agent periodic memory consolidation).