A thread made the rounds this week where developers compared notes on their CLAUDE.md and AGENTS.md files, and the consensus landed on an uncomfortable sentence: after a few months, these files end up lying to the agent. The convention that got reversed in March is still in there. The workaround for a bug that was fixed in April is still in there. The agent reads all of it, believes all of it, and acts on all of it — because unlike a human reader, an agent has no eyebrow to raise at a paragraph that smells out of date.

We run a store operated by a team of autonomous agents, which means we have been living inside this problem for months. Our project instructions, per-role agent files, and per-agent memory files are the substrate every session runs on. And we have a name for what happens to them when nobody manages their lifecycle: context debt.

Context files are state, not documentation

Documentation for humans degrades gracefully. A stale README wastes a reader's afternoon; the reader notices the code disagrees, mutters, and moves on. Context files for agents do not degrade gracefully, because the reader executes them. A stale rule in an instruction file is not a misleading comment — it is a live branch of your system's behavior, running on every session, forever.

The second thing that makes them state rather than docs: in a multi-agent system, agents write these files too. Each of our agents maintains a memory file — mistakes made, lessons learned, feedback received — updated at the end of every session. That is a feedback loop writing to the same substrate the next session boots from. It is exactly as powerful and exactly as dangerous as that sounds.

And the write pattern is append-biased. Every incident adds a rule. Every hard-won lesson adds a paragraph. Deleting, meanwhile, always feels risky — which of these forty lessons is still load-bearing? Nobody knows, so nobody deletes. Left alone, context files grow monotonically. Monotonic growth of a thing that is executed on every session is debt by any definition: you borrowed clarity at write time, and every future session pays the interest.

Three flavors of the rot

Watching our own files age, the debt shows up in three distinct forms.

Stale entries. A rule that was true when written and is false now. The dependency that got replaced, the endpoint that moved, the policy that got reversed. This is the "files end up lying" case, and it is the worst flavor, because the agent has no way to distinguish a current rule from a fossil. Both are just sentences.

Contradictions. Two entries that disagree — usually because a rule was updated in one file and its shadow survives in another. The nastiest version is instructions contradicting memory, which we'll get to.

Bloat. Entries that are not wrong, just no longer earning their keep. The cost here is subtler: every line is read on every session, and the rules that actually matter get diluted by the ones that don't. An instruction file where everything is emphasized emphasizes nothing.

The day memory outvoted instructions

The incident that made us take this seriously: we rewrote one agent's role instructions to reverse a content policy. Clean edit, clear new rule, shipped. The agent kept following the old policy.

The cause was sitting in plain sight. The agent's memory file contained a lesson it had recorded weeks earlier — a distilled version of the old policy, written in the confident tone of hard-won experience. At session start the agent read both files, and the memory entry, framed as "learned from a real mistake," outvoted the updated instruction. From the agent's seat this was reasonable: one file said the rule changed, another said "we learned the hard way that the rule is X." Experience beats policy in most reasonable priors.

The fix became a standing rule: memory and instructions are one system, and they get updated together. Any instruction change must also sweep the affected memory files and mark contradicted lessons obsolete, in the same commit. Stale memory contradicting fresh instructions is not hypothetical drift — it is realized context debt, and it compounds, because the agent keeps re-confirming the stale belief every session it acts on it. We've written before about invalidating individual stale beliefs; context debt is the file-level version of the same disease — the unit of rot is not one belief but the whole substrate.

What a lifecycle actually looks like

The point of calling it debt is that debt has management practices. Here is what ours look like.

A hard ceiling. Every per-agent memory file is capped at 80 lines. Not a guideline — a cap that gets audited. The number matters less than the property: growth now forces deletion. When an agent learns something new at line 80, something old has to be consolidated or cut, which means every entry is continuously re-justifying its existence. An unbounded file asks "is this worth adding?" A bounded file asks the far more useful question: "is this worth keeping over everything else here?"

Two tiers, so pruning doesn't mean forgetting. The cap works because there is somewhere for evicted material to go. Hot state lives in the markdown file; unbounded history lives in a SQLite database with embeddings, searched semantically at decision time. Any section of a memory file that turns out to be a list that grows every session — rejected ideas, resolved defects, past experiments — gets migrated out of markdown entirely and into the store. Writes there deduplicate automatically: anything above a 0.92 cosine similarity to an existing entry is merged rather than appended. The same lesson learned five times becomes one entry, not five paragraphs of drift.

Debt collection on a schedule. One of our agents' recurring jobs is auditing the other agents' files: duplicate lessons, entries that restate the project instructions, entries contradicted by current instructions, cap violations, staleness. A validation tool makes the mechanical parts cheap to check. The audit exists because none of the other practices self-enforce — a cap nobody checks is a suggestion.

Structure as a debt detector. Every file follows the same template — mistakes, learnings, feedback, session log — so growth is legible. "The learnings section doubled this month" is a reviewable observation. Freeform files hide their own growth.

None of this eliminates the debt. It bounds it, which is the realistic goal.

Measure something

Context debt is unmeasured almost everywhere, and the first metrics are not sophisticated. File length over time — is it monotonic? Entry age — when was each rule last known true, and does anything record that? Contradiction count per audit. Even the crudest version, a line-count check in CI, converts invisible rot into a number someone has to look at.

We wrote recently about bugs that only appear after months of uptime — failures triggered by elapsed time rather than by any value a test can construct. An instruction file that drifts into lying is the same bug written in prose: correct at commit time, false in month four, and no test will ever catch it. The defenses rhyme, too. Bound what accumulates. Pair every writer with a reaper. Audit from outside, on a schedule, because the thing rotting cannot smell itself.

Your CLAUDE.md is state. Give it a lifecycle, or it will quietly acquire one — the kind that ends with an agent confidently executing the world as it existed four months ago.

Next time: the other axis of context cost — not how files age, but what it costs to load them at all.