The project memory of my personal website is a single Markdown file. Every new chat with my coding agent reads it before doing anything else. It holds the rules of the project, the current state of things, and the decisions I do not want to explain twice. For a while it worked very well. Then it kept growing, because adding a line is always easier than removing one.
On 7 October 2026 I looked at its size. It had reached about 37,000 tokens. That is a lot of text to load at the start of every conversation, and most of it described things that were finished, replaced or no longer true. I cut it to about 3,000 tokens, a reduction of 92%, and I did not delete any information to do it.
What was wrong with the long version
A long memory file feels safe. Everything is there, so the agent should know everything. In practice it does not work that way.
The agent reads the whole file with the same attention. A rule that matters every day sits next to a note about a problem I fixed weeks ago. Both look equally important. When an old fact contradicts a new one, the agent does not always pick the new one. It may follow the paragraph that sounds more confident, or the one that is more detailed, and old notes tend to be detailed because I wrote them while I was fighting the problem.
Stale facts are not neutral. They cost money, because every token is paid for in every chat. They cost attention, because the important rules get diluted. And they mislead, because the agent treats what it reads as current truth. It cannot know that a section is history unless the file says so.
How I split it
The fix was structural, not editorial. I did not try to write the same content more tightly. I separated two kinds of text that had been mixed together:
- A short core that is always read: the rules of the project, the current state, and the decisions that still apply.
- An archive folder with the full history: the previous complete version of the memory, older guides and longer notes, each in its own file.
- Links from the core to the archive, so the agent knows where the details live and opens them only when a task needs them.
The archive has a small README that says what each file is. The core says, in one line, that the archive exists and when to look there. Nothing was lost. The old text is still in the repository, still searchable, still readable by me and by the agent. It just no longer costs anything in a chat that does not need it.
Every chat now starts by reading less than a tenth of what it used to.
The rules I keep now
A split like this decays if nobody guards it. So I keep a few rules for the core file:
- It stays under 12 KB. When it grows past that, something moves to the archive before anything new goes in.
- It describes the present. If a fact is only true historically, it belongs in the archive.
- Decisions are written as decisions: what we do, in one sentence, not the discussion that led there.
- Details are linked, not copied. One place for each long explanation.
A memory file is not a diary. It is the briefing you give a new colleague on their first morning, and the agent is a new colleague every single chat.
The third rule matters more than it looks. A paragraph that says "we tried A, then B had problems, so for now we are leaning towards C" gives the agent three options and a mood. A line that says "use C" gives it one instruction. If I want the reasoning, I link to it.
The size limit is the rule that makes the others work. Without a number, every addition looks reasonable on its own. With a number, each new line has to compete with what is already there, and that forces the question I was avoiding: is this still true, and does every chat need it?
The general lesson
The same applies to any instructions file an agent loads by default, whether it is called .cursorrules, copilot-instructions.md or something else.
People talk about models, prompts and tools when an agent gives a poor answer. Those matter. But an agent working in a repository spends most of its effort on what it reads there: the memory file, the README, the comments, the docs folder. If those are long, contradictory or out of date, a better model will mostly produce better-written mistakes.
So I now treat agent documentation the way I treat code. It has a size budget. It gets refactored when it grows. Old parts are moved out instead of left to rot in place. And when the agent does something surprising, my first question is no longer "what is wrong with the model" but "what did I tell it, and is it still true".
Keeping it under 12 KB is a small habit each time I add something. That is cheaper than an agent that confidently follows instructions I stopped believing months ago.