Why your coding agent re-reads the repo every session
Coding agents re-read the repo because every session starts with an empty context window. The agent greps and opens files until it has a picture, then loses it when the session ends. Along the way it misses conventions and copies stale patterns. Ensemble keeps a codebase graph and product knowledge, re-indexed on every protected-branch change, that agents query over MCP.
Why every session starts from zero
An agent's knowledge of your repo lives in its context window, and the context window is empty at the start of every session.
Watch the first minute of a Claude Code or Cursor agent session on a real task. Before it writes anything, it explores: lists directories, searches for a function name, opens a handful of files, follows an import, searches again. It's building a mental model of the part of the codebase the task touches.
That exploration is reasonable. It's also:
- Repeated. Tomorrow's session starts from zero and does it again. So does your teammate's.
- Expensive. Every file read costs tokens and time, and on a large repo the agent can spend a real share of its context window just orienting.
- Uneven. What the agent learns depends on what it happened to search for. Search for
sessionand you find one helper; search forauthand you find another.
The result is an agent that's smart about code and new to your codebase, every time.
What the crawl gets wrong
File search can find a symbol, but it can't tell which of three implementations is the one that matters.
Four failure modes come up again and again:
- Missed conventions. The codebase already has a
requireSession()helper. The agent didn't search for that name, so it writes its own session check. Now there are two. - Stale patterns copied. The grep matched a deprecated module first. The agent copies its pattern into new code, and the deprecated pattern spreads.
- No blast radius. The agent changes a function's signature without seeing its 14 callers, three of which have no tests.
- No product meaning. The repo has three billing paths. The agent can't tell which one customers actually use, so it edits the one that looked most complete.
None of these are model failures. They're information failures. The agent made reasonable decisions with the information a crawl gave it.
Doesn't CLAUDE.md or AGENTS.md solve this?
A rules file helps with conventions, but it's written by hand, goes stale, and can't describe a whole codebase.
Keep one. A short CLAUDE.md or AGENTS.md is the right place for preferences: "use pnpm," "prefer server components," "never edit generated files." It's the wrong place for facts about the codebase, for three reasons:
- Size. A codebase's structure doesn't fit in a file the agent reads every session, and trying makes every session slower.
- Staleness. Someone has to update it when the code changes. Nobody does.
- Structure. "Who calls this function?" isn't a question a markdown file can answer.
Use the rules file for preferences and an index for facts.
What persistent codebase context looks like
Persistent context is an index of the code, built once and kept current, that the agent can query alongside its own search.
Ensemble builds that index from your repositories. It covers:
- Structure: symbols, references, calls, routes and database tables.
- Module briefs: each module's purpose, entry points, invariants and pitfalls.
- Recipes: how a new service, handler or job should look in this codebase.
- Product knowledge: features, and the code that implements each one.
- History: how comparable tickets were solved.
Agents reach it through Ensemble's MCP server. The tools are shaped around the questions an agent actually has:
| Tool | The question it answers |
|---|---|
orient |
What is this codebase, and what matters for my task? |
explain |
What is this symbol, who calls it, what must stay true? |
check_diff |
What does this change break? |
how_to_add |
Where does a new handler, service or job go, and what must it look like? |
feature |
What is this feature, and which code implements it? |
Instead of starting every task with a round of searches and file reads, the agent can ask one question, get an answer shaped for the task, and then read the files that matter. MCP servers for codebase context lists every tool.
How the context stays current
Ensemble re-indexes when a protected branch changes, so answers describe what's merged, not every keystroke.
Two details make the answers trustworthy:
- Every answer names its commit. Results carry a
commitSha, so the agent (and you) know exactly which version of the code the answer describes. - Every answer says how sure it is. A
preciseresult comes from a compiler-grade index and is a resolved reference. Aheuristicresult is a name match, which might be an unrelated function that happens to share a name. Agents should treat heuristic results as leads to verify.
Your uncommitted local changes aren't in the index. To ask about them, pass the diff to check_diff, which reports the blast radius of the change against the indexed code.
What changes in practice
With persistent context, a typical session looks different:
- The agent calls
orientwith the task and gets the relevant modules, conventions and pitfalls in one answer. - Before editing an unfamiliar function, it calls
explainand learns who calls it and what must stay true. - For new code, it calls
how_to_addand follows the recipe the codebase already uses. - Before committing, it runs
check_diffand fixes the untested callers it finds.
The aim is less time re-exploring, code that follows existing patterns, and fewer surprises in review. Search still has its place. The index adds what a search can't easily reach, like calls between services and repos, and what each feature is for.
Seeing the change run
Context helps the agent write the change. Then someone has to see it run. Ensemble gives every branch its own running copy of the app at a private link, so agents working on several branches don't take turns on one localhost, you can click the change before you read the diff, and the PM who asked for it can open the link instead of asking you to pull the branch. See what is a preview environment.
FAQ
Why does Claude Code re-read my codebase every session?
Claude Code, like other coding agents, starts each session with an empty context window. It rebuilds its understanding by searching and reading files. Persistent context, such as an MCP server backed by a codebase index, lets it ask as well as search.
Is a codebase index the same as RAG over my repo?
Not quite. Plain RAG returns text chunks that look similar to the question. A codebase graph returns structure: who calls what, which routes hit which tables, what a change affects. Ensemble combines both with generated product knowledge.
Do I have to switch editors?
No. The Ensemble MCP server works with Claude Code, Cursor and other MCP clients.
Does Ensemble replace my coding agent?
No. Ensemble is context your agent calls. Your agent still writes the code.
Does Ensemble see my uncommitted changes?
No. The index describes committed code on your branches. To check local edits, pass a diff to the check_diff tool.
Ensemble turns every change into a running copy of your real app, with its services and data, at a private link anyone on the team can open. What is Ensemble?