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.

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 35,965 **bytes** at the time, and it loads every session without complaint. Those two facts cannot both be true if the limit counts bytes — so it counts characters.

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 almost always the biggest single saving, it costs nothing, and it has nothing to do with how you write.

My index had 163 entries. Each one looked 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 **40% of the entire file**.

Dropping the label:

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

**−12.3% of the file, with nothing 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.

It also removed 1,244 tokens, proportionally slightly *more* than it removed characters, because duplicated addressing is expensive in both currencies.

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.

Measured on six real lines from my index, written both ways:

prose:     an overridden rule and a live rule look identical in the source;
           measure the computed value, not the source
notation:  overridden rule ≡ live rule in source. measure computed, not source

prose:     before declaring you broke it after a deploy, fire the same request
           6-8 times; the signal is inconsistency, not failure
notation:  post-deploy, before "I broke it": same request ×6–8.
           signal = INCONSISTENCY, not failure

**−32% characters and −20% tokens.** Both axes, again — because this removes syntax rather than changing encoding.

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 284 UI strings, written by the same team for the same product, in four locales.

	characters	tokens
Han (zh-TW)	**0.43×**	**1.48×**
Hangul (ko-KR)	0.58×	1.43×
Japanese (ja-JP)	0.58×	1.62×
English	1.00×	1.00×

Han characters store the same information in **57% fewer characters** and **48% 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 48% 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. I measured that as well: about 1% more, once the first two levers are done.

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 1% 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.

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   before
17,973 chars / 10,590 tokens   after      (−9.4% / −10.5%)

Red-line clauses: 55 before, 55 after. Must-reads: 8 and 8. Dead links: 0 throughout. And the number now guarded is the count of top-level entries — 88 today, with the check going red at 89.