/gaia-cleanse

/gaia-cleanse reviews what Claude remembers and what it loads at every session start (machine-local memory, CLAUDE.md files, and rules) against the wiki, the project’s source of truth. It looks for entries that repeat the wiki, disagree with it, or point at things that no longer exist, and for files that make the always-loaded context too large. Then it asks you one question before changing anything.

It runs like every maintenance command: from the main checkout, on a branch of its own (a worktree by default, per your team’s isolation policy), ending in a pull request.

Why it helps

Memory and CLAUDE.md files load into every session, and Claude treats them as instructions. An entry that has gone stale or contradicts the wiki steers Claude wrong on every task, and every extra line costs tokens in every session. Claude Code’s own memory documentation (opens in a new tab) notes that the more specific and concise these instructions are, the more consistently Claude follows them.

When to use it

Run it after a stretch of work, or when Claude’s starting context (everything it loads before you type anything) feels heavy. The statusline nudges you with 🔎 /gaia-cleanse (<reason>), showing the highest-priority reason:

• resume draft: a report is waiting to be applied.
• <N> new memories: machine-local memory has grown by 10 or more entries since the last applied cleanse.
• <N> days since review: 30 or more days since the last applied cleanse.
• over budget: an auto-loaded file is larger than its size budget (an oversized CLAUDE.md, nested CLAUDE.md, or rule).

How to invoke

/gaia-cleanse

Researches, shows you what it found, and applies the changes only if you say yes.

/gaia-cleanse "memory only"

A hint in quotes limits which memory stores or files the research looks at. It can only narrow the search. It can’t change how the report looks, what kinds of changes it makes, its safety checks, or any specific edit.

/gaia-cleanse --apply

Applies the most recent report again. Use it to finish a run that was interrupted, or to retry after fixing whatever caused some changes to be skipped.

What it looks at

Store	Path	Auto-loaded?
Machine-local project memory	~/.claude/projects/<project>/memory/	MEMORY.md (first 200 lines); entries on demand
Machine-local agent memory	~/.claude/agent-memory/	Per agent, on demand. Reported, never edited: it is shared by every project on the machine.
Project agent memory	.claude/agent-memory/	Per agent, on demand
Root CLAUDE.md	CLAUDE.md	Every session
Nested CLAUDE.md files	**/CLAUDE.md (for example frontend/CLAUDE.md)	When the working directory matches
Project rules	.claude/rules/*.md	At session start, or on a paths: match
Wiki	wiki/	On demand. The reference the others are checked against.

Each entry is classified:

• DUPLICATE: the wiki already says it, so the local copy is removed.
• PROMOTE: lasting knowledge that exists only in memory moves to a named wiki page.
• KEEP-LOCAL: it really does belong to this machine only (a personal preference, a path on this machine), so it is left alone.
• STALE: it points at a file, branch, or feature that no longer exists.
• CONFLICT: a memory entry disagrees with the wiki, so it is changed to match the wiki.

Counts, size budgets, and references to missing paths are measured by a script, so they come out the same every time. Claude judges only what a script can’t.

What it does not touch

• Conflicts between instruction files. When two CLAUDE.md files, rules, skills, commands, or agents disagree with each other, this command does not decide between them. Run /doctor prompt-audit for those. An instruction file that contradicts the wiki is reported and filed as a tech-debt issue, never edited.
• Files you do not own. It edits only your project’s own files and memory, and asks you per file. A problem in a file GAIA ships is reported for /update-gaia to fix. A problem in a third-party file is reported for its vendor. Agent memory shared across the whole machine is only reported; ask Claude directly if an entry there needs changing.
• The wiki’s own redundancy and broken links. Those belong to /gaia-wiki.
• Rules from /gaia-codify. A rule /gaia-codify wrote carries a comment saying where it came from (it starts with gaia-harden:, the command’s old name). It is treated like any other rule, except it is never removed just because the problem it targets stopped showing up. A problem that stops showing up means the rule is working.

The flow

1. Research. A separate Sonnet agent writes a report to .gaia/local/cleanse/KNOWLEDGE-<timestamp>.md (gitignored). Every proposed change is spelled out exactly: the path, the content it expects to find there, and what replaces it.
2. Verification round (recommended, optional). When the report proposes any change, three checks run in parallel. They test each proposed change against the actual memory files, the wiki, and the repository, and drop or fix any that got it wrong. Memory lives outside git, so a wrong delete can’t be undone; this round catches it before you approve.
3. One question, in your session:
   • Apply: asks which of your own files it may edit, then applies the report on its own branch, files any out-of-scope problem as a tech-debt issue, commits, opens a pull request, and merges it.
   • Discuss / refine: talk it through. Claude updates the report and asks again.
   • Decline: delete the report. Nothing is applied, filed, or published.

When the report proposes no changes, the run skips the verification round and the question and finishes on its own, but only after a check confirms the report compared every memory and rules file with the wiki. If that check fails, it says what the report missed and asks the usual question instead.

Safe by default

Running /gaia-cleanse researches and reports. Nothing in memory, rules, or the wiki changes until you choose Apply.

What Apply changes

Apply removes files or sections the wiki already covers, moves lasting knowledge from memory to a named wiki page, and replaces text in an auto-loaded file with a link to the wiki page that covers it.

Each change records what the file looked like when the report was written. If the file has changed since, that change is skipped and noted, never forced. A file with uncommitted changes is skipped before anything runs.

Reports and resume

A report is draft until applied, then applied or applied-partial (some changes were skipped, and --apply retries them). Drafts are never deleted. Of the finished reports, the newest five are always kept, and older ones are deleted once they are more than 30 days old.

--apply checks the report’s age: up to 24 hours proceeds, 24 to 72 hours proceeds with a warning, and over 72 hours stops and asks for a fresh run.

Memory edits live outside the repository under ~/.claude/ and are never committed. A run that only changed memory opens no pull request.

The run ends with a cost line.