Squid Clean Memory

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.

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.

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 diff touches 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.