| name | squid-clean-memory |
| disable-model-invocation | true |
| argument-hint | [scope-path] (default: every memory file in the repo) |
| description | Shrink the memory files sessions load — the root AGENTS.md plus every nested AGENTS.md / CLAUDE.md — to the minimum words that state the same rules: compress wording, delete duplicates and harness-enforced claims, merge fragments. |
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.
Output is a plan table, approved by the user, then applied as one commit per pass.
$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 to use
AGENTS.md has organically grown into entropy — /squid-self-improve rounds, hand-pasted rules, merged PRs.- Sessions keep loading guidance that repeats itself, restates harness defaults, or fragments across tiny sections.
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 — each pass below commits separately so any revert is surgical.
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). 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 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 /checkup (Claude Code only — a
built-in you cannot invoke): it dedupes local memory against checked-in files and flags unused
always-loaded guidance, catching what this pass missed.
Notes on shape
- Fewer words, never fewer rules. If a cut loses a nuance, it is an edit — out of scope.
- One home per idea. Duplication is the target; cross-reference, never transclude.
- Compress before cutting. The caveman pass normalises wording, so reworded duplicates become
literal ones — easier to spot in Step 3.
