Daniel Broadhurst

ArticlesAI Engineering

Stale Agent Memory Is Worse Than None: How to Prune It

10 Nov 2026 · 7 min read

Ink sketch of an open notebook with a pair of pink scissors cutting one old, curling page out along the spine

An agent with no memory asks. An agent with stale memory tells you, confidently, about a file you deleted in March.

Every guide to agent memory says the same thing: write it down. Put the build command in CLAUDE.md, let the agent save your corrections, and stop explaining the same thing every session. That advice is right, and it’s only half the job.

The other half is decay. Code moves, memory doesn’t. A note that was true when it was written becomes a confident lie a few refactors later, and the agent has no way to tell the difference.

So here’s the short answer: every memory entry needs evidence, a date it was last confirmed, and a mechanical check that the things it names still exist. Contradictions replace the old entry rather than sitting beside it. And a scheduled job prunes the lot and opens a pull request, so a person decides what goes.

Agents trust memory more than they should

Memory is loaded before the agent has looked at anything. In Claude Code, CLAUDE.md files and the auto memory index are both loaded at the start of every conversation. That’s the point: the agent starts with context. It’s also the problem, because the agent reads your notes before it reads your code.

When the two disagree, the note has a head start. It’s written in your voice, it sounds authoritative, and it costs nothing to believe. Checking the code costs a tool call.

The docs say as much. Claude treats memory as context, not enforced configuration, and if two instructions contradict each other, Claude may pick one arbitrarily. Arbitrarily is a polite word for “a coin toss you didn’t know you were making”.

A wrong note costs more than a missing one, because nobody thinks to question it. No memory means the agent goes and looks. Stale memory means it doesn’t.

Evidence and dates on every entry

My first rule is evidence-or-no-entry. A memory says where the fact came from: a file path, a commit, a PR, or “you told me on this date”. If the agent can’t point at anything, it doesn’t get written down. Guesses belong in the conversation, not in the file every future session reads first.

The second rule is a last-confirmed date in each entry’s frontmatter:

---
name: test-command
last-confirmed: 2026-09-14
---
Run `pnpm test:unit` before committing; `pnpm test` also starts the e2e suite.
Source: `package.json` scripts.

Claude Code already stamps memory files with a modified timestamp when it writes them. Useful, but it answers a different question. Modified tells you when someone last changed the note. Confirmed tells you when someone last checked it was true. A note can be checked and found correct a dozen times without changing a word, and that’s exactly the note you want to trust.

So when the agent uses an entry and it holds up, it bumps the date. When an entry hasn’t been confirmed in N weeks, it gets flagged for review. Pick N to match how fast your codebase moves. A busy repo needs a shorter fuse than a quiet one.

Mechanical checks for entries that name files, functions or flags

Dates tell you what’s old. They don’t tell you what’s wrong. For that, the cheapest win is the boring one: if an entry names a file, function or flag, check it still exists.

No model needed. Pull everything in backticks out of each memory file and look for it in the repo:

// check-memory.mjs <memory-dir> [repo]: flag stale or broken entries
import { readFileSync, readdirSync, existsSync } from 'node:fs';
import { spawnSync } from 'node:child_process';
import path from 'node:path';

const [dir, repo = '.'] = process.argv.slice(2);
const STALE_WEEKS = 8; // your N
const cutoff = Date.now() - STALE_WEEKS * 7 * 864e5;
const flag = (msg) => { console.log(msg); process.exitCode = 1; };

for (const file of readdirSync(dir).filter((f) => f.endsWith('.md') && f !== 'MEMORY.md')) {
  const text = readFileSync(path.join(dir, file), 'utf-8');
  const confirmed = text.match(/^last-confirmed:\s*(\S+)/m)?.[1];
  if (!confirmed || Date.parse(confirmed) < cutoff) flag(`${file}: not confirmed since ${confirmed ?? 'ever'}`);
  for (const [, ref] of text.matchAll(/`([^`\s]+)`/g)) {
    const found = ref.includes('/')
      ? existsSync(path.join(repo, ref))
      : spawnSync('git', ['-C', repo, 'grep', '-qF', '-e', ref]).status === 0;
    if (!found) flag(`${file}: \`${ref}\` not found in ${repo}`);
  }
}

Paths get an existence check. Everything else (function names, flags, script names) gets a fixed-string git grep. It’s crude. A name that survives in a comment will pass, and it can’t tell you the function now does something different. It doesn’t prove an entry is right. It proves some entries are definitely wrong, for free.

If you’d rather not run your own, Claude Code now has /doctor prompt-audit, which looks for references to files or commands that don’t exist and for files that contradict each other. It covers your instruction files, not the auto memory folder, and it proposes edits rather than making them. I still like a script I can run in CI that exits non-zero.

Contradictions: replace, don’t archive

When a new fact contradicts an old entry, the instinct is to keep both. Add “UPDATE:” underneath, or move the old one to an “archive” section, just in case.

Don’t. The agent reads the archive too. Now it has two answers and, per the docs above, may pick either.

The rule is simple: update the entry in place and delete the old version. Git is the history. If your memory lives in the repo, git log -p shows what it used to say and when it changed. If it doesn’t, that’s an argument for putting it there. Either way, the file the agent reads should hold one answer to each question.

Same for duplicates. Before writing a new entry, check whether one already covers it, and edit that one. Two entries that say nearly the same thing will drift apart, and then you’ve built your own contradiction.

A size cap and a scheduled prune PR

Memory that only grows will stop being read. Claude Code loads the first 200 lines or 25KB of MEMORY.md, whichever comes first, and anything past that isn’t loaded at session start. The docs also recommend keeping each CLAUDE.md under 200 lines, because longer files reduce adherence.

So I treat the size limit as a budget, not a ceiling. Stay well under it, and a new entry has to be worth more than the weakest one already there. A cap is what forces the prune to happen at all.

The prune itself runs on a schedule and ends in a pull request:

  1. A scheduled GitHub Actions workflow runs weekly.
  2. It runs the checker above and saves the findings.
  3. A headless Claude Code run gets the findings and one job: for each flagged entry, confirm it against the code and bump the date, fix it, or delete it. Its tools are limited to reading and editing.
  4. The workflow commits the result to a branch and opens a PR.

The agent never merges. Deleting memory is a judgement call, so a person makes it, in a diff, where it’s cheap to say no. It’s the same shape as the guardrails on my publishing agent: the agent edits, a script pushes, a human merges.

Two caveats. Auto memory is machine-local, stored under ~/.claude/projects/, so a CI job can’t see it. The scheduled PR covers memory you’ve committed to the repo; for the rest, run the checker locally now and then. And in a public repo, GitHub disables scheduled workflows after 60 days with no repository activity. A quiet repo is exactly the one where you’d forget to notice.

If you’re building your own

  • Demand evidence for every entry. If the agent can’t say where a fact came from, it doesn’t get remembered.
  • Date confirmation, not just edits. A last-confirmed field tells you what’s been checked lately; flag anything past N weeks.
  • Check names mechanically. A grep for every file, function and flag an entry mentions catches the worst rot for free.
  • Replace contradictions and delete the old entry. One answer per question; git keeps the history.
  • Cap the size and prune on a schedule. Let an agent propose the cuts in a PR, and let a person merge them.

The same idea runs through the one inbox post: anything you store can go stale, so derive what you can and check what you can’t.

More in the Working with AI agents series.

ShareLinkedIn

Liked this?

Get the next field note

New posts and tools on engineering with AI agents and serverless, when they're ready. No schedule, no spam.

RSS feedFollow on LinkedIn

Related reading