{"slug": "show-hn-provenance-and-decay-for-ai-agent-memory", "title": "Show HN: Provenance and decay for AI agent memory", "summary": "Stalebrain, a new open-source tool from stalebrainlabs, audits AI agent memory files (CLAUDE.md, AGENTS.md, .cursorrules, GEMINI.md, Copilot instructions, and 18+ other locations across 13 agents) against current code, using git history to verify claims and stamp them with dates. The tool, installable via uv, pip, or git, provides verdicts, commit evidence, and ready-to-apply fixes for stale or false claims, aiming to prevent agents from acting on outdated instructions.", "body_md": "**Your AI agent's memory files are lying to it. stalebrain finds every lie, proves it with commits, and hands you the fix.**\n\n[Install](#install) ·\n[Demo](#see-it-in-action) ·\n[What it does](#what-it-does) ·\n[How it compares](#how-it-compares) ·\n[Troubleshooting](#troubleshooting) ·\n[License](#license)\n\nType `/stale-brain`\n\nin your AI coding assistant and it audits every agent memory file in your repo (CLAUDE.md, AGENTS.md, .cursorrules, GEMINI.md, Copilot instructions, 18+ locations across 13 agents) against the code as it exists today. Claims that check out get a dated stamp. Claims that don't get a verdict, the commits that prove it, and a ready-to-apply fix.\n\nNot a linter. A trust model: after one audit, every claim in agent memory carries an age, a verification date, and cited evidence.\n\nPrerequisite: a repo with git history. That's it.\n\n**With uv or pip (recommended, works inside Claude Code or any CLI)**\n\n```\nuv tool install stalebrain      # or: pip install stalebrain / pipx install stalebrain\nstalebrain install              # user-level: every repo, Claude Code CLI and desktop app\nstalebrain install --project .  # or just this repo\n```\n\nOne-shot without installing anything permanent:\n\n```\nuvx stalebrain install\n```\n\n**With git alone**\n\n```\n# project-level\ngit clone https://github.com/stalebrainlabs/stalebrain .claude/skills/stale-brain\n\n# or user-level (available in every repo)\ngit clone https://github.com/stalebrainlabs/stalebrain ~/.claude/skills/stale-brain\n```\n\nThen type `/stale-brain`\n\n, or say \"audit my agent memory\".\n\n**Desktop / no terminal at all**\n\n`stalebrain install`\n\ncovers the Claude Code desktop app (it reads the same user-level skills folder). For every other desktop chat (ChatGPT, Gemini, Claude.ai), run `stalebrain portable`\n\nto print the single-file protocol, or just copy [PORTABLE.md](/stalebrainlabs/stalebrain/blob/main/PORTABLE.md) and paste it into the chat.\n\n**Any other assistant (Cursor, Copilot, Gemini CLI, ChatGPT, local models)**\n\nPaste [PORTABLE.md](/stalebrainlabs/stalebrain/blob/main/PORTABLE.md) into the chat, or drop it in your repo and say \"run the stale-brain protocol in PORTABLE.md\". It is fully self-contained and degrades gracefully: an assistant with no tools asks you to paste command output (batched into one block), and one with no file access prints the diffs for you to apply.\n\n**Always-on tripwire (optional, any agent)**\n\nAdd one line to your always-loaded memory file (CLAUDE.md, AGENTS.md, or rules):\n\n```\nIf an instruction in this file contradicts observed reality, say so in one line (⚡ stale-brain) instead of silently complying, and suggest a stale-brain audit.\n```\n\nVerification is mechanical: glob, grep, and read-only git. No embeddings, no server, no database, no network. Nothing leaves your machine, and nothing gets executed: scripts are verified by their definition (scripts block, Makefile, CI), never by running them.\n\nAgents keep \"ignoring the rules\"? Half the time the rules are unfollowable. They name paths that moved, scripts that were renamed, package managers that were swapped out in March. An agent fed contradictory memory doesn't get 90% right; it gets confidently wrong, every session, at a token cost you pay every session.\n\n| Capability | How |\n|---|---|\n| Claim extraction | Every sentence becomes a typed claim: PATH, SCRIPT, SYMBOL, DEP, FACT, OWNER, CONVENTION. Style opinions are skipped, never judged. |\n| Verification | Per-type recipes against the live repo. A missing path gets git archaeology to find the rename and the new destination. A wrong owner gets checked against CODEOWNERS and git shortlog. |\n| Confidence decay | Per-type half-lives (paths 30d, conventions 120d). Past its half-life a fact is re-verified or downgraded to a hypothesis. |\n| Provenance stamps | `<!-- stale-brain: verified 2026-07-31 -->` , invisible in rendered markdown, greppable forever. Stamps make re-audits incremental. |\n| Contradiction evidence | Never \"this looks wrong\". Always \"wrong since a1b2c3d, here's the diff\". |\n| Cross-file conflicts | CLAUDE.md says yarn, .cursorrules says npm: flagged even when nobody knows which is right. |\n| Token meter | What your memory costs per session, and what share of it is actively misleading the model. |\n| Mid-task tripwire | When the agent notices an instruction contradicting reality mid-task, it says so in one line instead of silently complying. |\n| Approve-only fixes | Every verdict is explained; every edit waits for your yes. Non-interactive runs apply nothing. |\n\n| Agent | Files |\n|---|---|\n| Claude Code | CLAUDE.md (root and nested), CLAUDE.local.md, .claude/**/*.md |\n| Codex / cross-tool | AGENTS.md (root and nested) |\n| Cursor | .cursorrules, .cursor/rules/**/*.mdc |\n| GitHub Copilot | .github/copilot-instructions.md, .github/instructions/*.instructions.md |\n| Gemini CLI | GEMINI.md |\n| Windsurf | .windsurfrules, .windsurf/rules/** |\n| Cline | .clinerules (file or directory) |\n| Roo Code | .roo/rules/** |\n| Aider | CONVENTIONS.md (when referenced from .aider.conf.yml) |\n| Zed | .rules |\n| Amazon Q | .amazonq/rules/** |\n| JetBrains Junie | .junie/guidelines.md |\n| OpenHands | .openhands/microagents/*.md |\n\nHuman docs (README, CONTRIBUTING, docs/) are out of scope. Lockfiles, manifests, and CI configs are evidence, not memory: they're what claims get checked against.\n\nFour verdicts. Every claim lands in exactly one:\n\n| Verdict | Meaning |\n|---|---|\n| 🟢 CONFIRMED | Evidence checks out today. Gets a dated stamp on apply. |\n| 🟡 STALE | Re-verification came back inconclusive (owner inactive, convention eroding). Downgraded to \"as of , X was true\". |\n| 🔴 CONTRADICTED | Affirmative evidence against, with the specific commits cited and a corrected rewrite. |\n| ⚪ UNVERIFIABLE | No mechanical check exists. Says so explicitly. Never guesses. |\n\nHealth = (confirmed + 0.5 × stale) / (confirmed + stale + contradicted) × 100. A valid stamp counts as a confirmation; unverifiable claims are excluded because not knowing is not the same as being wrong.\n\nThe output system is a feature, not a byproduct. Reports follow CALM rules (chunked to 5 findings per block, verdict first, zero narration) rendered with Pulse graph primitives: an append-only ticker that streams audit progress one line at a time, and terminal graphs for health, token cost, and trend. Every evidence line carries a `(direct)`\n\nor `(inferred)`\n\nprovenance tag; `why C7`\n\nreprints any finding as its full evidence chain; `brief`\n\ncollapses the report to 10 lines; `files`\n\nshows per-file health strips; a `decay`\n\nline names the next half-life expiry; and applied fixes end in a one-line `GAIN`\n\nsummary (health, misleading tokens, and recovered tokens, before → after). All of it is plain Unicode with a complete ASCII fallback, built from scratch, zero dependencies. Full spec in [references/output-format.md](/stalebrainlabs/stalebrain/blob/main/references/output-format.md). Each audit is recorded in `.stale-brain/audit-YYYY-MM-DD.md`\n\n, which feeds the trend graph on the next run.\n\nFeature checks verified 2026-07-31 against each project's published docs and source. ✓ shipped, ~ partial, ✗ absent.\n\n| stalebrain |\n|\n|---|\n\n[ctxlint](https://github.com/YawLabs/ctxlint)\n\n[agents-lint](https://github.com/giacomo/agents-lint)\n\n[AgentLinter](https://agentlinter.com/)\n\n[claude-memory-health](https://github.com/alexknowshtml/claude-memory-health)\n\nIf one row matters most, it's the stamps: without provenance, every other tool re-audits everything from zero and can't tell you how old a \"fact\" is. With them, stalebrain is a trust model you can grep.\n\n```\nSKILL.md                    the protocol (Claude Code entry point)\nPORTABLE.md                 self-contained any-agent version\nreferences/\n  memory-sources.md         where every agent keeps its brain\n  claim-types.md            taxonomy, half-lives, verification recipes\n  output-format.md          CALM rules, Pulse graphs, token meter, report + audit formats\nsrc/stalebrain/             the installer CLI (stalebrain install / portable / path)\nassets/                     hero and demo art\npyproject.toml              uv / pipx / pip packaging\n```\n\n**The skill doesn't trigger.** Type `/stale-brain`\n\ndirectly, or use the phrases in the trigger description: \"audit my agent memory\", \"verify my CLAUDE.md\", \"my agent ignores the rules\". Skill activation is description-matched and inexact everywhere.\n\n**A verdict looks wrong.** Every verdict cites its evidence: a lockfile, a scripts block, a commit hash. Check the citation first; if the evidence is right and the verdict is still wrong, that's a bug worth reporting.\n\n**It flagged something I want to keep.** Nothing is applied without your approval of the specific diff. Decline the fix; the claim stays as it was. Style preferences are never flagged at all (OPINION claims are skipped).\n\n**The token numbers look off.** They're file bytes ÷ 4, labeled as estimates (±20% for English text). The signal is the ratio of misleading to total, not the absolute count.\n\n**Output symbols look garbled.** Say \"ascii\". Every symbol has a plain-text fallback with the same line structure.\n\n**My repo is a shallow clone.** Drift detection needs history. stalebrain notices shallow clones and re-verifies instead of trusting an empty drift pass, but full history gives better citations.\n\nMIT. See [LICENSE](/stalebrainlabs/stalebrain/blob/main/LICENSE). All content is original work, written from scratch.", "url": "https://wpnews.pro/news/show-hn-provenance-and-decay-for-ai-agent-memory", "canonical_source": "https://github.com/stalebrainlabs/stalebrain", "published_at": "2026-07-31 13:13:53+00:00", "updated_at": "2026-07-31 13:22:13.651825+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools"], "entities": ["stalebrain", "stalebrainlabs", "Claude Code", "Cursor", "Copilot", "Gemini CLI", "ChatGPT"], "alternates": {"html": "https://wpnews.pro/news/show-hn-provenance-and-decay-for-ai-agent-memory", "markdown": "https://wpnews.pro/news/show-hn-provenance-and-decay-for-ai-agent-memory.md", "text": "https://wpnews.pro/news/show-hn-provenance-and-decay-for-ai-agent-memory.txt", "jsonld": "https://wpnews.pro/news/show-hn-provenance-and-decay-for-ai-agent-memory.jsonld"}}