Context management in Cursor

Context management in Cursor is the choice of what the agent sees before it writes code: files, folders, code selections, indexed documentation, past chats and rules, attached with @ mentions or found by the agent’s own search. One canonical example file usually beats a long description, and too many attachments make the output worse, not better.

You ask the agent to add pagination to GET /api/users. It writes a new pagination helper from scratch, ignores the one in src/utils/pagination.ts, and uses offset/limit although the project moved to cursor-based pagination months ago. Nothing is wrong with the model. It never saw the helper, and nobody told it which pattern wins.

This page is for the developer in their first weeks with Cursor who wants the agent to follow the project’s existing patterns instead of inventing new ones. It sits in the quick-start path after MCP setup in Cursor and before your first feature.

What you get from managing Cursor’s context

• A table of the context kinds Cursor’s agent accepts and when each one pays off.
• Four copy-paste prompts: pattern reference, boundary fence, current library docs, and a clean handoff between chats.
• A fixed order for adding context, so you attach only what the output proves you need.
• A context receipt prompt and three terminal checks that show whether the agent reused the right code and stayed inside its fence, without reading every line of the diff.
• A failure-mode table with the recovery for each symptom.

Which context can you give Cursor’s agent?

Type @ in the agent input to open the context menu, and filter by typing to find the item to attach. Picker labels have changed between Cursor releases, so trust the menu on your screen over any screenshot. The kinds of context below are the ones Cursor’s agent protocol carries, checked in @cursor/sdk 1.0.32 on 2026-09-26.

Context kind	What the agent gets	Reach for it when
File	The file you name	One file holds the exact pattern to copy, or is the file to change
Folder	A directory to work in	The agent needs the layout and naming of an area, not every file in it
Code selection	A selected function, class or block	Only one function matters and the file is long
Docs	An indexed documentation source	The task depends on a library or internal API the model may know only from old training data
Past chat	An earlier conversation	You resume work whose decisions live in that chat
Terminal output	A terminal or a selection from it	A failing test run or stack trace is the evidence
Git and pull requests	Commits, diffs and pull requests	The task is “finish, review or explain this change”
Rules	A rule you select	A convention should apply to this request even though its rule does not load automatically
Images	A pasted screenshot or mockup	A UI bug or a design is easier to show than to describe

Rules also add context without a mention: a rule set to always apply loads on every request. Keep those short and move the rest into file-scoped rules, as project rules in Cursor explains. Cursor’s docs say it also reads AGENTS.md in the project root and subdirectories, and Cursor’s help says it reads CLAUDE.md files the same way and always applies them to every conversation. Cursor’s help also says rules apply to Agent only, not to Tab completion, Inline Edit or Bugbot PR reviews (both checked 2026-10-12). Every attachment costs tokens on every turn of the chat; token management in Cursor covers the bill.

Point at one canonical example instead of describing the pattern

A description of your conventions leaves room for interpretation. A file that already follows them does not. Compare two prompts for the same task:

Weak: Create an orders endpoint. We use Express with auth middleware,
zod for validation and our own error format.

Strong: Create POST /api/orders following @src/routes/users.ts exactly:
same middleware order, same zod validation, same AppError handling,
same response shape.

The strong prompt gives the agent something to copy and something to be checked against. Cross-cutting conventions fail the same way: ask for error handling without context and the agent wraps the handler in try/catch and returns { error: "Something went wrong" }, while your codebase already has an AppError class, a central error-handler middleware and a response format with error codes. Attach the middleware and the class, and the agent throws AppError like every other route. Pick the example deliberately: the newest file that follows the current convention, not the oldest file in the directory. If two files disagree, the agent may follow either one.

Copy-paste prompt: follow a canonical example

Create src/services/notification-service.ts.

Pattern reference: @src/services/email-service.ts
Copy exactly: class structure, constructor dependency injection,
error handling with AppError from src/lib/errors.ts, and the test
file layout in tests/services/email-service.test.ts.
Change only the domain logic: notifications instead of emails.

Before writing code, list the three conventions from the reference
file you will follow. Then write the service and its test file.

After you paste a prompt, check that each @ reference shows up as an attached item. If a path stays plain text, delete it, type @ again and pick the file from the menu.

Use a folder mention when the agent needs a map

Attach a folder when the question is “where does this go and what is it called”, not “copy this function”. For example: Look at @src/components/ and add a NotificationBanner component that follows the same file layout, naming and story file as the existing components. A folder is cheaper than attaching every file in it, and the agent can open the files it needs.

Use a code selection for one function

Attach only the function as a code selection when the rest of a long file is noise: Refactor calculateDiscount (attached) to support percentage and fixed-amount discounts. Keep the signature. Attaching the whole file also works; it costs more tokens and gives the agent more to misread.

When should you attach context and when should you let the agent search?

Cursor’s agent can search the codebase, read files and run commands on its own. Attaching context is a way to remove guesswork, not a requirement for every request.

Situation	Attach it yourself	Let the agent search
You know which file holds the pattern	Yes, one file	—
You know which file will change	Yes	—
You do not know where the code lives	—	Yes, and ask it to report what it found
The task touches every caller of a function	Attach the function	Let it find the callers
An earlier chat made the design decision	Attach the past chat or a handoff note	—
The task is broad and exploratory	—	Yes, in Plan Mode first

The hybrid works best for most real tasks: attach the file to change and the rule that governs it, and ask the agent to find the rest. For example: @src/services/billing/subscription.ts Add a three-retry strategy for failed renewal payments. Search the codebase for how we already retry external calls and reuse that helper; tell me which one you picked.

Add context in a fixed order, and only when the output proves you need it

Attaching ten files “just in case” makes the agent weigh irrelevant code as heavily as the one file that matters. Start small and let each wrong answer tell you what was missing.

1. Task only. Write the task and the acceptance check (“the new test passes, npm run typecheck is clean”). Let the agent search.

2. Add the canonical example if the output uses the wrong pattern: one file, attached with @.

3. Add the governing rule if it still misses a convention that a rule already states, for example the error-handling rule.

4. Add a folder if it puts files in the wrong place or names them wrongly.

5. Add docs if it calls an API that does not exist in your library version.

6. Start a new chat if the third correction in a row does not stick. The history now carries the wrong attempts, and they compete with your corrections.

When a step fixes the output for good, write that context into a rule or the canonical example, so the next person does not repeat the ladder.

Fence the change with boundary context

Positive context tells the agent what to copy. Boundary context tells it what not to touch. Name both, and name the files by path so you can check the fence afterwards.

Copy-paste prompt: add a feature inside a fence

Add rate limiting to the /api/users routes in @src/routes/users.ts.

Follow the middleware pattern in @src/middleware/auth.ts.

Boundaries:
- Change only src/routes/users.ts, and add src/middleware/rate-limit.ts
  and tests/middleware/rate-limit.test.ts.
- Do not change middleware order in src/app.ts.
- Do not add dependencies; use what package.json already has.
- Do not add caching, logging or configuration options nobody asked for.

If the task cannot be done inside these boundaries, stop and tell me
which boundary blocks it instead of working around it.

Exclusions such as “no caching, no logging” matter as much as the file list: a vague task invites the agent to add abstractions you then have to review and delete. The last line matters too. Without it, an agent that hits a boundary tends to find a creative way around it, which is the change you least want to discover in review.

Give the agent current library documentation

Models learn libraries from training data, which lags the release you run. Two ways close the gap in Cursor.

• Indexed docs. Cursor’s docs context attaches a documentation source Cursor has indexed, including sites you add by URL. The Docs entry in Cursor Settings manages indexed sources; its location has moved between releases, so search Settings for “Docs”. Use it for internal API docs and for libraries you work with every day.
• Context7 MCP server. Context7 fetches version-specific docs for a named library on request (npm @upstash/context7-mcp 4.1.1, checked 2026-09-26). Add the remote server to your global ~/.cursor/mcp.json; the API key is optional and belongs in the global file, never in the repository. Context7 for coding agents covers keys, library pinning and the skills mode.

{
  "mcpServers": {
    "context7": { "url": "https://mcp.context7.com/mcp" }
  }
}

If you have a key, add it as a header on the same entry:

"context7": {
  "url": "https://mcp.context7.com/mcp",
  "headers": { "Authorization": "Bearer YOUR_API_KEY" }
}

Replace YOUR_API_KEY with your Context7 key; the file lives in your home directory, so the key never enters the repository.

Copy-paste prompt: write against the library version you run

Check package.json for the installed drizzle-orm version, then use
context7 to fetch the drizzle-orm docs for that version.

Using only APIs that exist in that version, add a notifications table:
id (uuid primary key), user_id (foreign key to users.id), channel
(enum: email, sms, push), status (enum: pending, sent, failed,
delivered), created_at (timestamp, default now), delivered_at
(nullable timestamp). Generate the migration with drizzle-kit, not
raw SQL.

List every drizzle API you used with the doc page it came from.

Keep files out of the agent’s reach with .cursorignore

Generated code, snapshots, vendored libraries and large fixtures pull the agent’s search towards files nobody should copy. .cursorignore uses .gitignore syntax at the repository root, and Cursor’s agent code loads both .gitignore and .cursorignore (checked in @cursor/sdk 1.0.32, 2026-09-26), but only .cursorignore is the one to use for keeping files away from the agent. When the agent searches a path this way blocks, the tool returns Path '…' is filtered out by .cursorignore (checked in @cursor/sdk 1.0.32). Build the file from your repository’s real file counts, as tuning Cursor for large codebases shows.

Carry context across chats without dragging the whole history

Every message and tool result stays in the chat, so a long chat carries old attempts, dead ends and outdated plans. When the chat fills the model’s context window, Cursor compacts it into a summary of its own choosing. Start a new chat when you finish a task, switch areas of the codebase, or notice the agent repeating a mistake you already corrected.

You have two ways to bring the useful part along. A past chat reference attaches the earlier conversation as it was. A short handoff note that you write, or ask the agent to write, keeps only what you choose, and you can review it in 30 seconds. Prefer the note for anything that must survive: decisions, constraints and the next step.

Copy-paste prompt: close a chat with a handoff note

We are ending this chat. Write docs/handoff/notifications.md with:
- Goal: one sentence.
- Decisions: each decision we made and its reason, one line each.
- Done: files changed, with the test that proves each change.
- Open: the next step, and any test that is currently failing.
- Context for the next chat: the files it should attach with @.
Keep it under 40 lines. Do not paste code that is already committed.

Then open a new chat and send: Read @docs/handoff/notifications.md and continue with the step under Open. Delete the note once the new chat has picked up the work, unless your team wants such notes in review; do not add its folder to .cursorignore, because the next chat has to read it. Token management in Cursor shows how to log each compaction with a preCompact hook, so you see which chats run too long.

How do you prove the agent used the right context?

Right context shows up in the result: the new code imports the existing helper, touches only the fenced files, and passes the project’s gates. You can check all three without reading the diff line by line.

1. Ask for a context receipt before the code. The receipt turns an invisible choice into a list you can compare with what you expected.

Copy-paste prompt: context receipt

Before you change anything, reply with a context receipt:
1. Files you read and why, one line each.
2. The existing helper, type or pattern you will reuse for each part
   of the task, with its path.
3. Anything you expected to find and did not.
4. Files you plan to create or change.
Wait for my OK before editing.

If the receipt names a new helper where you know one exists, attach the existing one and ask again. That costs one message; finding it in review costs a rewrite.

2. Check reuse and scope in the terminal. After the agent finishes and before you commit, run checks like these for the pagination example. For that task, the fence was src/routes/users.ts and tests/routes/users.test.ts:

# Every file the agent created or changed, including new files
git status --porcelain -uall

# Files outside the fence you set in the prompt: expect no output
{ git diff --name-only HEAD; git ls-files --others --exclude-standard; } \
  | grep -Ev '^(src/routes/users\.ts|tests/routes/users\.test\.ts)$'

# The route reuses the existing helper: expect one import line
rg -n "utils/pagination" src/routes/users.ts

# No second pagination helper appeared anywhere else: expect no output
rg -n "export (default )?(async )?(function|const) \w*[Pp]aginat" src --glob '!src/utils/pagination.ts'

3. Run the gates the project already trusts. Tests, the type check and the linter prove behaviour; the checks above prove the agent built on the right code. When both pass, the developer who ran the chat signs off and names the context receipt in the pull request description, so the reviewer checks one list instead of re-deriving it. Your first feature puts this into a full loop with tests first.

What breaks in Cursor context management, and how to recover

Symptom	Likely cause	Recovery
The agent writes a new helper next to an existing one	It never saw the existing one	Attach the helper file, ask for a context receipt, and delete the duplicate with the reuse check above
The agent follows an outdated pattern	Your example file, or an older file it found, uses the old pattern	Attach the newest file that follows the current convention and name the old one as “do not copy”
Files land in the wrong directory	It does not know the layout	Attach the target folder, and add a file-scoped rule if it happens twice
Code calls an API that does not exist in your version	It relied on training data	Add indexed docs or use Context7, and ask it to cite the doc page for each API
Docs context returns outdated pages	The indexed source is stale	Remove the source in the Docs entry of Cursor Settings and add the URL again
The output adds caching, logging or layers nobody asked for	The task was vague about scope	Add explicit exclusions to the boundaries and ask for the smallest change that passes the test
The agent ignores a file you attached	The file is long and the relevant part is buried	Attach the one function as a code selection and quote its name in the prompt
A search returns Path '…' is filtered out by .cursorignore	The path matches a .cursorignore pattern	Remove the pattern if the agent needs the file, or attach a non-ignored copy of the relevant part
A rule and the example file disagree	Two sources of truth	Fix whichever is wrong; until then, say in the prompt which one wins
Corrections stop sticking after a long chat	History full of old attempts, or a compaction dropped your instruction	Write a handoff note and continue in a new chat
Ten attached files, worse output	The agent weighs irrelevant code	Cut to the two or three files that matter and let it search for the rest

Where to go next after context management

Build your first AI-assisted feature Put rules, context, Plan Mode and tests together on one real feature.

Project rules in Cursor Turn the context you keep attaching into rules that load on their own.

Token management in Cursor Measure what context costs and log every compaction.

Prompt templates for Cursor Reusable prompts that build on the context patterns on this page.

Context management across tools Context windows, documentation as context and memory patterns for Claude Code, Codex and Cursor.

Using Claude Code or Codex as well? The same ideas apply with different mechanics: see Claude Code’s memory system and context patterns in Codex.