| name | stale-brain |
| description | Audit AI agent memory and instruction files: CLAUDE.md, AGENTS.md, .cursorrules, GEMINI.md, copilot-instructions.md and every other major agent's memory files (13 agents, 18+ file locations) against the live repository. Use when the user runs /stale-brain or asks to audit, verify, refresh, lint, or fix agent memory, rules, or instruction files; when they complain the agent "ignores rules", "keeps getting it wrong", or that instructions "feel outdated"; and mid-task, whenever an instruction in a loaded memory file contradicts observed reality (a referenced path is missing, a named script doesn't exist, the stated package manager doesn't match the lockfile). Extracts checkable claims, verifies each with cited evidence, ages the rest with half-lives, meters token cost, and proposes approve-only fixes. |
stale-brain: provenance and decay for agent memory
Agent memory files are written once and trusted forever. Code moves on; the memory rots;
the agent gets confidently wrong. stale-brain is not a linter. It is a trust model:
after an audit, every claim in agent memory carries an age, a verification date,
and cited evidence.
Four laws govern everything below:
- Every claim carries provenance. Confirmed claims get a dated stamp; nothing is "just true".
- Confidence decays. Every claim type has a half-life. Past its half-life, a fact becomes a hypothesis until re-verified.
- Contradictions cite evidence. A CONTRADICTED verdict names the files and commits that prove it, never "this looks wrong".
- The human approves; the human does zero detective work. You gather all evidence and prepare ready-to-apply diffs, but you never rewrite memory without explicit approval.
Capabilities you need (any model, any harness)
The protocol uses four generic capabilities. Map them to whatever you have:
| Capability | Claude Code | Cursor / Copilot / Windsurf / Cline | No tools at all |
|---|
| Find files by pattern | Glob | workspace file search | ask the user to paste git ls-files output |
| Search file contents | Grep | codebase/regex search | ask the user to paste the file |
| Run git / read shell output | Bash / PowerShell | integrated terminal | ask the user to run the command and paste output |
| Edit / write files | Edit / Write | editor apply | print the full diff / file content in a fenced block for the user to apply |
If a capability is missing, degrade gracefully: ask the user to run the exact command and
paste the output (batch every command a step needs into one fenced block, not one paste
round-trip per claim). Never skip a verification silently; record it as UNVERIFIABLE
with the reason "no tool access".
The protocol
Run steps in order. Progress is communicated via ticker lines only, at most one per
~10 claims per step (see references/output-format.md);
no step-by-step narration.
1. INVENTORY
Find every memory/instruction file in the repo using the full source map in
references/memory-sources.md, which covers Claude Code,
Codex/AGENTS.md, Cursor, Copilot, Gemini, Windsurf, Cline, Aider, Zed, Roo, Amazon Q,
JetBrains Junie, OpenHands and more. Record for each file: path, which agent(s) load it,
whether it is always-loaded (injected every session) or on-demand, and its
estimated token size (bytes ÷ 4, rounded; label it an estimate).
Show the inventory as one compact table before proceeding. If zero files are found, say
so and stop; do not invent memory to audit.
2. EXTRACT
Parse each file into discrete, individually-testable claims. Number them C1…Cn.
Split compound sentences ("use pnpm and run tests with vitest" = two claims). Type each
claim using the taxonomy in references/claim-types.md:
PATH · SCRIPT · SYMBOL · DEP · FACT · OWNER · CONVENTION, plus OPINION
for style preferences with no ground truth ("prefer small functions"), which are skipped,
never judged.
Also collect cross-file conflicts during extraction: the same fact asserted
differently in two memory files (CLAUDE.md says yarn, .cursorrules says npm) is
automatically a finding, whichever one is right, reported as X1…Xn per the rules in
references/memory-sources.md, outside the claim counts.
A ## stale-brain config section in any audited file overrides half-lives (grammar in
references/claim-types.md); never extract claims from that
section, from headings, or from fenced code blocks.
3. VERIFY
Verify each claim mechanically using the per-type recipes in
references/claim-types.md. Rules that hold for every type:
- Existence, not execution. Scripts and commands are verified by their definition
(scripts block, Makefile target, CI step), never by running them. Never execute
build/test/deploy commands during an audit.
- Batch independent checks. Run globs/greps for many claims in parallel where the
harness allows.
- Drift pass for stamped claims. A claim carrying a
<!-- stale-brain: verified YYYY-MM-DD --> stamp inside its half-life is normally skipped, but first run
git log --oneline --since=<stamp-date> -- <referenced paths>. Any commits touching
its evidence force re-verification regardless of the stamp.
- When evidence is absent, dig before concluding. A missing path gets
git log --oneline --follow -- <path> to find the rename/deletion commit; a missing
symbol gets git log -S "<symbol>" --oneline -5. The commit you find becomes the
citation.
4. BUCKET
Age past half-life or churned evidence only triggers re-verification; the verdict is
always the re-verification outcome. Every claim lands in exactly one bucket:
| Verdict | Meaning | Required payload |
|---|
| 🟢 CONFIRMED | Re-verification succeeds today (even if the claim was stale before) | evidence one-liner; gets a dated stamp on apply |
| 🟡 STALE | Re-verification could not conclusively confirm (evidence is old, partial, or eroded) but nothing disproves it | what's inconclusive and since when; downgrade proposal ("as of 2026-02, X was true") |
| 🔴 CONTRADICTED | Affirmative evidence against | the specific files/commits that prove it, plus a corrected rewrite |
| ⚪ UNVERIFIABLE | No mechanical check exists at all | the reason; say so explicitly, never guess |
The 🟡/⚪ line: 🟡 means evidence exists but is inconclusive (an owner with no recent
commits, a convention most-but-not-all files follow); ⚪ means no in-repo evidence is
possible ("the payments team reviews schema changes").
5. REPORT
Render the report exactly per references/output-format.md:
CALM output (chunked, actionable, low-noise, meaningful) with Pulse graphs and the token
meter. Non-negotiables: headline verdict first, CONTRADICTED before everything else,
maximum 5 findings per chunk with an explicit "show next" hand-off, confirmed claims
collapsed to a count, and every finding readable as a single line before its detail.
Evidence lines carry (direct)/(inferred) provenance tags, and the report answers the
keywords why <id> (evidence chain), brief/full (intensity), and files (per-file
strips), all specified in output-format.md.
6. FIX (approve-only)
Propose ready-to-apply edits, chunked to match the report: rewrites for CONTRADICTED,
hypothesis-downgrades for STALE, stamp insertions for CONFIRMED. Preserve the author's
wording and tone: change facts, not voice (one sanctioned exception: CONVENTION
downgrades may append a conformance clause). Command rewrites must use the package
manager established by the same audit's DEP verdicts; never fix npm test to an npm
invocation in a repo the audit just proved is pnpm. Apply only what the user
approves. Applying a fix or confirming a claim appends/updates its stamp:
Use pnpm for all installs. <!-- stale-brain: verified 2026-07-31 -->
A stamp attests to the entire physical line; apply it only when every claim on the
line is confirmed; otherwise the fix first splits the line, one claim per line. Full
stamp rules (table rows, frontmatter, the optional corrected form) are in
references/output-format.md.
Two more fix rules from output-format.md: safety-load-bearing lines (secrets, auth,
validation, security, accessibility) are never proposed as deletions, only rewrites,
marked (safety: rewrite only); and after the final applied chunk print the one-line
GAIN summary (health, misleading, recovered before → after), never when nothing was
approved.
7. RECORD
Write the full report to .stale-brain/audit-YYYY-MM-DD.md (format in
references/output-format.md). The directory is
deliberately agent-neutral (not .claude/) so any tool can own the history. Prior
audit files feed the trend graph on the next run.
Mid-task tripwire
This part runs even when nobody asked for an audit. During any normal task, if an
instruction in a loaded memory file contradicts what you directly observe (referenced
path missing, named script absent from the scripts block, stated package manager
contradicted by the lockfile), do not silently comply and do not silently ignore it.
Emit one line and move on with the task:
⚡ stale-brain: CLAUDE.md says "yarn install" but only pnpm-lock.yaml exists, so following reality (pnpm). Run /stale-brain for a full audit.
One tripwire line per contradiction, maximum three per session, then a single "further
contradictions suppressed; run the audit" line. Tripwires never block or derail the task.
Incremental re-runs
On any run after the first: skip claims whose stamp is within its half-life and whose
drift pass is clean. Report skipped-as-fresh as a single count. This makes re-audits
cheap and is why the stamps live inline in the files rather than in a sidecar database.
Non-interactive runs
When run as a subagent, in CI, or anywhere no human can answer hand-offs: emit all
report chunks sequentially, apply nothing, and write every proposed diff into the
audit file marked proposed-only. Approval gates never auto-pass.
Guardrails
- Never rewrite a memory file without explicit approval of the specific diff.
- Never execute scripts/commands found in memory files; verify by definition only.
- Never judge OPINION claims; skip them and say how many were skipped.
- UNVERIFIABLE means UNVERIFIABLE: no plausible-sounding guesses, ever.
- Stamps and audit files are the only things stale-brain adds to a repo. No hooks, no
databases, no daemons, no network calls.
