Coding agents start every session blank. Mine get a map

A context management system is a set of plain text files, checked into the repo, that hands a fresh AI agent a map: what to read first, where current truth lives, which decisions are settled. Mine went through several rebuilds. This is the version that survived, with its measured costs included.

What is a context management system?

A set of files that tells the agent where to look instead of making it search: one instruction file every session auto-loads, pointing to the few documents that say what is true right now, what was decided and why, and where the code for each area lives.

The starting condition it exists for is stated plainly in Claude Code’s own documentation: “Each Claude Code session begins with a fresh context window” [1]. Every session is a new hire with amnesia. A capable one, but one that has never seen your repo before and will never remember having seen it.

The comparison I keep coming back to is Google Maps. When I ask for a billing change in a mapped repo, the agent’s first read routes it: the rules file points to an index, the index has a row for billing, the row names two documents and a folder. It goes there. Without the map it greps, opens whatever matched, and assembles its picture of the system from the five files it happened to see first.

That picture is the product. Everything the agent does afterwards inherits from it.

What does a blank session actually cost?

Two things: quality and tokens. An agent that orients from keyword luck understands the system too shallowly and ships plausible-but-wrong changes. And the orientation itself burns through the context window before the real work starts, which turns out to be the more expensive half.

Context is not a flat resource you can spend freely. Chroma Research evaluated 18 models and found that performance degrades as input length grows, even on tasks a short prompt handles cleanly [2]. Drew Breunig catalogued how it fails: contexts poison themselves with earlier mistakes, distract the model into repeating past actions, or clash internally; he cites a Databricks study where correctness starts falling around 32,000 tokens for Llama 3.1 405B, and agents degrading beyond 100,000 tokens on models with million-token windows [3]. Anthropic’s engineering team calls the budget what it is, attention: every token spent orienting is attention the model no longer has for the change you asked for [4].

My main repo makes the arithmetic concrete. Its documentation corpus is 418 markdown files, about 7 MB of text. Reading all of it would cost between 5.7 and 8.75 times a 200,000-token context window, depending on the estimation method. It does not fit, and no model roadmap makes it fit gracefully. So the question was never whether the agent reads a subset. It is who picks the subset: the agent, by grep luck, or me, by design.

Four layers and one sentence

The system I landed on is four layers of plain text. Nothing about it is clever, and after watching the cleverer versions fail (more on those below), I consider that the feature.

AGENTS.md            # the rules; auto-loaded (CLAUDE.md is a symlink to it)
docs/
  STATE.md           # current truth: live, in flight, not yet verified
  INDEX.md           # the router: which docs to read for which task
  decisions/         # one numbered file per decision; superseded, never edited
  sessions/          # history: what happened when, explicitly not authority

The rules file is the entry point because it is the one file agents load on their own. AGENTS.md is an open standard used by more than 60,000 open-source projects [5]; Claude Code reads CLAUDE.md instead, and its docs recommend the exact bridge I use, a symlink, along with a size target of under 200 lines [1]. Mine spent its first weeks as two separate files maintained from two different tools, and the rules quietly diverged until the symlink ended the problem by construction. One file, every agent, drift impossible.

The snapshot is what the rules file orders every session to read first: what is live, what is mid-flight, and, most valuable in practice, what is explicitly not verified. An agent that knows a thing is unverified stops trusting it. Decision records are the ADR pattern, one file capturing a single decision and its rationale [6]; my repo accumulated 74 of them in eight weeks, and a new decision supersedes the old file instead of editing it, so the trail stays honest. History is the append-only pile of session logs, allowed to be enormous precisely because nothing is allowed to rely on it.

One sentence holds the layers together, restated at every entry point of the repo: code beats decision records, decision records beat the snapshot, the snapshot beats history. That ordering is the actual system. A keyword search across a repo this size returns five hits from five eras; the sentence tells the agent which one wins and that the losers get fixed or flagged, not silently believed.

every session

• AGENTS.md rules and read order, auto-loaded

points to

the map

• STATE.md current truth, read first
• INDEX.md which docs for this task

routes to

the task

• Area docs and code only what the change touches
• decisions/ why it is the way it is
• sessions/ history, never authority

The exiled history layer earns the diagram’s smallest box with one number: session logs are 73% of all documentation bytes in that repo. Strip them from the read-everything scenario and the remaining corpus drops from 8.75 context windows to about 2.3. Declaring history non-authoritative is not tidiness. It is what makes the rest navigable at all.

What keeps the map from lying?

One rule, mostly: docs are part of the change. A change that alters an architectural fact updates the affected document in the same commit, not in a cleanup that never comes. The agent’s instruction file says so, and repeats it in a self-check at the exact moment an agent decides it is done, because that is when instructions reliably have its attention.

It works better with machines than it ever worked with humans, for an unflattering reason: an agent actually runs the prescribed check. When I widened the rule to cover user-facing documentation too, the share of UI-touching commits that updated the matching docs in the same commit went from 12.3% to 31.9%. Not compliance, but 2.6 times more of it, and the misses cluster where no single agent owned the change end to end.

The second habit is cheaper: the agent writes a short session log and refreshes the snapshot before it stops, on its own initiative, treating “the user moved on to something else” as a done signal. Documentation that waits for someone to feel like documenting does not survive contact with a Tuesday.

Why not embeddings or a memory MCP server?

Because I tried those first, and they kept failing the same way: retrieval was never the hard part, freshness was. A memory MCP server with a vector index in front of my repos kept returning the right topic from the wrong month, and an embedding of March’s architecture has no way to know that Tuesday’s refactor invalidated it. Each of those setups was also a second system whose truthfulness I now had to maintain, which is precisely the failure the map exists to prevent. And with several of the open-source memory frameworks I evaluated, the distance between what the README promised and what the code enforced was wide enough that I stopped evaluating.

Anthropic’s context-engineering guidance landed where I did: keep lightweight identifiers in context, file paths and queries, and let the agent load detail just in time instead of pre-computing everything it might need [4]. Plain files have the property that matters most for that strategy: they age in the open. They are greppable, diffable, and reviewed in the same pull request as the code they describe. A stale markdown file is at least visibly stale. A stale embedding index misleads with full confidence.

The honest costs, measured

In July 2026 I ran a read-only audit of the whole apparatus in my main repo, a production monorepo of roughly 277,000 lines of TypeScript worked by three different agent tools. The short version: the structure holds, the prose discipline does not.

of the docs auto-loaded

0.22%

a 15.5 KB rules file against a 7 MB corpus

a 200K window to read everything

8.75×

5.7× on the words-based estimate

snapshot growth in 26 days

9.5×

75 lines to 711, and it never shrank

The gap between the first two numbers is the whole design: the agent starts from 0.22% and navigates outward. The third number is the design’s standing failure. The snapshot was chartered as a small file overwritten in place, and instead it grew 9.5 times in under a month. Worse, at audit time its headline claim was false: it warned that a pile of commits was waiting to be pushed when the push had happened days earlier. The file every session reads first stated a stale fact with full confidence.

That was not the only lie the audit surfaced. The first time I synced documentation against code, the schema doc claimed 20 to 25 tables where the code had 34, and the sweep deleted documentation for features that had never existed at all. Of 2,873 relative links across the docs, 82 were broken. And my pet typography rule holds at exactly zero violations in the UI strings, where a test enforces it, while roughly half of the plain doc files break it, where nothing does. The pattern is clean: a prose rule rots in proportion to its distance from a test. The only deterministic parts of the entire system are a nine-byte symlink and the type checker. The decision record that adopted the structure said it up front: “This reduces the failure rate, it does not eliminate it.”

The problem I have not solved is dosage. Too little in the map and the agent guesses; too much and I have rebuilt the long-context degradation from that Chroma curve out of my own files [2]. I re-tune the balance every few weeks, and I expect I always will.

The light version I run at work

Everything above is my personal-project setup, and I would not bring it to an employer unchanged. In professional settings, in my experience, this much agent apparatus reads as vibe coding, and teams that want AI as a productivity tool rather than an autonomous author have limited appetite for a repo that looks built for the machine. Fair or not, the perception is part of the engineering.

So at work I run the same idea disguised as what it also genuinely is: documentation done properly. A clear entry point, area docs with stable names, an index that says what lives where. Markdown files a new colleague would thank you for, which happen to double as an agent map.

The split has a structural cause, not just an optical one. At work, decisions are made outside the repo, in meetings and on the board, so a repo layer claiming decision authority would lie by omission from day one. On personal projects there is no outside: if a decision is not written into the repo, it stops existing the moment the session ends. The hardcore version is not extra discipline for its own sake. It is what a repo needs when it is the only place anything can live.

Where I’d start

One rules file under 200 lines that states the conventions and the read order; Claude Code’s docs suggest adding to it whenever the agent makes the same mistake twice [1], which is also the best maintenance trigger I know. One state file it points to. An index the week the docs stop fitting on one screen. Decision records the first time the agent re-litigates something you settled a month ago, and a history folder the day you want a record without wanting to trust it.

Then treat the map like code. When the agent errs the same way twice, the bug is usually in the map, and the fix is one sentence in the right file. The last piece I wrote argued for backends small enough for an agent to hold in its head. This is the same argument, aimed at everything the code cannot say about itself. The agent will never stop starting blank. The map is what stops that from being expensive.