Giving Coding Agents a Map

In many of the projects I work on, the slow part is not writing the change. It is finding the right place to make it.

A coding agent can search a repository quickly, but it still starts each new session without a durable picture of the project. It has to rediscover where the important code lives, which files are authoritative, and what else might be affected by a change.

Codex and I have been using a local tool called RepoMemory to reduce that rediscovery. It is a local helper that points an agent to likely files and supplies a small amount of relevant repository context. It gives the agent a map before the work begins.

What RepoMemory is

RepoMemory is a local repository context layer I built for coding agents. I give it access to approved repositories, and it keeps a searchable view of the files, their purpose, and whether its information is still current.

When Codex begins a non-trivial task, it can ask RepoMemory where to start. The response is a focused set of likely files with enough context to explain why they may matter. Codex then opens those files and continues with ordinary source inspection, tests, and runtime checks.

RepoMemory is not a code generator, a chat interface, or a replacement for Git. It is the context layer between a coding task and the repository itself.

The rediscovery tax

Most repositories develop their own shape over time. Application code sits beside tests, configuration, scripts, deployment files, documentation, and old paths that still look important. The file with the obvious name is not always the source of truth.

That creates a repeated orientation cost. An agent searches for a term, opens a few promising files, follows imports, checks nearby tests, and slowly builds a working picture of the project. That exploration is necessary the first time. I do not want to repeat all of it for every task.

The problem becomes more noticeable when I return to a project after a few weeks, move between several repositories, or hand a narrow task to another agent. The code is still there, but the useful context from the previous work is gone.

What I wanted

I did not want a tool that claimed to know the answer. I wanted one that could help an agent begin in the right neighborhood.

When I ask where note publication is controlled, for example, the useful response is not a long explanation of the entire website. It is a short list of the files most likely to own publication rules, the nearby code that may be affected, and enough context to explain why those files are worth opening.

The working pattern is simple:

describe the task
      |
      v
find likely files
      |
      v
read the source
      |
      v
change and validate

RepoMemory helps with the second step. It does not remove the steps that follow.

A map, not an answer

The map comparison is important because it sets the right expectation.

A map can point to the road, but it cannot prove the road is open today. In the same way, repository memory can identify likely files and related context, but the current source still decides how the application behaves.

Our normal workflow starts with RepoMemory, then moves back to direct evidence. The agent opens the selected files, searches for the exact symbols, reads the relevant tests, and checks the running application when the task affects real behavior.

That boundary is deliberate. Stored context can become stale. A broad question can point toward a related file instead of the real owner. A summary can omit the one condition that matters. Treating memory as proof would only replace one kind of guess with another.

Where it helps

RepoMemory is most useful when I know what I want to change but do not yet know where the change belongs.

That includes returning to an older project, tracing behavior across several layers, locating the source of a configuration value, or finding the tests and runtime paths that belong to a feature. It also gives an agent a smaller and more relevant starting context than opening a large part of the repository at once.

This does not make ordinary search obsolete. If I know an exact function name, error message, or configuration key, a direct text search is usually the right tool. RepoMemory is more useful when the question is about intent: where a behavior is owned, which files belong to a change, or what should be checked before editing.

The two approaches work well together. One narrows the starting area. The other confirms the details.

What changed in practice

The biggest improvement for me has been continuity. A new task can often begin with a focused set of candidates instead of a wide scan of the repository. The agent verifies those files and moves into the actual work sooner.

The verification step also exposes a bad first result before the agent changes the wrong part of the codebase. That is much safer than asking an agent to trust a stored description of the codebase.

I have been using RepoMemory across my internal projects and experiments for a while now (a few months of development and dogfooding so far). Its dashboard estimates that it has kept about 8.6 million tokens of unnecessary context out of agent requests. That is an estimate, not a billing total. It depends on how often the agents use RepoMemory, but it still gives a sense of how much repeated repository reading we have avoided.

One unexpected lesson has been that lookup speed is only part of the picture. A raw search can be very fast, but the agent still has to read and sort what it returns. What matters in practice is whether the whole task begins with less unnecessary context.

RepoMemory is still evolving, and I will write more about how it works and what we have learned from using it in the days to come. When I start a new task in an existing project, RepoMemory gives the agent a useful starting point. From there, the agent reads the source, runs the tests, and checks the application itself.