iusztinpaul/squid/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

Rewrite each line in the fewest words that keep its meaning — drop filler, hedges, and pleasantries ("Please make sure to always run the tests" → "Run the tests"); keep code, paths, and URLs byte-identical. Commit the pass as one commit. Compress before cutting: normalised wording turns reworded duplicates into literal ones.

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.

When run unattended (a scheduled routine), also send that report with PushNotification — nobody reads the session.

Notes on shape

• Fewer words, never fewer rules. If a cut loses a nuance, it is an edit — out of scope.