Trimming Is Not a Plan: When Our Agent's Memory Index Hit Its Ceiling

Part 4 of this series ended on pruning: give the memory index a size budget, keep each entry to one line, and archive work when it closes. That is what the portal did. The consumer app had the budget and the one-line entries, but it had no archive.

This post and the next one cover what happened when the consumer app's index ran out of room, and the fix the agent proposed once the developer asked for one that would last.

The ceiling

In Claude Code, auto memory is a folder of notes plus an index file, MEMORY.md, with one line per note. The index loads into every session. A note loads only when the agent decides its index line looks relevant.

That gives the index a hard limit. Past about 24 KB it is cut off when it loads, so the lines at the end never reach the agent. Two warnings watch it:

• Our own hook, written in June, fires at a 22 KB soft cap after any write to the index.
• A second warning fires as the index nears the limit and asks the agent to compact it to under about 17 KB.

Three trims, no entries removed

• 5 October. The index reached 25.2 KB and 113 entries, past the hard limit. The agent rewrote every line shorter and got it down to 17.1 KB. The notes themselves didn't change.
• 12 October. The index was at 134 entries and 21.3 KB. The agent shortened every line again, down to 16.8 KB, and kept all 134.
• 17 October. The warning fired in the middle of a bug fix. The agent handed the trim to a background agent, which took the index from 20.5 KB to 17.0 KB. Again, nothing was dropped.

Each trim was done well. Every note survived, every link still resolved, and a backup of the old index went into the session's scratch folder. That was the problem: each trim just squeezed the same content harder.

• The lines were running out of room. The average index line went from about 220 bytes to about 150 on 5 October, and was down to about 115 by 17 October. A line is what the agent reads to decide whether a note applies, and it can't get much shorter and still do that job.
• The index kept growing. It gained three to four entries a day. The first trim lasted seven days before the next warning, and the second lasted five.

The question

Less than half an hour after the background trim, the bug fix was verified on the phone and its pull request was open. The developer typed:

What else we could do to the memory? It's at the edge, keep on trimming isn't a permanent solution

Sorting the index

The agent read the whole index before it recommended anything. The index held 154 entries in 17.2 KB. Sorting them by what each note was actually about turned up three large groups:

• About 31 ticket and pull request records: what a ticket needed, what was decided and what merged. Ticket work added a few of these every day, so most of the growth came from here.
• About 20 procedures: driving the physical test phones, running code inside the app, operating the over-the-air update service, and reading design files by script. These were how-tos, not facts.
• About 20 facts about the code and the backend: a component quirk, a test trap, an endpoint that accepts a filter and then ignores it. These described the repository, not the developer.

What remained was the developer's rules and preferences, facts about the local environment and credentials, open bugs, and decisions still in force. That is what personal memory is for.

Why not split the index?

The obvious alternative is hub files: a single index line for "device testing", say, that points at a sub-index of a dozen notes. The agent argued against it:

An index line is what makes me recall a memory without being prompted. Behind a hub, I'd only find it if I already suspected the topic, and that's exactly how a trap like [this morning's] gets missed.

So the index isn't a table of contents. It is the list of things the agent will notice without being told. Moving a note down a level quietly turns it into something the agent has to know to go looking for.

The agent argued that archiving is safe for one kind of note: finished tickets. Those rarely need recalling until someone mentions them first.

The plan

1. Archive finished ticket work. First lift anything still live out of the note. Then move the note into an archive folder with its own index, which doesn't load.
2. Turn procedures into skills. Until a skill is used, it costs one description line per session.
3. Move code and backend facts into the repository, next to what they describe.

The agent estimated this would take the index from 154 entries to about 70, around 8 KB. Step 1 only touched the developer's local memory and could be undone, so it could happen at once. Steps 2 and 3 changed the repository and would go through review.

The developer's reply was one character: "1".

Step 1: the archive

Seven minutes later, step 1 was finished.

• 17 notes archived: change requests, finished features, a release cutover, and a migration's design notes.
• 4 ticket notes kept, because each still held something live: a call never to make, even while probing; a question about a time offset that was still unanswered; what one unhelpful error code really means; and API shapes still in use.
• Facts lifted out before archiving: the release path, meaning which branches are stale and which pipeline actually ships, went into a kept note, along with a ruling the developer had made on one ticket.
• One stale note fixed: it said a feature flag was off in production, but the flag file showed it had been on for nine days. Several of the archived notes were stale in the same way. A ticket note records the code on the day it was written, and then the code moves on. That is one more reason not to load those notes into every session.

The agent also wrote the process down as a memory note, so it would follow it without being reminded:

• When a ticket's pull request merges, lift any live fact out of its note, then move the note and its index line to the archive.
• Sweep for merged tickets whenever the index passes about 15 KB.
• Before starting work on a ticket, search the archive index for its number or topic.

Step 1 took the index from 154 entries to 138, counting the new rule, and from 17.2 KB to 15.5 KB. That is only 1.7 KB. The rule slows new growth from tickets, but it doesn't touch the backlog, which was the other 40 or so notes that were never personal in the first place.

The developer's next message was "go, do 2 and 3". Part 14 covers that hour.

What to copy

• Treat a memory size warning as a design question. If three trims in a row keep every entry, the index needs fewer entries, not shorter ones.
• Sort the index by kind before cutting. About a fifth of ours was ticket records, and about a quarter was how-tos and facts that belonged in the repository.
• Keep recall cues in the loaded index. Don't hide notes behind hub files.
• Archive finished tickets, but lift live rules and open questions out first. Search the archive before starting related work.
• Expect ticket notes to go stale. They describe the code as it was on the day they were written.