Memory beats docs only when it's small and loaded by the work
Every session pays for an always-loaded index, and half of mine was boilerplate.
SymptomYour agent's always-loaded memory or rules file grows week over week, and pruning it never sticks.
My agents share one memory folder across every session and login. Its index loads into every session against a hard cutoff that the Claude Code memory documentation puts at 200 lines or 25 KB, whichever comes first, and lines past the cutoff silently stop loading.
Before the shared folder, memory split by where a session started, and about 40% of memories loaded in only about one session in fifty. One folder fixed recall and created a budget problem.
Pruning didn't help, because each fact was individually durable. Measuring showed that 7.5 KB of the 15.2 KB of rule lines was link boilerplate.
Grouping rules into themed hubs removed most of that. Then the per-rule cues on each hub's index line grew the index from 20.2 KB to 23.2 KB in a week.
Going pointer-only took the index from 22.4 KB to 7.8 KB. A hook loads a hub's cue list only when a tool call or prompt matches its triggers. A week's backtest put the median at one hub per session.
Rules with no tool or prompt signature never trigger the hook. For those, the pointer line's 'when to open' text carries the whole load.
Measure the bytes and the line count of your always-loaded memory index file. Find its load limit in your agent tool's documentation. Claude Code loads the first 200 lines or 25 KB of MEMORY.md. If no documented limit exists, report the size with the limit as unknown. Count the bytes that are links, titles and prefixes, versus the words that trigger recall. Structure at 40% of the bytes or more is a gap. A file above 90% of its limit is a gap.
Passes ifLinks, titles and prefixes are under 40% of the index file's bytes. The file is at or below 90% of its documented load limit.
Access needed:local-config
- 01Keep the always-loaded index to 1 pointer line per file, 250 bytes or less, saying when to open it.
- 02Group rules into themed hubs. Put each rule's cue on the hub's own contents list, not in the index.
- 03Load a hub's contents list by hook, once per session, when a tool call or prompt matches its triggers.
- 04Gate memory writes. Refuse cue lists in the index and new standalone rule files. Refuse any memory with near-duplicate similarity to a live memory.
- 05Keep session state out of memory entirely.