A Claude Code Skill to Tidy Up Auto-Memory

The problem

A typical MEMORY.md after a few months:

# Memory

## Skills directory structure

- Skills are stored in `~/.claude/skills/`
- Each skill has a `SKILL.md` with frontmatter

## Existing skills

- `data-pipeline` — ETL orchestration
- `incident-response` — runbook structure
  [...11 lines...]

## Skills rewrite (2026-03-10)

- Both `data-pipeline` and `release-checklist` rewritten to match standards
- Now use: checklist progression, parallel agents, ultrathink
- Key updates: runtime validation, deprecated schemas [...230 chars on one line...]

## release-checklist architecture

- `SKILL.md` — Main orchestration
- `STAGES.md` — 8 deploy stages
  [...]

46 lines, six multi-paragraph sections. Two of them entirely reproducible with ls. One that reads like a session changelog. One describing a skill you can read directly in its folder.

The content isn't wrong — it's loaded into every conversation with no added value. The harness loads MEMORY.md automatically at startup, truncates beyond 200 lines, and everything in it lives in every thread's context.

What remained was knowing how to tidy it. And there, no public documentation.

Internal rules, undocumented

Auto-memory is defined in Claude Code's internal system prompt, in an auto memory section. Invisible, but present in every session. It describes:

• 4 strict memory types: user, feedback, project, reference
• A mandatory body format for feedback and project (**Why:** and **How to apply:** lines)
• Strict rules for MEMORY.md (no frontmatter, lines < 150 chars, pure index)
• A list of things to never save (derivable catalogs, git history, bug fixes, CLAUDE.md duplicates)

None of it appears in Anthropic's public docs. The memory concept is mentioned for managed agents, but neither the format nor the CLI's internal rules. Hence the idea of encoding those rules into a skill that audits and refactors.

What it produces

One command, /memory-reorganize, and 30 seconds later:

## Memory audit — 2026-04-28

**Current state**: 3 files + MEMORY.md (46 lines)

### Critical violations
- MEMORY.md L3-6 "Skills directory structure": entirely derivable from `ls`
- MEMORY.md L8-19 "Existing skills": 12 lines derivable from `ls`
- MEMORY.md L21-27 "Skills rewrite": 7 inline lines (should be deleted)
- MEMORY.md L26 is ~280 characters (>150)

### Medium violations
- release-checklist.md: non-standard `originSessionId` field
- data-pipeline.md: "Architecture" section derivable from `ls`

### Derivable content to remove
- 60% of release-checklist.md: catalog of support files

The skill then proposes a structured refactor plan and asks for explicit validation before touching anything. It backs everything up as *.backup-YYYY-MM-DD before writing a single line.

Result on the example memory: 46 lines of MEMORY.md down to 5, three files refactored (average -50% length, missing Why/How added), no loss of valuable information.

The rules, condensed

4 strict types

Any file that fits none of these types is suspect. "Memory: project structure" is neither user, nor feedback, nor project, nor reference: it's derivable from the filesystem, so it isn't a memory.

Why / How to apply format

For feedback and project, two mandatory lines:

**Why:** [motivation, incident, constraint]
**How to apply:** [when/where this rule applies]

Without them, judging edge cases later is impossible. A memory saying "don't commit on Friday" with no Why becomes ambiguous within two months: no-deploy or no-commit? All day or only after 4pm? You're left with the bare rule and none of the invariants that produced it.

MEMORY.md = pure index

• No frontmatter
• One line per memory, format - [Title](file.md) — one-line hook
• Each line < 150 characters
• Total < 200 lines (beyond that, truncated by the harness)
• No content written directly, only pointers
• Semantic sections by topic, not chronological

If your MEMORY.md contains the word "we", or lists things, or describes an architecture: it's broken.

What NOT to save

Even on explicit request:

• Code patterns, architecture, paths (derivable)
• Git history, who-did-what (git log is authoritative)
• Debug recipes or fixes (the fix is in the code)
• Anything already in CLAUDE.md
• Ephemeral state (in-flight tasks, current conversation context)
• Lists derivable from ls

The mental test: "where would I find this later?". If the answer is ls, git log or CLAUDE.md, it isn't a memory.

Absolute dates

Always 2026-04-28. Never "recently", "last week", "two days ago". Memory lives for months; relative dates turn into fiction.

The skill's architecture

The skill lives in ~/.claude/skills/memory-reorganize/ (see on GitHub):

memory-reorganize/
├── SKILL.md              (orchestrator, 171 lines)
├── BEST_PRACTICES.md     (full rules, 86 lines)
└── EXAMPLES.md           (concrete before/after, 203 lines)

The pattern follows Anthropic's progressive disclosure recommendation: SKILL.md stays lean, and the detailed rules and examples load only when needed. That's not cosmetic — it's measurable in tokens saved per invocation.

The workflow orchestrated by SKILL.md:

Phase 1  : Inventory (list files, read MEMORY.md)
Phase 2  : Per-file audit against BEST_PRACTICES.md
Phase 3  : MEMORY.md audit (index format)
Phase 4  : Duplicate / overlap detection
Phase 5  : Derivable content detection
Phase 6  : Freshness check (broken refs, relative dates)
Phase 7  : Violation report
Phase 8  : Refactor plan (consulting EXAMPLES.md)
Phase 9  : User validation (AskUserQuestion)
Phase 10 : Backup + apply + final check

BEST_PRACTICES.md captures the system prompt's internal rules as a table and a checklist. It's the source of truth for phases 2 to 6, loaded only during the audit.

EXAMPLES.md is the most surprising file in terms of impact. Without concrete examples, Claude refactors correctly but the style varies from one call to the next. With three well-chosen before/after examples, the style becomes deterministic — taste transferred by demonstration. The three cases covered: a project memory with no Why/How (the most frequent violation), MEMORY.md from chaos to pure index (the most visible transformation), and a well-structured but overly verbose memory (the subtle case). Plus an anti-pattern table to calibrate detection.

A concrete case

A typical "well-intentioned but broken" project memory:

---
name: release-checklist skill architecture
description: Architecture of the release-checklist skill (refactored 2026-04-14)
type: project
originSessionId: 00000000-0000-0000-0000-000000000000
---

Pre-deploy validation skill for backend services.

Architecture (after 2026-04-14 refactor):

- `SKILL.md` (118 lines) — Lean orchestrator
- `STAGES.md` — 8 deploy stages with gating criteria
- `ROLLBACK.md` — 4 rollback procedures
- `KPIS.md` — measurable thresholds per stage

Key rules:

- No deploy on Friday after 16:00 (SRE policy)
- Mandatory canary 5% before full rollout
- Rollback within 15min if error rate > 1%
- Postmortem required for any P1/P2

The diagnosis: frontmatter with a non-standard originSessionId, an "Architecture" section entirely derivable from ls, missing **Why:** and **How to apply:** (mandatory for type=project), and "Key rules" worth keeping since they aren't derivable.

After refactoring:

---
name: release-checklist skill
description: Pre-deploy validation skill for backend services. Blocks risky deploys and enforces mandatory SRE checks.
type: project
---

Pre-deploy skill for internal backend services.

**Why:** Reduce rollbacks (12% of deploys before introduction). Enforce canary, no-deploy-Friday, and automatic rollback <15min on >1% error rate, after the 3 P1 incidents in Q4 2025.

**How to apply:** Invoke for any release/deploy preparation. Architecture details in support files — do NOT duplicate here.

## Non-derivable operational rules

- **No deploy Friday > 16:00** (SRE policy)
- **Mandatory 5% canary** before full rollout
- **Rollback < 15min** if error rate > 1%
- **Postmortem required** for any P1/P2

26 lines down to 16, no duplication with the filesystem, a Why that tells the incident behind the rule and an explicit How to apply. Three months later, facing an edge case like "can we deploy a critical patch on Friday at 5pm to fix a data leak?", you have the motivation to decide — not just the bare rule.

Guardrails

The skill modifies files, so:

• Systematic backup: every modified file is copied to *.backup-YYYY-MM-DD before any write
• Explicit user validation (Phase 9, via AskUserQuestion)
• No edits outside the memory folder: not CLAUDE.md, not settings.json, not skills
• Valuable content preserved: a memory that breaks the rules but holds useful info is refactored, not deleted
• Nothing invented: the skill reorganises what's there, it doesn't create from nothing

Testing

Restart Claude Code (skills load at startup), then:

/memory-reorganize
/memory-reorganize duplicates
/memory-reorganize frontmatter
/memory-reorganize index

Expect 30 seconds to 2 minutes depending on memory size.

What this teaches

Claude Code's internal rules aren't publicly documented. Everything is in the system prompt. That's deliberate — internals can change — but it means reading your current system prompt or asking Claude itself for the rules. The skill encodes them in BEST_PRACTICES.md to make them explicit, at the cost of potentially going stale.

The Why changes everything. One version of the skill asked only for type + content, the other required Why + How to apply. The second produces memories still usable at six months; the first, opaque notes within two. Motivation is what turns a note into an actionable rule.

Derivable content is the main enemy. In the example memory, 60% of the volume: skill lists (ls), folder architecture (tree), session changelogs (git log). That content pollutes every session and adds nothing. Applying the "where would I find this later?" test before every save halves memory size.

Progressive disclosure genuinely works. Splitting the skill into three files cuts ~30% off SKILL.md, and the files only load when needed. Measurable in tokens saved per invocation.

User validation is non-negotiable. A skill that modifies files without asking will eventually delete something important. AskUserQuestion adds ten seconds per run — nothing compared to restoring a backup, let alone recovering a file with no backup.

Limitations

It's a tool, not an authority. The skill applies rules, but some memories "violate" them while still being useful — typically one mixing project and reference. It detects the ambiguity and asks rather than deciding alone, and it can get the proposed type wrong, especially on short memories.

It does not generate memories: if yours is empty, it won't invent anything. Enriching memory is what normal usage does.

Finally, it depends on the stability of the internal memory format. If Anthropic changes it, BEST_PRACTICES.md becomes potentially wrong — the skill is a snapshot of the rules at a point in time.

For the intended use case, an attic that drifts over the months, it's a quarterly cleanup tool: 30 seconds to audit, 2 minutes to validate, and memory starts clean again.