A memory file can succeed at storage and silently fail at availability. Stored is not loaded.
Claude Code keeps an auto-memory file, MEMORY.md, that loads at the start of every session. You write a standing rule into it once and from then on the agent behaves as if it knows the rule. That is the whole contract, and it is why the file accumulates: every rule you add is a rule you never have to say again.
The contract has a quiet edge. Only the first 200 lines — or 25KB — are loaded. When the file grows past that, the entries below the cutoff stop reaching the model, and the agent simply stops behaving as if those rules exist. The file on disk is still perfectly correct.
The distinction matters and is easy to get wrong: this cutoff is a property of MEMORY.md, the auto-memory file. It is not the same thing as CLAUDE.md, the instruction file you author yourself, which is documented as loading in full. If you read this and go worrying about your CLAUDE.md, you have generalized the bug to the wrong file.
We hit this on a long-running project. The entries that went dark were not scratch notes; some were load-bearing standing rules that had been in the file for months. The behavior is well documented by now — #25006 reported the hard limit and the silent truncation in February 2026, #39811 described the operational consequence of it, and #57574 covers the invisibility problem directly. In the version we encountered, there was no operator-visible warning: no error, no truncation marker in the loaded text, nothing at the terminal to say part of the file had not been included. #57574 describes a warning existing but buried in the system prompt — visible to the model, not to the person who would act on it. The current documentation now states the limit explicitly, which is a real improvement over what we ran into.
None of that is the interesting part. The interesting part is what the silence does to the operator.
A rule that is loaded and disobeyed looks like a model problem. A rule that was never loaded looks exactly the same from the operator’s chair — the agent does the wrong thing, confidently, with no reference to the constraint it just walked past. The two cases are observationally identical unless loading is itself observable.
So the first instinct is wrong, and wrong in a way that compounds. You reach for the prompt, the model, the phrasing of the rule. You rewrite the rule to be more emphatic — and the rewrite lands below the cutoff too, so nothing changes, which reads as further evidence that the model is ignoring you. The one hypothesis that would have ended the investigation in a minute — is this text even in the context? — is the one nobody checks, because the file is right there on disk and it looks fine.
The file being correct on disk tells you nothing about whether it was read.Persistence and loading are different guarantees. Only one of them is visible in your editor.That is the general form, and it outlives this particular limit. A persistent-memory system can succeed completely at storage and fail silently at availability. Storage is the guarantee these systems advertise and the one operators check; availability is the guarantee that actually determines behavior. Where the two can diverge without a signal, every downstream failure gets attributed to the model.
Persistent memory needs load observability, not just storage guarantees.
Which is why the useful ask is not a bigger budget. It is a receipt — something that tells the operator, at load time, what actually made it in.
The maintenance answer — keep the file small, prune it when it grows — is not an answer. It puts a recurring human chore in front of a silent failure, and the chore is skipped for exactly as long as everything appears to work. What worked for us was changing the shape of the file so that outgrowing the budget stops being possible.
We should be precise about credit here, because the shape we arrived at is now the documented design. Anthropic’s current documentation describes MEMORY.md as an index whose details live in separate topic files read on demand, and #39811 proposed migrating overflow into topic files behind one-line pointers before we wrote any of this down. We converged on the same structure independently, under pressure, which is mild evidence it is the right structure — but converging on a pattern is not inventing it. What follows is offered as four invariants we would defend, not as a discovery.
The index stays under the budget.
The memory file itself is an index, not a corpus. The most load-bearing entries stay in it verbatim, at the top. Every other entry is reduced to a one-line hook — enough to tell the agent the rule exists and where it lives.
Bulk moves into topic files.
The full text of a cold entry goes into a topic file linked from the index. Nothing is lost; it is relocated. The index carries the map, the topic file carries the detail.
Every file is reachable in one hop.
A topic file that is only reachable from another topic file is a topic file the agent will not find. One hop from the index, always — otherwise you have rebuilt the invisible tail somewhere else, in a shape that looks tidy.
The split deletes nothing.
Every entry that was in the file before the split is in the system after it. Tiering decides what loads first, never what survives.
The first three invariants are logistics. The fourth is a judgment call that gets argued every time, because a split is exactly the moment when deleting looks responsible — you are already in the file, the entries are already in front of you, and some of them look dead.
Deletion needs a signal, and in a memory file the available signal is age — which entry has sat there longest without being touched. Age is a bad signal. The rules that have been in the file the longest are frequently the ones that have been quietly right for the longest. An old entry can be the most important one; it is old because it was settled, not because it stopped mattering.
Tiering is reversible. Deletion is not.
Moving an entry from the top of the index into a topic file is a mistake you can undo the moment you notice it. Removing it is a mistake you notice years later, when the agent does the thing the entry existed to prevent and no one can remember why the rule was there.
The four invariants are what an operator can do alone. They bound the damage; they do not make loading observable, and that is the cheaper half of the problem.
A load-time warning when the index exceeds the budget would have surfaced this immediately — not a marker inside the loaded text where only the model sees it, but a message to the operator, at the moment of loading, saying that part of the file was not included. That is the ask in #57574, and it was already the ask in #25006 in February: make the cap visible. The current documentation states the limit, which helps someone who goes looking; a warning is what reaches someone who does not yet know to look.
The companion ask in #79217 — make the cap configurable — covers the case where the budget is simply the wrong shape for a project. The two together close the class. A visible cap tells you that you crossed it; a configurable cap lets you put it where your project actually needs it. Either alone leaves a gap: a visible cap you cannot move is a recurring alarm, and a movable cap you cannot see is the same silent failure at a higher number.
We do not know how long the tail was dark. Once the entries stopped being read there was no record of it, which is the point of the whole failure mode — there is nothing to look back at. Any duration we gave you would be a guess dressed up as a finding.
We also are not claiming the structure is ours. The index-and-topic-files shape is documented and was proposed publicly before we wrote this; what we can say is that we arrived at it under pressure and that the four invariants are what we would defend if someone argued for a looser version. The narrow claim is that the shape does not depend on knowing the exact threshold — which is the reason we prefer it to keeping the file trimmed by hand, and the reason it survives the limit changing.
Until loading is observable, you can approximate a receipt by hand, and it costs about a minute. Do not ask is the file correct — you already know it is. Ask the agent what the last rule in the file says. If it cannot tell you, that rule has not been in force for as long as you have believed it was.
Related: Context Decay in Long AI Sessions, on the other end of the same problem — constraints that were loaded and then displaced.