My coding agents forget the repo. I built them a map

My coding agents do not remember the repository between sessions, so I give them a fixed read path. Four layers of plain text show what is current, which decisions are settled, and where the relevant code lives. The agent uses less of its context window rediscovering the codebase, but keeping the map accurate remains the hard part.

What is a context management system? A fixed read path

For a billing change, my context management system sends the agent to an index that names two documents and one folder. That fixed read path replaces an open-ended search through the repository, so the agent starts with the files most likely to matter.

Claude Code’s documentation explains why a repeatable starting point matters: “Each Claude Code session begins with a fresh context window” [1]. The agent starts without knowledge of the repository and cannot carry what it learned into the next session. Any continuity has to come from information it can find again.

The map does not try to store everything the agent might need. An automatically loaded instruction file points to current state, past decisions, and relevant code locations, while the agent loads the details only when the task requires them. The first selection matters because it becomes the basis for every decision the agent makes afterwards.

What does a blank session cost? Tokens and accuracy

A blank session costs both quality and tokens because the agent has to learn enough about the system before it can change it. If that learning depends on keyword matches, important details are easy to miss and the resulting change can look reasonable while still being wrong. The search itself also consumes context before the requested work begins.

Loading more files does not solve the problem by itself, because a model does not maintain the same level of attention throughout a long context window. Chroma Research tested 18 models and found that performance declined as the input grew, even on tasks that the same models handled well with a short prompt [2].

Long contexts fail in several ways, not just by running out of space. Drew Breunig describes how earlier mistakes can affect later reasoning, previous actions can distract the model, and different parts of the input can conflict. He also cites a Databricks study in which Llama 3.1 405B started losing correctness at about 32,000 tokens; agents became less effective beyond 100,000 tokens even on models with million-token windows [3].

Anthropic’s engineering team frames the same constraint as an attention budget [4]. In practice, every token spent understanding the repository leaves less attention for the requested change.

The numbers from my main repository make that trade-off unavoidable. Its 418 markdown files contain about 7 MB of text, and reading them all would require between 5.7 and 8.75 times a 200,000-token context window, depending on the estimation method. The agent has to read a subset, so I use a documented read order rather than letting the first keyword matches choose it.

Four plain-text layers keep current facts above history

The system routes every session through rules, current state, decisions, and optional history. Ordinary repository files make all four layers easy to inspect, review, and update, which matters more to me than sophisticated retrieval.

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

every session

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

points to

the map

• STATE.md current state, 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 rules file comes first because agents load it automatically. The Agentic AI Foundation describes AGENTS.md as an open standard used by more than 60,000 open-source projects [5], while Claude Code reads CLAUDE.md instead. Claude Code’s documentation recommends the bridge I use: make CLAUDE.md a symbolic link to AGENTS.md and keep the shared file under 200 lines [1].

I initially maintained a separate file for each tool, but their rules gradually diverged. The symbolic link removed that source of drift by giving both tools the same file and leaving me with one copy to update.

From the rules file, every session moves to the snapshot. It lists what is live, what is still in progress, and, most usefully, what has not been verified. That last category prevents the agent from treating unfinished work or an unchecked assumption as fact.

Behind the snapshot sit the decisions and the history. The ADR project defines an architectural decision record as a document about one important architectural decision [6]; in my system, each record explains both the decision and its reason. My repository accumulated 74 records in eight weeks, and when a decision changes, a new record supersedes the old one instead of rewriting it. Session logs are different: they form an append-only history that the agent can consult, but never as a source of current truth.

One authority order resolves conflicting answers

Those layers only work if the agent knows how to resolve conflicts between them. Every repository entry point therefore states the same authority order: code overrides decision records, decision records override the snapshot, and the snapshot overrides history. When a search finds five answers written at different times, the agent can follow the highest-ranking source and update or flag the rest.

The decision to keep history out of the normal read path has a large practical effect. Session logs account for 73% of all documentation bytes in this repository, so excluding them reduces the read-everything estimate from 8.75 context windows to about 2.3. The current documentation is still substantial, but it becomes much easier for the agent to navigate.

How do I keep context files current? Update docs with code

I treat documentation as part of the code change. Whenever code alters an architectural fact, the same commit must update the relevant document rather than leave it for a later cleanup. The instruction file states this rule up front and repeats it in the agent’s final self-check, when the update is hardest to overlook.

In my repository, agents followed that check more consistently than people did. After I extended the rule to user-facing documentation, the share of UI commits that updated the matching docs rose from 12.3% to 31.9%. A 31.9% rate is hardly compliance, but it is 2.6 times the previous result, and most misses came from changes that no single agent owned from start to finish.

I use a second rule for the information that changes between sessions: before stopping, the agent writes a short session log and refreshes the snapshot. Moving to another task triggers the same routine. Without that explicit moment, updates that seem easy to do later are just as easy to forget.

Why I stopped using embeddings and memory MCP servers

I stopped using both because retrieval was not the problem. The systems found relevant information but could not reliably tell whether it was current. My memory MCP server and vector index often returned the right topic from the wrong month because embeddings created before a refactor do not know that the architecture changed.

Each setup also created another source of information that I had to maintain, bringing back the problem I was trying to solve. Several open-source memory frameworks added a second concern: their code often did not enforce the behavior described in the README. Once I had to verify both freshness and implementation, I stopped evaluating them. Hosted agents raise the same question of what persists between sessions, which I cover in what OpenAI’s Agents API keeps and what the Codex harness takes over.

Anthropic recommends keeping lightweight identifiers, such as file paths and queries, in context, then loading details only when the agent needs them [4]. Plain files suit that approach because they can be searched, diffed, and reviewed in the same pull request as the code they describe. A reviewer can notice an old markdown file; an outdated embedding index is much harder to inspect.

What did the system cost? Less reading, more maintenance

The system kept the automatic starting load at 0.22% of my repository’s documentation, but it did not keep that documentation accurate. A July 2026 audit found that the snapshot had grown 9.5 times in 26 days and contained a stale warning.

The repository is a production monorepo with about 277,000 lines of TypeScript used by three different agent tools. The structure did its job by giving each tool a short entry point and a consistent read order. The information inside that structure was much less reliable. How two of today’s coding agents handle large features is a separate comparison: Claude versus Codex on large multi-agent features.

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 first two numbers show the benefit of the read order: the agent starts with 0.22% of the documentation and loads more only when the task requires it. The third number exposes the system’s persistent weakness. STATE.md was supposed to stay small and be rewritten in place, yet it grew 9.5 times in less than a month and, during the audit, its main warning was wrong. It claimed several commits still needed to be pushed even though the push had happened days earlier.

That stale warning was not an isolated miss. The schema documentation said the system had 20 to 25 tables while the code had 34, and the audit removed documentation for features that had never existed. It also checked 2,873 relative links across the docs and found 82 broken ones.

The most consistent pattern was the difference between written instructions and automated checks. A test enforces my typography rule in UI strings, where the audit found no violations, while about half of the plain documentation files broke the same rule because nothing checked them. In practice, the symbolic link and the type checker were the only parts with deterministic enforcement. The decision record that introduced the system had stated the limit clearly: “This reduces the failure rate, it does not eliminate it.”

I still have not found the right amount of information to load. If the starting files contain too little, the agent has to guess; if they contain too much, I recreate the long-context problem that Chroma Research measured [2]. The balance changes with the repository, so I adjust it every few weeks rather than treating the structure as finished.

At work, I keep the read path and lose the ceremony

At work, I keep the same read-path idea but present it as ordinary project documentation. The full system belongs in my personal projects because, in my experience, many teams read this much agent-specific structure as vibe coding rather than documentation for developers.

In practice, the work version looks like standard project documentation: a clear entry point, stable documents for each area, and an index that explains where to find things. New colleagues benefit from those markdown files, and coding agents can follow them too.

The two versions differ for more than appearances. At work, teams make decisions in meetings and on planning boards, so the repository cannot be the complete source of decision history when much of that history lives elsewhere. My personal projects have no equivalent outside record; if I do not write a decision in the repository, the next session has no way to find it.

How to start: one rules file under 200 lines

I would start with one rules file under 200 lines that states the repository conventions and the order in which the agent should read other files. Claude Code’s documentation suggests adding a rule when the agent repeats a mistake [1], which is also the maintenance trigger I use. A repeated error means the read path did not explain something clearly enough.

The rest can arrive when the need appears. Add one state file and point to it from the rules, then create an index when the documentation no longer fits on one screen. Write the first decision record when an agent questions something you already settled, and add a history folder when you need a record of past work without presenting it as current truth. A clear read path also changed how well a model works for me, which I describe in my Opus 5 workflow of clear plans and smaller tasks.

From there, maintain the files with the same care as code. My previous article argued for backends small enough for an agent to understand; this system applies the same principle to the information that code cannot explain by itself. The agent will still begin every session without memory, but a maintained read path lets it find the right context without reading the whole repository.