I cut my agent's context by 42%, then made it worse

Every session my agent started by loading 36,732 tokens before I had typed anything.

I knew it was bad. I did not know it was that bad, because I had never measured it. I had been estimating, and my estimate was low by roughly half.

The cause was a convenience that defeated the design

There was already a routing system. Files were meant to load on demand: you ask about pricing, the pricing file loads, nothing else does. That was the whole design and it was working correctly.

Sitting above it was an import list in the project instructions that pulled in fourteen files unconditionally. Product notes, design system, voice guide, stack documentation. All of it, every session, whether the task was a typo fix or a schema migration.

The imports short-circuited the routing. The lazy loader never got asked for anything, because everything had already arrived.

This is the more general trap. The expensive thing was not a bad architecture. It was a convenience layer bolted on top of a good one, doing the exact thing the good one existed to prevent.

The fix

Imports went from fourteen files to four: the index, the company one-pager, the behaviour rules, and the personal context. Everything else moved behind the routing table it should have been behind already.

The behaviour file itself went from 376 lines to 110, with the heavy procedural sections split into trigger-tagged sub-files that load when the trigger fires.

36,732 tokens to 21,188. A 42% cut, with no capability lost.

Nothing got worse. The agent still had everything it had before; it just had to ask.

Then I did the same thing again and it failed

Riding the win, I audited for more. Five files were over 2,000 tokens. I picked the design system file at 2,279 and split it along a seam the file itself documented: marketing mode, dashboard mode, buyer mode, plus shared tokens. Four files out of one. Textbook.

Before committing, I measured each loading path.

Path	Before	After	Change
Marketing only	2,279	2,767	+488
Dashboard only	2,279	2,829	+550
Both modes	2,279	3,602	+1,323

Every single path got worse. I reverted the whole thing.

Why splitting cost more than it saved

Two reasons, and both generalise.

Every file has a floor. Frontmatter, a title, a line explaining what the file is and when to read it, cross-links to its siblings. Call it 400 to 500 tokens before a single useful sentence. Split one file into four and you have paid that four times.

The shared part still loads every time. The design tokens were needed in every mode. Splitting them out did not stop them loading; it just gave them their own overhead. The only content that genuinely saved anything was the mode-specific material, and there was not enough of it to cover the cost.

A clean conceptual seam is not the same as a clean loading seam. The file was badly organised for reading and correctly organised for loading, and I had optimised for the wrong one.

The actual lesson

I measured the first change and it was a win. I would have measured the second change afterwards too, and found the regression, and reverted — but I would have written four files, restructured the cross-links, and updated every reference first.

The measurement took two minutes. Writing the files took most of an hour.

Measure before you write, not after. Not as a general principle about being rigorous. Specifically because the cheap step and the expensive step are in the wrong order by default, and nothing about the work reminds you to swap them.

What to do instead

Before splitting any context file, get three numbers: what loads today, what would load on each path afterwards, and the fixed cost of a new file in your setup. If the third number times the number of new files exceeds the saving, stop.

For agent memory specifically, the rule of thumb I now use: do not split below about 1,500 tokens. Under that, the file’s own overhead is a large fraction of its content and you are paying to be tidy.

And treat any unconditional import list as suspect. If you have built lazy loading, something that loads eagerly above it is not a shortcut. It is the thing stopping your design from working.

Related

• Agent memory - the three-tier structure this sits in.
• Claude Code orchestration - what should be loaded when.