Context rot: when agent instructions stop matching the code

Missing context is a cost. The agent does not know, so it looks, and looking takes time and tokens. Annoying, bounded, self correcting.

Stale context is a different category. The agent does know, or believes it does, so it does not look. It acts on a statement that was true when someone wrote it and is not true now. Nothing in the system flags the difference, because a stale note and a fresh note are the same characters in the same file.

That is context rot, and it is the tax on every attempt to give agents memory by writing things down.

Where it comes from

Not from carelessness. It comes from the fact that written guidance and the code it describes live in different places and change on different clocks.

Someone writes "the rate limiter runs before auth, so unauthenticated requests are counted against the caller IP." True. Correct. Useful. Four months later a pull request reorders the middleware for an unrelated reason, and the sentence is now false. The pull request was reviewed, tests passed, and nobody thought about a line in a markdown file in a different directory, because there is no mechanism that would have made them think about it.

The half life is shorter than people expect. Anything that describes ordering, layout, naming, ownership, or the relationship between two services will typically be falsified within a release cycle or two. Anything describing intent, the reason behind a choice, tends to survive much longer.

Why it is worse than nothing

Three reasons, in increasing order of cost.

It suppresses investigation. The value of a written finding is that the next agent skips the search. That is exactly what makes a stale finding expensive: it buys the skip and delivers a wrong premise.

It is confidently stated. Written text carries no uncertainty by default. "The rate limiter runs before auth" reads with the same authority whether it was verified this morning or eighteen months ago. An agent has no way to weigh it, so it weighs it fully.

It compounds. A wrong premise produces work built on the wrong premise. That work gets reviewed against the same wrong premise, merged, and occasionally written down, at which point the rot has reproduced.

The practical result is that teams learn not to trust the written layer, which is a rational response and which also destroys the entire benefit of having one. Everyone has met a wiki nobody reads. This is how it got that way.

Freshness is not a timestamp

The common fix is to date things. Reviewed on this date, owner is this person, review again in six months. It helps a little, and it does not address the actual question.

A date tells you when someone last looked. It does not tell you whether the thing is true. A claim written yesterday about a file that changed this morning is stale. A claim written two years ago about a module nobody has touched since is fine. Age correlates with staleness weakly enough that treating them as the same thing produces both false alarms and false confidence, and after enough false alarms people stop reading the badges.

Ownership review has the same shape. It moves the work to a human on a schedule, and the schedule has no relationship to when the code moved.

What can actually arbitrate

The repository already contains the answer. Not in prose, but in a form that can be checked.

Git knows when the file the claim is about last changed, and on which branches, and in which pull request, and who reviewed it. Tests know whether the behaviour a claim describes is currently asserted anywhere. History knows whether the reason a claim gives was ever discussed, and where.

This gives a sharper definition of a stale claim than a calendar can. A claim is worth re-checking when the evidence it rests on has moved. Not when six months have passed. If the middleware file has not been touched since the claim was made, the claim is as good as it was. If it has been touched, the claim needs to be reconciled against what is there now, and until it is, it should be presented with that uncertainty attached rather than as a plain fact.

That is a mechanical property, and mechanical properties can be computed rather than remembered.

What follows from taking it seriously

If you accept that framing, a few things change about how knowledge should be stored.

Claims need to be separable from evidence, so a claim can be re-checked against the thing it came from rather than re-asserted. Claims need versions, because a claim that was true and is now false is a different object from a claim that was always wrong, and the difference matters when you are trying to understand a system's history. Claims need branch awareness, because "true on main" and "true on the release branch" are routinely different answers, and any system that flattens them will be wrong for half the team.

And retrieval needs to carry the reconciliation result, not just the text. An agent that receives "the rate limiter runs before auth, and the file this rests on changed in PR 1204 after this was recorded" behaves correctly. It checks. An agent that receives only the sentence does not.

This is the part of the problem REM exists for: evidence is immutable, claims are versioned, git governs temporal and branch validity, and what is retrieved carries whether it still holds. The alternative is the wiki everyone has and nobody reads, pointed at agents instead of people, at machine speed.