Is AGENTS.md enough, or does my codebase context need somewhere else to live?

You re-explain because nothing you wrote down is being retrieved when the agent needs it. Every session starts from an empty window, and the two standard fixes fail in opposite directions: a context file is loaded whole and crowds out the working space, while the agent’s own search is keyword-shaped and never surfaces what you wrote. What ends the re-explaining is recording the facts your code cannot show, somewhere an agent queries on demand instead of swallowing up front.

Why this happens

The agent is not forgetting. Most of what you re-explain was never written down anywhere, and the rest was written somewhere the agent has no reason to look.

Two different problems get filed under “it forgot again.” The first is genuine session boundaries: weights are frozen, inference is stateless, and every conversation rebuilds its input from nothing. No prompting technique changes that. The second is the part that actually costs you time. Why the retry backoff is 400 milliseconds. Which of two service boundaries was tried in 2024 and abandoned. An agent reading your repository can infer structure, but it cannot recover intent that only ever existed in a thread from last March. That gap is the subject of why AI coding assistants can’t see your codebase: 84 percent of developers use AI coding tools, only 29 percent trust the output, and “almost right, but not quite” is the most-cited frustration at 66 percent.

The reflex is to write more of it into the context file, and that reflex is the one move here that has been tested against a control. The guides answering this question tell you to write the file and report an improvement for it. An ETH Zurich group ran four coding agents over SWE-bench tasks and a fresh set of issues from repositories that ship such files, and found that providing one did not generally improve task success rates, while increasing inference cost by over 20 percent on average. Repository overviews, the section those guides tell you to write first, were singled out as ineffective.

That does not make the file useless. It makes it not free, and the section everyone writes first is the one that pays least. A separate study of 466 open source projects found half of these files are never touched after the first commit, one of the findings in what 466 AGENTS.md files teach about context engineering. A static file is paid for on every turn regardless of relevance, and it is written once, at the point of least knowledge, then drifts with nothing signaling it has. That is also where the token-limit complaint comes from, and agents misjudge that budget because they cannot see their own window state, as covered in context window blindness.

Why do coding agents default to keyword search instead of semantic retrieval?

Because keyword search is always fresh and an embedding index is always slightly stale, and for source code that trade is usually worth making. Claude Code, Codex CLI, Cursor, and Aider all reach for grep or ripgrep first. An index built at one commit is wrong at the next, and an agent very often searches for text it wrote itself thirty seconds ago, which a rebuilt-nightly index handles worst.

The benchmark evidence backs the choice for code specifically. CoREB, released in May 2026, evaluated eleven embedding models and five rerankers across text-to-code, code-to-text, and code-to-code retrieval. Short keyword queries, the format closest to how developers and agents actually search, collapsed every model tested to near-zero nDCG@10. Vendors arrived at the same conclusion from the other direction: Cursor answered slow ripgrep in large monorepos by building a faster text index rather than by switching to vectors.

That is fine for finding code and useless for finding decisions. A decision has no distinctive token to match. “We moved off the shared cache after the thundering herd incident” contains not one identifier an agent would grep for, and no codebase index returns it either, because the index is over source and the answer is not in the source. This is the narrow slice where semantic search earns its cost, and noticing that it is narrow is what keeps the fix cheap.

Your options

AGENTS.md or CLAUDE.md is the right home for rules that are short, stable, and apply to every task: build commands, the lint policy, which directories are generated. Kept that way it costs almost nothing, and the result above is not an argument for deleting it. The failure is growth, and it is silent in both directions: nothing tells you the file got too long, and nothing tells you it went stale.

Your agent’s built-in memory is genuinely good at personal working style and bad at everything else, because it does not leave the tool. Context you build in one assistant is invisible to the next one and to your teammates, so the re-explaining does not stop, it forks. That bites hardest for anyone running more than one agent.

Architecture decision records are the only option here that directly targets the expensive category: rejected alternatives and constraints that outlived their stated reason. They are worth writing. The weakness is retrieval rather than capture, since nothing makes an agent read the three ADRs relevant to the file it is editing, and the habit is the first thing to go under deadline.

An indexed search over the repo earns its place once the codebase is large enough that grep gets slow. Sourcegraph, Cursor’s index, and Augment’s Context Engine all do this well. The limit is structural: an index over source cannot return something that is not in the source, so it shortens the search without shortening the explanation.

A shared store your agents read and write targets the retrieval half rather than the capture half. Decisions live outside any one tool, and the agent pulls the relevant few at the moment of use instead of loading everything up front. It only works if writing to it is a habit, it adds a network call a local file does not, and it does nothing about knowledge nobody ever states out loud.

How to decide

Is what you keep re-explaining in the code, or about the code? If it is in the code, you have a search problem, and a faster index or better grep patterns will fix it more cheaply than anything here. If it is about the code, no amount of indexing helps and you need a place to put it.

How many agents and how many people? One person on one tool should stop at a short context file plus the tool’s own memory. The moment a second agent or a second teammate needs the same answers, per-tool memory starts generating the work rather than saving it.

What updates it, and when? Every option except capture-as-byproduct depends on someone remembering to go back and edit. If you cannot name what triggers the update, choose the option that does not need one, and keep the file short enough that staleness is survivable.

What to do next

Start by cutting your AGENTS.md rather than extending it. Keep only the rules that apply to every task and that an agent cannot infer from the repository, usually under thirty lines. That one change reclaims window space, removes most of what goes stale, and costs nothing.

Then pick one place for the decisions. If you already run most work through a coding agent, have it record them as they are made, so capture is a byproduct rather than a chore. If you do not, write three ADRs for your most-argued-about subsystems. The test either way: a week later, does an agent get the answer without you typing it again. If it does not, the reasons are usually the three failure modes in why AI agent memory keeps failing.

Wire is our version of the shared-store row, and it is worth a look only if the questions above landed you there. It gives coding agents one permissioned place to read and write through wire-memory, so a decision is recorded once and answered to whichever agent asks next; the property doing the work is context portability, the store outliving the tool you happen to be using. If the re-explaining is confined to one repository, one person and one assistant, a thirty-line file plus your agent’s own memory is cheaper.

Sources: Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? · Beyond Retrieval: A Multitask Benchmark and Model for Code Search · 2025 Stack Overflow Developer Survey · Why Coding Agents Still Use grep as Their Search Backbone