We wrote that file so our agent would stop asking us the same questions. We kept adding to it until it was 73,769 bytes. Then we checked it against the code, line by line. It was wrong in six places. Each one would have changed what a session did.
It claimed 41 commands and 65 MCP tools. When we checked, the binary had far more commands than that and fewer tools. Under that sentence sat a whole section arguing the command list was under control, built on both numbers. One count had gone up and the other down, so a reader could not even adjust for it in their head.
Line 1009 explained how we keep our two clients in step. Line 1032 said we had deleted the second client. Both lines load into every session and neither one wins. A markdown file cannot say that one line replaced another, so the session goes with whichever one it happened to notice.
It named a test directory that no longer exists and described it as a suite with a fixture per schema version. It was deleted along with the old client. A session told to add a fixture there goes looking and finds nothing. Then it either makes the directory up or quietly stops trusting the file.
It said a tools folder held three test harnesses that compared the two clients. They had been deleted long before. It named a README for the installed brain that was never written.
And one bullet contradicted itself. It said those harnesses "are kept for reading, not for running" and four lines later said they had been deleted. Same bullet, same file, both loading into every session since.
Nobody was careless. Nothing in a markdown file ever expires or gets replaced, so every one of those lines is still there, stated with full confidence about code that has since changed.
When a line is missing, the model goes and looks. When a line is out of date, the model acts on it in your name and what it produces looks exactly like what it produces when it is right.
Four of the six would have sent a session the wrong way without any sign of doubt. Nobody is making anything up. The model is repeating what it was told.
About 17,000 tokens sit in the context window on every turn, before anyone types a word. The problem is the space, not the bill. Caching makes those tokens cheaper but they still fill the window. The window decides how far a session gets before the agent has to compress its history and loses track of what it was doing.
Here is what should settle it. The agent opens the files every time. It has to and it is right to. Nothing in that file says when a line was written or whether it is still true. Reading it, you cannot tell the six bad lines from the hundreds of good ones. So either you trust all 73KB, which we just showed is wrong six times, or you check what matters, which means reading the code.
Look at how we found the six. We did not read the file. We read the code and compared. A file meant to save you from reading the code can only be checked by reading the code.
It was 8,281 bytes at the start and 73,769 when we checked it. 43 commits touched it. Two made it smaller, by 191 bytes between them.
One of those two deleted a whole retired client from the project. Thousands of lines of code went in one change and it took 190 bytes out of the file that describes the project. The rest of that round of work left the file 15KB bigger.
Nothing in a markdown file fades and nothing replaces anything, so the only edit anyone ever makes is to add more. When did you last delete a paragraph from yours?
When we did the audit, 48 of the 192 memories in this project's own brain had a commit stamp. Recall tells you, fact by fact, whether the code has moved. Four said tree unchanged since stored, so a session can use those without opening a file. The other 44 said N commits since, re-check against source. That still beats the markdown file, which said nothing about the same 48 facts, so the only safe move was to re-read everything. With the brain the session knows which four it can skip and exactly which 44 to check. You still re-read some code, but only where it is needed.
--supersedes makes the new fact replace the old one and a search in the old words gets the new answer. Our "two clients in step" line and our "second client deleted" line could not both have been current. One would be the answer and the other would be history.
Infrastructure facts never fade. "The box is rebooting" loses half its weight every four days and is buried within two weeks without anyone deleting it. Fading deletes nothing. The memory just stops ranking above things that still matter.
The brief ranks what it has, cuts the least important parts, names what it cut and prints the command to see the rest. There is a number stopping it and that is the whole difference between a brief and a file. By default it is 6,000 bytes, about 1,500 tokens, against roughly 17,000 for the file.
Only the person who made a decision can make it wrong, never a commit. Flagging one as stale just invites people to argue it again. So the staleness warning stays on a short list of types on purpose: a warning that shows on every memory is one everybody learns to skip.
A script can only measure size and size is the weakest point on this page.
Open your CLAUDE.md, your AGENTS.md or your .cursorrules. Pick five lines you can check: a file path, a count, a command name, a directory, a version number. Check each one against the code.
Then decide whether you want the next five years of that file loading into every session you run.
$ curl -fsSL https://brain.fightclub.pro/install.sh | sh # then, in the project you want it to remember $ ns-brain init
Every number on this page comes from ns-brain's own repository. All six mistakes are in its git history next to the commit that fixed each one.