The agent keeps re-reading the same files and burning context
Claude Code Last checked 2026-10-27
It is not confused — it has no memory of reading the file, so the only way to know what is in it is to look again. Each re-read eats context, which brings the next compaction closer, which erases the memory again. Put the one fact it needs (a signature, a shape, a path) in a file it is told to trust, and the loop stops.
What you saw
The agent opens src/api/users.ts (or any file), does something with it, then five tool calls later opens the exact same file again — sometimes multiple times in one turn.
A task that should take 10 tool calls takes 40, and most of the extra calls are Read on files already read this session.
Context usage climbs fast even though you have not asked for anything new; /context shows most of the budget going to file contents, not conversation.
The session compacts twice in quick succession — once, then again ten minutes later — and each time the re-reading starts over.
It happens most on tasks that touch the same handful of files repeatedly: a schema, a shared types file, a config, anything referenced from many places.
What it actually means
A model has no persistent memory between tool calls beyond what is still in its context window. If a file's contents scrolled out of context — because other tool calls pushed them out, or because a compaction summarised them away — the model does not "remember reading it"; it only remembers deciding something *based on* it. To act again, it has to re-fetch the source.
This is different from forgetting a plan after compaction (see that page): here the model usually still has the plan, it has lost the *content* the plan depends on. "Add a field to the User type" survives a summary; the literal current shape of User usually does not.
Re-reading is self-reinforcing. Every Read call adds the full file back into context, which is exactly the thing that pushed the window toward its limit and caused the memory loss in the first place. Large shared files — a 2,000-line types file, a big schema, a monolithic config — are the worst offenders because each re-read is expensive and the same file tends to be relevant to many steps.
Tool design makes it worse in some clients: if the agent cannot easily tell "have I already read this and does it still reflect disk" from the transcript, re-reading defensively is the only safe move. An agent that is unsure whether a file changed since it last looked will choose to look again rather than guess.
The fix
Extract the one or two facts the agent actually needs repeatedly — a type shape, a function signature, an env var name — into a short reference file, and point the agent at that instead of the large source file.
# .agent/types-reference.md
## User (src/models/user.ts)
interface User {
id: string; email: string; role: "admin" | "member";
createdAt: Date;
}
## Canonical import path
import { User } from "@/models/user";
Tell it explicitly that the reference file is authoritative and current, so it stops treating the real source as the only trustworthy copy.
Trust .agent/types-reference.md for type shapes unless I tell you
it is stale. Do not re-read src/models/user.ts to check it.
For a task that touches one file many times, load it once at the start and tell the agent to track changes itself rather than re-reading to check.
Read src/config/flags.ts once now. For the rest of this task,
assume it hasn't changed unless you (or I) just edited it — don't
re-read it to verify.
Split a task that keeps circling back to the same file into separate sessions or sub-agents, each scoped to one slice of work, so the expensive file is only loaded once per slice instead of once per step.
Session 1: add the field to the User type and the migration.
Session 2 (fresh): update every call site to pass the new field.
Session 3 (fresh): update the tests.
If the file is large and only a small part is relevant, ask for a narrower read instead of the whole file — grep for the symbol, or read a line range.
grep -n "interface User" src/models/user.ts
# or, if your client supports it:
Read src/models/user.ts lines 1-40 only.
Watch context proactively instead of reacting to the loop. In Claude Code, check /context before a file-heavy step and compact deliberately at a clean point rather than letting auto-compact fire mid-task.
/context
# at a clean stopping point, before the big file-heavy step:
/compact Keep: the reference file contents and the plan.
Drop: full source of files already summarised in the reference file.
How to stop it happening again
Keep a small, explicitly-trusted reference file for anything referenced from more than two or three places in a task — types, config shape, API contracts. Update it when the real thing changes; treat it as the source the agent reads.
Prefer grep/targeted reads over whole-file reads for large shared files, both for yourself and in the instructions you give the agent.
Scope sessions narrowly. A session that touches one file once is cheap; a session that touches the same file at every step pays for it on every step.
If a client exposes a context breakdown, check it before — not after — a file-heavy stretch of work, and compact or split before the window forces a summary on its own terms.
Related questions
Is this the same as forgetting the plan after compacting?
Related but not identical. Forgetting the plan is losing the decisions and constraints. Re-reading files is losing the *content* those decisions depend on. The fix for both is the same shape — put the thing that matters in a file the agent is told to trust — but what you extract differs: decisions and rules for one, data shapes and signatures for the other.
Why does it re-read a file it just read two tool calls ago?
Usually because something else — a large command output, another file, a long tool result — pushed the earlier read far enough back in context that it is effectively gone, or close enough to the edge that the model does not trust it is still accurate. The fix is to make the thing it needs small and durable, not to make it remember harder.
Does giving the agent a bigger context window fix this?
It delays it. A larger window holds more re-reads before compacting, but the underlying pattern — no persistent memory of file contents, only of decisions — is unchanged, and material in the middle of a very long context is attended to less reliably anyway. A trusted reference file is the structural fix; window size is a buffer.
Does this happen with Cursor, Codex and other agents too?
Yes. Any agent built on a stateless-per-call model has the same limitation. The symptom shows up most wherever the client's own file-caching or diffing is weakest, but no current client has true persistent file memory across context resets — a reference file your workflow controls is portable across all of them.
Should I just tell it not to re-read files?
Only alongside giving it something trustworthy to use instead. A bare "stop re-reading" instruction without a reference file just trades expensive-but-correct behaviour for cheap-but-wrong behaviour — it will guess at a shape it can no longer see, and guesses about code are worse than re-reads.