You ask Cursor Agent to change the payments module in a monorepo, and it edits user-center DTOs instead. Claude Code runs twenty bash rounds, then forgets “never import internal legacy packages directly.” That is not the model suddenly getting dumber — it is the most common failure mode in large projects: context loss.
In 2026, both Cursor and Claude Code advertise million-token context, yet on real engineering floors, “forgot our agreement” still happens often. This article delivers a repeatable five-step troubleshooting method: first classify how context was lost, then check budget, index, boundaries, repo conventions, and session strategy in order. Tool versions as of 2026-07-17 (Cursor 1.x, recent Claude Code CLI).
Quick Answer: five-step overview
| Step | What you are checking | Typical action | Signal it worked |
|---|---|---|---|
| 1. Classify symptoms | Session truncation / index miss / rules not loaded | Use the table below — don’t swap models first | You know whether to fix “session” or “repo” |
| 2. Check context budget | Tool rounds and auto-injection filling the window | Close unrelated tabs, reduce @ files, use a smaller model for exploration | Fewer repeated instructions; diffs stop contradicting themselves |
| 3. Rebuild index | .cursorignore, huge dirs, stale index | Reindex; exclude node_modules / DerivedData | Agent finds the right package path automatically |
| 4. Set boundaries | Task scope too wide | Subfolder workspace, explicit @ call chain, handoff block | Changed files stay inside the expected module |
| 5. Write repo conventions | Verbal rules never became searchable text | AGENTS.md, .cursor/rules, split long sessions | New sessions still follow the same constraints |
What does “context loss” mean in a large project?
Align on terms first: a long context window answers “can this many tokens fit right now?” Effective context answers “which facts did the model actually use for this decision?” That gap widens in big repos — see our earlier piece on persistent memory in AI coding.
When engineers say context was “lost,” it usually falls into three buckets:
| Type | What you see | Common root cause | Check first |
|---|---|---|---|
| A. Session truncation | Same thread drifts; earlier constraints get overturned | Multi-round tool output pushes out early instructions; compact / summary drops detail | Steps 2, 5 |
| B. Index miss | “Can’t find that module” / “assumes table doesn’t exist” | Over-aggressive ignore, stale index, repo too large with noisy retrieval | Steps 3, 4 |
| C. Rules not loaded | New session forgets naming style and forbidden paths | Rules only in chat; missing or overlong AGENTS.md | Step 5 |
Step 1: Classify first — don’t treat every “forgot” as a model problem
When you hit an error or a nonsensical diff, run this 60-second decision tree:
- Same session contradicts itself? → Likely A session truncation — go to Step 2.
- New session forgets agreements? → Likely C rules not loaded — go to Step 5.
- Model insists a file doesn’t exist, but
grepfinds it? → Likely B index miss — go to Steps 3–4. - Error is
context length exceeded/prompt is too long? → Clear budget issue — go straight to Step 2.
Cursor and Claude Code differ slightly: Cursor Composer / Agent auto-injects open files and index snippets, so the IDE can “quietly blow up” the window; Claude Code terminal Agents more often lose mid-chain decisions after long bash sequences + auto-compact. For tool comparison, see the 2026 selection guide.
Step 2: Check context budget — a big window is not automatic thrift
Real token use in one Agent task usually comes from: system prompt + rule files + @ files + tool output (grep, test logs) + history summary. In a 120k-line TypeScript monorepo, a single Cursor Agent run that auto-reads eight related files and runs the full test suite can land at 80K–120K input tokens — before retries.
2.1 On the Cursor side
- Close editor tabs unrelated to the task; don’t leave huge JSON or lock files open.
- Use a smaller-context model or plain Chat for exploration; open Agent only after the plan is clear.
- Don’t chain “refactor + write tests + change CI” in one Composer — split into three tasks, each with an explicit file list.
- Watch Codebase indexing in Settings; when indexing fails, Agent falls back to grep and the window inflates faster.
2.2 On the Claude Code side
- On long tasks, watch for auto-compact; after compact, paste a fixed “non-negotiable constraints” block.
- Redirect huge command output to a file and have Agent
tailkey lines instead of stuffing 5,000 log lines into chat. - Before
/clearor a new session, write conclusions toHANDOFF.mdor an issue comment.
| Signal | Likely cause | Do now |
|---|---|---|
| Edits get worse toward the end | Early constraints pushed out of the window | New session + handoff block + shorter task |
| API bill spikes on one task | Re-reading large files / full test output | Limit test scope; use head/tail |
| “Context exceeded” error | Hard limit hit | Fewer @ files, split task, exploration model |
Step 3: Rebuild index and clean up ignore — help the Agent “find” code
Type B’s core issue: the model isn’t refusing to look — retrieval never delivered the right file.
3.1 Check .cursorignore / .claudeignore
Sensible ignores save index time; over-ignore creates ghost blind spots. Keep excluding:
node_modules/,.git/,dist/,build/,DerivedData/- Directories with huge generated code (if you must edit generated output, @ single files explicitly)
- Binaries and media assets
Do not casually ignore business source packages — many teams exclude all of legacy/ and then wonder why Agent never sees the compatibility layer.
3.2 Trigger a reindex
Cursor: Settings → Indexing & Docs → Resync Index (wording varies by version). First full index on a large repo on M4 often takes 15–40 minutes; if the laptop is also running Ollama + Xcode, consider running indexing on a dedicated cloud Mac node to avoid swap timeouts for both IDE and Agent — consistent with memory findings in our M4 AI coding benchmarks.
git ls-files | wc -l in weekly CI and compare to indexed file counts. When coverage drops sharply, schedule a shared Reindex instead of everyone restarting Cursor on guesswork.Step 4: Set boundaries — “whole repo at once” is the enemy
Sometimes context loss is really an oversized task definition: you ask to “optimize payments” and the model touches forty packages a little each.
4.1 Narrow the workspace
- Use VS Code / Cursor multi-root workspace — open only
apps/checkout+packages/payment-sdk. - Start Claude Code in a subdirectory:
cd apps/checkout && claudeso unrelated paths don’t enter retrieval.
4.2 Explicit @ call chain
When changing an API, @ at least: interface definition → server implementation → one real caller → related test. In Vue + Spring Boot full-stack repos, adding call-chain @ references dropped “forgot the frontend” from about 40% to under 10% — a more systematic approach is in our CodeGraph case study.
4.3 Handoff block template
Before switching sessions on a long task, paste a fixed structure:
## Handoff
- Goal:
- Done:
- Not done:
- Non-negotiable: (paths / naming / forbidden imports)
- Suggested files to open next:This beats “summarize the above” because entries are checkable, not prose that drops constraints.
Step 5: Put conventions in the repo and learn to split sessions
Type C’s fix: make rules part of the repository, not part of the chat.
5.1 AGENTS.md and Cursor Rules
At repo root, maintain short, actionable conventions (aim for < 200 lines; split if longer):
- Module boundaries and “do not let AI edit” paths (e.g.
generated/,vendor/) - Naming and error-handling style (one good and one bad example each)
- Checklist: which layers must change when an API changes
- Commands that must run:
pnpm test payment --filter=...
Cursor reads .cursor/rules; Claude Code reads AGENTS.md and CLAUDE.md. Keep them factually aligned — conflicting copies confuse both tools.
5.2 When to split sessions
| Scenario | Recommendation |
|---|---|
| One feature merged; starting the next | New session + Handoff |
| Agent misunderstands three times in a row | Stop, write Handoff, shrink @ scope |
| Compact fired / context bar past halfway | Persist conventions to disk before continuing |
| Continuing next day | Always new session + link to PR/issue |
When call chains span a dozen packages and @ files still aren’t enough, then evaluate code knowledge graph tools — that is an enhancement after Step 5, not the first move.
Case study: 45 minutes on a 120k-line monorepo
A B2B SaaS team (8 backend + 4 frontend) uses Cursor + Claude Code on a pnpm monorepo (~118k LOC, 6 apps, 23 packages). Symptom: when Agent edited billing-api, it repeatedly broke type exports from auth-middleware — and new sessions kept doing it.
| Order | Finding | Action | Result |
|---|---|---|---|
| Step 1 | New sessions also forgot rules → Type C | Confirmed no AGENTS.md | Root cause identified |
| Step 3 | .cursorignore wrongly excluded packages/auth | Fixed ignore + Reindex | Agent could reference middleware |
| Step 4 | Task “fix billing” too broad | Workspace narrowed to billing + auth; @ tests | Files touched dropped from 19 to 6 |
| Step 5 | Verbal rules never written down | Added 120-line AGENTS.md + CI import-boundary check | No same-class regressions for a week of PRs |
They did not upgrade to a pricier model. Mean tokens per task fell ~35% because Agent stopped full-repo grep loops. Reindex and nightly tests moved to a Macstripe 24GB cloud node; the laptop only SSH’d in to code — swap warnings during indexing disappeared.
Self-check checklist: 2 minutes before you start
- ☐ You can name whether this task is type A, B, or C
- ☐ Editor has only relevant files open; no huge logs open
- ☐
.cursorignoredoes not exclude business source - ☐ Index is healthy, or Reindex is scheduled
- ☐ Workspace scope ≤ 2–3 related packages
- ☐ Call-chain key files @’d (including one test)
- ☐
AGENTS.mdlists this task’s non-negotiables - ☐ Handoff template ready for a long task
FAQ
The context window is rated at 200K — why does context still get lost?
The window is a capacity ceiling, not an attention guarantee. Multi-round Agent tool calls push early instructions out of effective attention; compact summaries drop detail. Searchable repo conventions beat longer chat history.
Which loses context more easily — Cursor or Claude Code?
Cursor tends to lose boundaries through IDE auto-injection and long Composer chains; Claude Code tends to lose mid-chain decisions after long bash runs and compact. Both need explicit @, AGENTS.md, and task splits — neither is “easier.”
Does .cursorignore affect manual @ references?
Manually @’ing a single file usually still works; what breaks is whole-repo index and auto-retrieval. Ignored directories need explicit @ or the Agent won’t find them on its own.
Should I add a code knowledge graph?
Worth a pilot when call chains cross many packages and @ files still miss edits. For small repos or clear boundaries, AGENTS.md + CI first gives better ROI.
Can switching Macs or going to the cloud help?
It won’t enlarge model context, but a dedicated 24GB M4 reduces swap during indexing and tests, avoiding Agent timeouts — and can be the team’s shared “heavy task” environment. Try by the day to validate.
Conclusion
“Context loss” with Cursor / Claude Code in large projects is mostly an engineering problem, not something a new model tier magically fixes. Run these five steps — classify symptoms → check budget → rebuild index → set boundaries → write AGENTS.md and split sessions — and you will usually spend less and get steadier results than blindly enabling Max mode.
- Drift inside a session: reduce injection, split tasks, use Handoff.
- Can’t find files: fix ignore, Reindex, narrow workspace.
- New session forgets: put conventions in the repo; let CI enforce them.
Next, read persistent memory and code knowledge graphs for enhancements after Step 5.
