Why Claude and Cursor Lose Context on Large Codebases

You're mid-session with Claude Code or Cursor, making good progress on a feature, and then it happens: the AI starts making changes that contradict things it seemed to understand five minutes ago. It suggests a function that doesn't exist. It forgets you renamed a module last week. It loses the thread.

This isn't a bug — it's a fundamental constraint of how large language models work. Understanding it is the first step to fixing it.

The context window: a sliding amnesia window

Every AI model has a context window — the maximum amount of text it can "see" at once. It is large, hundreds of thousands of tokens on current models, and editors often use a smaller window per request. These numbers sound large, but a real codebase burns through them fast.

Consider what goes into a single session:

• The system prompt (hundreds of tokens)
• Your CLAUDE.md or project rules (hundreds to thousands of tokens)
• Files the AI reads to understand your code (thousands of tokens each)
• The full conversation history up to this point
• Your latest message and the AI's draft response

On a medium-sized project, a working session can fill tens of thousands of tokens before anything particularly complex has happened. On a large codebase, a long session reaches the ceiling.

What happens when the context fills up

When a context window gets full, something has to go. The model (or the tooling around it) starts dropping the oldest parts of the conversation. This means:

• Code it read earlier in the session gets evicted and "forgotten"
• Decisions made early in the conversation are no longer visible
• The AI starts hallucinating function names and file paths it saw but can no longer access
• It suggests changes that conflict with the project structure it was originally shown

The experience is disorienting — the AI still sounds confident, but it's now operating on a partial, stale view of your codebase.

Between sessions: a clean slate

Context-within-session exhaustion is frustrating. But there's a second, equally significant problem: between sessions, there is no memory at all.

Every time you start a new conversation with Claude Code, it starts completely blank. The architectural decisions you discussed yesterday, the reason you chose a particular pattern, the bug you found and deferred — none of that carries over. You re-explain your project from scratch, every single time. On a complex codebase, this re-explanation cost is enormous.

Why CLAUDE.md helps — but only partially

Claude Code's answer to cross-session memory is CLAUDE.md — a markdown file where you document your project's conventions, architecture and instructions. It works reasonably well for a small project. But it has hard limits:

• It describes your project at the moment you wrote it, not what it is today
• It consumes context tokens every session (the AI re-reads it from scratch)
• It has no knowledge of actual symbols, functions or call graphs in your code
• You have to keep it up to date manually as the codebase evolves

A good CLAUDE.md is still worth writing. But it doesn't solve the fundamental problem of context-at-scale.

Within a session: reading the code is the work

Inside one session, most of the context goes to code the agent has to read to change it, and Claude Code's own grep already finds that code precisely. What you can keep lean is everything around it: one task per session, big logs and dumps kept out of the conversation, /clear or /compact between tasks. The problem that needs something new is the other one — what happens when the session ends.

What does: a memory the agent writes for itself

The between-sessions problem is different, and it is fixable. The knowledge that gets lost when a session ends — where the work stopped, what was tried and dropped, the trap in the Redis TTL, the decision to keep sessions out of JWT — is knowledge the agent had. It only needs to write it down, in its own terms, and get it back the next time without anyone remembering to paste it.

That is what Codelux AI does. At the end of a task the agent calls memory_set with a free JSON: summary, next step, open points, traps, decisions, facts anchored to a file and line, a map of the code it touched. The next session, a hook puts that memory back in context, together with what changed in those files since. When a prompt touches something the memory knows, a second hook adds it; when nothing matches, it adds nothing. A timeline keeps every memory, note, edit, commit and lock, with who and why, so a person can read the history too.

Summary

• Context windows are finite; large codebases exhaust them quickly
• When context fills, the AI forgets earlier code and starts hallucinating
• Within a session, reading code is the work: keep one task per session and big outputs out of the conversation
• Between sessions, there is no memory at all — CLAUDE.md is a partial workaround
• What helps is a memory the agent writes for itself and gets back automatically, plus a timeline people can read

← Back to the blog  |  Next: CLAUDE.md best practices →