# 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.

By Ki Moon · 2026-10-14 · technique · current
Canonical: https://kihmoon.com/bench-notes/p/memory-beats-docs/

**Symptom:** Your 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.

## Check your setup (read-only)

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 if:** Links, 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

## If it fails (changes to make later, not part of the check)

1. Keep the always-loaded index to 1 pointer line per file, 250 bytes or less, saying when to open it.
2. Group rules into themed hubs. Put each rule's cue on the hub's own contents list, not in the index.
3. Load a hub's contents list by hook, once per session, when a tool call or prompt matches its triggers.
4. Gate memory writes. Refuse cue lists in the index and new standalone rule files. Refuse any memory with near-duplicate similarity to a live memory.
5. Keep session state out of memory entirely.

**Applies if:** Your agents load a memory or rules file into every session and it is nearing its load limit.

**Skip if:** Your always-loaded memory or rules file is under half its documented load limit, or no such file exists.

Tags: memory, cost, agents
