Clean memory — same rules, minimum words
You are the cleaner. You shrink the memory files sessions load; you do not change what they instruct. Zero meaning diff is the contract — every rule that holds before must hold after, and no new rule may appear.
$ARGUMENTS is an optional file or directory scope. Empty means every memory file in the repo: the
root AGENTS.md plus each nested AGENTS.md / CLAUDE.md. Where CLAUDE.md symlinks AGENTS.md,
that is one file — edit the target, never replace the symlink with a copy.
When NOT to use
- Docs, READMEs, comments, docstrings →
/squid-clean-docs. - A rule you think is wrong — that is a deliberate edit to make with the user, not a cleanup.
Step 1 — Resolve the target set
Discover the set with git ls-files '*AGENTS.md' '*CLAUDE.md' (tracked files only, so vendored trees
stay out), narrow to $ARGUMENTS if given, and collapse symlink pairs. The files must be clean in
git.
Step 2 — Compress wording (caveman pass)
If the caveman plugin is installed, ask, then run /caveman-compress <file> on each file in the set
and commit the pass as one commit (code, paths, and URLs are byte-preserved). Compress before cutting:
normalised wording turns reworded duplicates into literal ones. Not installed → skip; the cuts below
still shrink the files, just without the wording-level pass.
Step 3 — Apply the keep/delete test
A memory line survives only if deleting it would change how a future session behaves. Three cuts:
Duplicates — the same instruction stated twice, even reworded — in one file or across the set: a
nested AGENTS.md repeating the root dies where it's nested, since the root already loads everywhere.
Keep one home, delete the copies; leave a cross-reference only when the section survives without it.
Moving a rule between files (root ↔ nested) changes where it applies — that is a scope edit, not a
cleanup: flag it in the plan, never fold it into a dedupe.
Baked-in claims — the test: would a fresh session with an empty memory file already behave this
way? If yes, the line is dead weight. Caution: AGENTS.md is read by non-Claude harnesses too — if
the behaviour is a Claude Code default rather than universal, keep the line and flag it in the plan.
| Delete | Keep |
|---|---|
| "Always read a file before modifying it." — harness enforces | "Use uv run pytest, never bare pytest." — project decision |
| "Be concise." / "Don't over-engineer." — system-prompt defaults | "Chunk at 200 tokens — the embedding model truncates above 256." |
| Install steps under both Setup and Contributing — one home | "Never edit docs/adr/ — ADRs are immutable." |
Merges — two sections merge when a reader never needs one without the other, or a section is a few lines sharing a topic with its neighbour. A 3-line Code style plus a 2-line Naming become one Conventions; a heading costs more attention than it organises.
Step 4 — Plan of attack (the output artifact)
Print one table in chat. Do not write it to disk unless the user asks.
| File | Lines / section | Cut (Step 3) | Why | ~Words |
|---|---|---|---|---|
AGENTS.md | "read before you edit" | baked-in | harness enforces it | −9 |
api/AGENTS.md | "use uv run, never pip" | duplicate | root already states it | −11 |
AGENTS.md | Code style + Naming | merge | always read together | −12 |
Stop and wait for explicit approval. Do not edit before it.
Step 5 — Execute
Apply the approved plan as one commit, separate from the Step 2 commit.
Step 6 — Verify
Meaning must be provably unchanged before hand-off:
- Re-read each final file against its pre-clean version: every old rule is still stated in a file that loads wherever the rule applied, merged, or a planned deletion — name its new home.
- Every path, command, and URL in the files still resolves.
git difftouches only memory files.
Anything off: revert that commit, do not "fix forward".
Step 7 — Hand-off
Report wc -w before → after per file. Then ask the user to run /doctor (Claude Code only — a
built-in you cannot invoke): Step 1 scopes this pass to tracked files, so the always-loaded
local ones — ~/.claude/CLAUDE.md, CLAUDE.local.md — are never reached here; /doctor
dedupes those against the checked-in set.
Notes on shape
- Fewer words, never fewer rules. If a cut loses a nuance, it is an edit — out of scope.
