# Memory Pruner

> Audit, deduplicate, and prune Claude Code auto-memory files. Detects orphans, broken links, duplicates, staleness, and bloat across MEMORY.md and individual memory files. Triggers: memory audit, memory prune, clean memory, メモリ整理, メモリ監査, プルーニング, 記憶整理

- Skill: `zawatton/memory-pruner` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add zawatton/memory-pruner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zawatton/memory-pruner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: zawatton (https://skillmd.com/u/zawatton)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zawatton/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).