Why Claude Code rereads the entire project and how to fix it

Ailoot documentation: API, keys, and connection.

Why does Claude Code reread the project from scratch every time?#

Many people think this is a bug. In fact, this is how Claude Code is designed: it has no project index of its own. When you ask it to fix something, it has no ready-made code map at hand—it explores the project again: finds relevant files, searches for the needed strings, and reads files into memory.

This approach has real advantages. The code is always fresh—there is no index that has fallen out of date. There is nothing to configure. Your code is not sent to any database.

But there is a downside: every new task means a new round of searching and reading files. Tokens are spent figuring out again where everything is, even though Claude already worked that out in the previous session. The larger the project, the more this reconnaissance costs. This mechanism is exactly why it can feel like the agent is “reading everything.”

How many tokens does this really burn?#

The cost begins before your request. One independent measurement shows it simply: Claude Code sends around 33,000 tokens of system prompt and tool descriptions before reading the first character of your message. For comparison, OpenCode starts at around 7,000.

Then rereading comes into play. Every file search and every read adds tokens to the context. The official Claude Code documentation says it directly: file reading dominates context usage. An analysis of auth.ts at 2,400 tokens means 2,400 tokens seen only by Claude, and the same applies to every file it opens during reconnaissance.

For our audience, this translates into money and limits. The number one fear among people who get into vibe coding is “I paid, and the limits ran out for nothing.” If the agent scans the project and rereads files from scratch for every task, the context burns up twice as fast: first on the system overhead, then on reconnaissance. I covered the full map of where exactly Claude Code tokens go in the guide “Where Claude Code tokens go”—project rereading is one of nine patterns there.

What is persistent code memory?#

Code memory addresses exactly the gap that makes Claude reread the project. The idea is simple: have something scan all the code once, build a map from it, and keep that map handy. Then the agent does not need to search from scratch every time—it asks the map.

Technically, it works like this. A separate tool scans the project and breaks it down into components: what functions and classes exist, who calls whom, and which files are connected. This structure is saved on disk. When Claude needs to understand where the payment logic is or what will break if a function is edited, it makes one targeted query to the map instead of reading dozens of files.

This map is connected through MCP—the standard way to attach an external tool to Claude Code (I covered connecting other servers in the guide “MCP servers for Claude Code”). The code memory tool adds its own map-search commands, and Claude uses them on its own when it needs to get its bearings in the project.

In practice, the difference is between “read the whole folder to find one function” and “ask the map where that function is.” The first costs tens of thousands of tokens; the second, hundreds.

Two approaches to code memory: how do they differ?#

Code memory tools differ in what they build from your project. The easiest way to think about them is: one gives you a surgeon’s hands for edits, and the other searches by meaning.

The GitHub star counts are as of July 15, 2026 (according to the GitHub API). Both tools are free and open source, both work with Claude Code, and both connect as MCP servers.

A short takeaway for non-programmers. Serena is a surgeon’s hands: use it when you edit the same piece throughout the project and precision matters. claude-context is meaning-based search: it finds code from a description, but that comes with cloud database setup and a key.

When should you choose Serena or claude-context?#

The two tools are not competing for a single prize. They remember different things, so the choice depends on the task.

Choose Serena if you do a lot of refactoring. It gives the agent code navigation like an intelligent development environment: it finds a function definition and all its actual call sites, then carefully renames the function or replaces its body throughout the project. The author describes the benefit this way.

Serena does not publish an exact savings percentage, and I will not attribute a made-up figure to it. The benefit is different: where a regular search returns forty matches along with comments and strings, after which Claude reads four entire files, Serena answers with a few precise queries. That means fewer calls and fewer false matches, and therefore a lower risk of the agent editing the wrong thing.

Choose claude-context if you need meaning-based search and are not put off by the setup. It turns code into vectors (numerical fingerprints of meaning) and searches by description: “find where our payment logic is,” even if you do not know the function names. The price of this search is the extra setup.

claude-context requires an external vector database, an embeddings provider key, and a recent version of Node. Of the two, it is the more involved to set up, so I recommend that beginners start with something else.

What can you do directly in Claude Code without third-party tools?#

Before installing third-party tools, get the most out of what Claude Code already includes. These commands are free and work out of the box.

1. /context—shows a live breakdown of what occupies the window: system prompt, CLAUDE.md, memory, tools, and files. The /mcp command shows the cost of each connected server, and /memory shows what loaded at startup.
2. /compact—compresses the conversation history into a short summary and continues the same task. You can guide the focus by adding what to preserve to /compact.
3. /clear—throws away the entire history. The official recommendation is to run it when switching to an unrelated task, so the old conversation does not crowd out the files you need.
4. /doctor (also known as /checkup, introduced July 8, 2026)—diagnoses the setup and suggests fixes: removes duplicates in CLAUDE.md, finds unused tools and servers, and catches slow handlers.

A separate note about CLAUDE.md. This file is loaded into context at the start of every session and is included in every message. If it is oversized, you keep paying for it. The official recommendation is to keep it under 200 lines and move reference details into skills that load on demand. I covered how to put together CLAUDE.md correctly in the separate guide “How to configure CLAUDE.md”.

One more built-in lever is subagents. They have their own separate context, so you can delegate heavy reading and reconnaissance to them without bloating your main window. Anthropic states the general principle this way in its engineering analysis.

Will an extra MCP server make the context even bigger?#

The logic that “one more server means more context overhead” used to be right, but Claude Code has changed this. MCP tool descriptions are now deferred by default: only server names are included in context at startup, and full descriptions are loaded when a specific tool is needed for the task. The documentation states this directly.

The math of code memory is simple. A small, fixed overhead for tool names versus thousands of tokens saved because the agent no longer rereads files. The balance clearly favors the index.

A couple of honest caveats, so you do not expect magic. The index needs to be rebuilt occasionally—the map reflects the code as it was at the time of scanning, and after major edits it needs updating (this varies by tool: some do it automatically, others require a command). And big claims like “120 times fewer tokens” describe the best case on selected queries, not what you will see on every task. The real savings are more modest, but still noticeable. If you want a deeper look at how to avoid hitting limits in general, I have a separate analysis, “How to avoid burning through Claude Code limits”.

Where should you start today?#

If you strip away everything unnecessary, today’s plan is simple:

1. Run /doctor and clean up what it suggests: duplicates in CLAUDE.md and unused tools.
2. Cut CLAUDE.md down to 200 lines, moving reference material into skills.

Then choose based on your needs: if you do a lot of refactoring, add Serena for precise edits; if you need meaning-based search, set up claude-context. Code memory and clean context solve the main pain point today.

If you need access to AI models through Ailoot, check out Ailoot.