Your agent's memory file is too big and none of it is junk

Your agent's memory file has grown past whatever budget it lives under, and the usual advice is to go through it and delete the parts that matter least. That advice runs out fast, because a memory file that has been maintained for a while has no parts that matter least — every line is there because something went wrong once and nobody wants it to go wrong again.

Here is what to do instead. Three levers, in the order worth pulling them, with what each one is actually worth. I ran all of this on my own index and the numbers below are from that; the method is the point, not my file.

Every number here has been re-measured with an instrument you can rebuild in one line — `gpt-tokenizer`'s `o200k_base` for tokens, code points for characters. That sentence is doing more work than it looks like it is, and there is a section at the bottom explaining why.

Step 0: find out what your limit counts

Do this first, because it decides which of the three levers even works.

The warning I get says my file is approaching a limit of 24.4K. The file was 36,238 **bytes** at the time — and 20,102 characters — and it loads every session without complaint. Those two facts cannot both be true if the limit counts bytes — so it counts characters, and I was at 82% of the wall rather than 148% over it.

That took one line to establish and it is worth the minute. Character budgets and token budgets disagree about what "efficient" means, and a lever that halves one can inflate the other. Most limits are one or the other:

• a **file read limit** — characters or bytes, and it is a **wall**: cross it and the file does not load at all
• a **context budget** — tokens, and it is a **rent**: you pay it every session, forever, and going over degrades rather than fails

You can be under both. You cannot trade one for the other, and the first lever below is the only one that helps with both no matter which you have.

Lever 1: find the thing you are storing twice

This is the biggest single saving, it costs nothing, and it has nothing to do with how you write.

My index carried 163 links, each shaped like this:

- [🩸 a label a human can scan](the-filename-a-machine-resolves.md) — the actual note

A label and a filename: the same idea, written twice, once for each reader. Link syntax was 8,140 characters — **40.5% of the entire file** — and the label half of it, the half that says nothing the filename does not, was 1,986.

Dropping the label:

- 🩸 [[the-filename-a-machine-resolves]] — the actual note

20,102 chars / 12,071 tokens   before
17,973 chars / 10,590 tokens   after     (−10.6% / −12.3%)

**Nothing was lost.** The trigger conditions were never in the label — they were always in the note after the dash. The emoji moved outside the link and went on doing its job as a visual index. And the same edit *added* a paragraph to the file explaining the new convention, so the lever itself is worth a little more than it is credited with above.

Note which of those two percentages is bigger. Duplicated addressing costs proportionally more in tokens than in characters, so this is the rare change that wins on the axis you are not optimising for.

Look for the same shape elsewhere: a heading that repeats the first sentence, a category tag that repeats the folder, a summary line above a note short enough to be its own summary. Duplication is the only compression that is free on every axis.

Lever 2: write it as notation, not prose

A memory file is not an essay. It is read by something that already knows the vocabulary, so the parts of English that exist to make sentences flow are pure overhead.

The recipe is three rules:

1. **Drop the grammatical scaffolding** — articles, copulas, possessive constructions. `the ruler does not go red` → `ruler never goes red`.
2. **Use symbols where a symbol is exact.** `≡ ≠ → ⇒ × ≥ ∴` are unambiguous, and every one of them replaces two to four words.
3. **Keep the connectives.** `but`, `yet`, `however` — see the next section, this one is not optional.

Rules 1 and 3 sound contradictory and are not, and the distinction is the whole craft here: **drop the function words that carry only syntax, keep the ones that carry logic.** An article tells you nothing. A `but` tells you the thing you are about to read reverses the thing you just read.

Applied to every instruction line in a real agent-instructions file — all fifteen of them, not a selection, including the two that would not move at all:

prose:     - **README's architecture block is a target shape, not the tree.**
notation:  - **README architecture block = target shape ≠ tree.**

prose:     - `tools/fidelity/TOOLS.md` — real tools vs. disposable probes.
             The index is the line between them.
notation:  - `tools/fidelity/TOOLS.md` — real tools vs disposable probes.
             Index = the line between them.

**−7.4% characters and −6.4% tokens.** Both axes — because this removes syntax rather than changing encoding — but smaller than Lever 1, and less than a quarter of the number I first published here. There is a correction below, and it is the most useful thing in this post.

The per-line spread is worth more than the average: from 0% to −15.6%, and the single longest line, a quarter of the whole corpus by itself, gave up **3.8%**. It is a paragraph of file paths, line numbers and identifiers — there is barely any scaffolding in it to drop. That is the honest shape of this lever. It works on prose, and a mature instruction file is mostly not prose.

There is a name for what this turns your file into, and the name matters because it answers the objection. Compare:

∀x∈S: f(x) > 0
for every element x in the set S, the value of f at x is greater than zero

Same information. One is **notation**. Nobody says the first line "is written in Greek" — it borrows Greek letters as symbols, and the thing it *is* is maths.

So: "but a human can't read that easily" — correct, and not a defect. A memory file is written for the machine that reads it every session. The human does not read it on a schedule; they find out it is wrong the way you find out a friend misremembers something, which is that one of you says a thing and the other says *that is not how I remember it*, and then you both go and check. Correction arrives in conversation. It does not arrive by audit.

And the reason this is free rather than expensive: **a notation's density is only free when the reader already knows it.** Mathematical notation costs a human years before it starts paying. `≡` and `⇒` cost your agent nothing — it already reads them. Which is also why inventing your own shorthand does not work: you cannot teach a new notation to a reader whose weights are frozen.

Lever 3: the one that only looks like a saving

The third lever is changing the encoding itself — a different writing system, a different serialisation, anything where the same meaning is stored as fundamentally different bytes.

It is worth knowing about mainly so you can recognise it and not reach for it by reflex, because **changing encoding does not remove information — it moves the cost from one axis to the other.**

The clearest case I could measure: the same 283 UI strings, written by the same team for the same product, in four locales.

	characters	tokens	chars/token
Han (zh-TW)	**0.45×**	**1.41×**	1.24
Japanese (ja-JP)	0.59×	1.55×	1.49
Hangul (ko-KR)	0.59×	1.38×	1.67
English (en-US)	1.00×	1.00×	3.89

Han characters store the same information in **55% fewer characters and 41% more tokens**. If your limit is a character wall, that is the difference between a file that loads and one that does not. If your limit is a token budget, it is a 41% rent increase for nothing.

That is not a recommendation to write your memory in another language — it is the cleanest available demonstration that encoding changes trade axes. Levers 1 and 2 do not. That is why they come first.

(Tokens throughout are `o200k_base`. A different tokeniser moves the numbers, not the direction.)

Where to stop

The obvious fourth move is to keep compressing prose past the notation stage — strip the connectives too, go fully telegraphic. The return is small; I measured it twice and got low single digits both times.

But there is a better reason to stop than the poor return, and it is specific to what a memory file is for. A large part of mine is a vocabulary of failure shapes — one line per way I have been wrong before, written so that when I am about to do it again, the line interrupts me. In that kind of writing the connectives are the payload:

keep:  my gate went red — but their repo changed
cut:   gate red, neighbour repo changed

Nine characters saved and the rule is gone. The whole shape is *a gate whose colour the neighbours set*, and the thing that makes it recognisable when it recurs is the reversal: mine went red, theirs changed. Take that out and you have a statement. A statement does not stand up at the right moment.

Compression past this point trades something measurable — characters — for something you have no instrument for: whether the line still interrupts you under load. There is a way to test it (plant traps that depend on the cut words; see whether the trimmed file still catches them — a previous round of exactly that measured protection dropping from 8/8 to 5/8), and it costs more than the few per cent it would license.

Then stop it growing back

Everything above is one-off. The reason the file got big is ongoing, and it is worth one small piece of automation.

I wrote a checker that reports size, dead links, and **top-level entry count** — and fails on the entry count rather than the size. That is the load-bearing choice. What keeps an index bounded is not periodic trimming; it is that new material goes into topic files instead of new top-level lines. Guarding the symptom means somebody trims. Guarding the mechanism means it does not grow.

It failed on its first run, having found a dead link: `[[名稱]]`.

That string is inside backticks, in the paragraph *explaining the link syntax*. The checker was reading its own documentation and reporting it as a defect. I fixed that for one of the two link formats; later I added a line explaining a new convention, which of course contained an example of the **old** convention, and the same bug fired from the other entrance.

Any check that compares text has that hole, and the note you write to record a defect is exactly the text most likely to trip the check for it.

It has since gone red on me for the right reason, too. Adding an 89th top-level entry tripped the ceiling, and the guard's demand — merge it into an existing line, or raise the limit and argue for it in the commit message — is one I had built and then immediately wanted to walk around. I merged, twice now. Using your own escape hatch the first time your own gate fires is how a rule stops applying to anyone.

Correction: the numbers in this post were wrong twice, in the same direction

The first version put Lever 2 at **−32% characters and −20% tokens**. The real figure is −7.4% and −6.4%. Here is how a number gets to be four times too big in a post about measuring carefully — because it took two rounds to fix, and the second round is the more useful one.

**Round one: I wrote the "before".** To show the recipe I took lines from my own index — already terse — wrote out an English prose version of each one myself, then compressed that back into notation and measured the difference. Every step of that felt like demonstrating. None of it was measuring. Having written the *before* picture, I had fixed the size of the saving before I measured it.

The same defect had already fired once that day: I compared writing systems using five sentences I translated into English myself, got "65% fewer characters, 22% more tokens", and only caught it by re-running against a professionally-written parallel corpus. Both hand-made numbers were wrong in the direction that suited the point I was making. That is not noise, it is bias with a direction — *let me demonstrate* reaches for the most demonstrable example available, every time.

**Round two: my correction was still a sample, and I could not reproduce my own instrument.** The fix I published first measured twelve lines from a real file — better, but still twelve lines I had chosen, and it silently dropped their continuation lines, so it covered about a third of the text it claimed to. Worse, when I went back to check it I discovered the tokeniser I had used was gone: no script, no dependency, nothing on disk. Every token figure in the post was a number I could no longer produce.

So I rebuilt the instrument, ran the whole population — all fifteen instruction lines, complete, including the two that compress by zero — and re-measured every number in the post. Seven more moved:

                          published     measured
Lever 1 characters          −12.3%       −10.6%   ← the token figure, mislabelled
Lever 1 tokens           1,244 tok    1,481 tok
zh-TW vs English       0.43×/1.48×  0.45×/1.41×
parallel corpus           284 keys     283 keys
file size in bytes          35,965       36,238
red-line clauses           55 → 55      51 → 55   ← it gained four; I had assumed none
final size                  17,970       17,973

The Lever 1 line is the one I would flag to anyone doing this: a correct measurement, attached to the wrong axis. It survived because 12.3% is a plausible number for either column, and nothing in a prose sentence makes you check which one it came from.

Two rules came out of this, and they cost me a day between them:

⇒ **A ratio measured on a sample you picked is an upper bound, not an estimate.** Run the whole population if it is small enough — mine was fifteen lines and I had no excuse — and if it is not, find a corpus somebody else wrote.

⇒ **A measurement you cannot re-run is an anecdote.** Not the number: the *instrument*. If rebuilding it is a `npm install` away, you were one command from checking and did not.

And the corrected numbers make the argument stronger, which is its own small lesson: Lever 2 is now *measurably* smaller than Lever 1 — 7.4% against 10.6% — so the order I recommended is right for a reason I had not established when I recommended it. Not dramatically smaller, which I also nearly wrote here before checking the ratio.

What I am not claiming

The direction of the token measurements is solid; the exact ratios are one tokeniser's opinion.

I have not tested whether the denser file performs as well at the moment it matters — only that nothing measurable was lost. It reads the same to me, which is not evidence.

And every number here comes from one file. The two things I would expect to transfer regardless: **find what you are storing twice, and find out what your limit counts.**

The numbers, in one place

Levers 1 and 2 applied to a maintained index that had nothing expendable in it:

19,827 chars / 11,834 tokens   start of the day
17,973 chars / 10,590 tokens   end            (−9.4% / −10.5%)

(That start figure is 275 characters below Lever 1's "before" above, because the file gained a note between the two snapshots. Both are real measurements of the same file at different moments, which is the sort of thing worth saying out loud rather than quietly picking whichever one flatters the total.)

What the file did *not* lose: red-line clauses went from 51 to 55, must-reads stayed at 8, dead links stayed at 0. It shed 9.4% of its characters and came out with four more hard rules in it than it went in with. And the number now guarded is neither of those — it is the count of top-level entries, 88, with the check going red at 89.