Context Management

You ask the agent to “add pagination to the API.” It generates a pagination utility from scratch — ignoring the one that already exists in src/utils/pagination.ts. It creates a new response format that conflicts with your existing API patterns. It uses offset/limit when your project standardized on cursor-based pagination two months ago. The model is not stupid. It just did not have the right context. Context management is the difference between an AI that knows your project and one that is coding blind.

What You’ll Walk Away With

• Proficiency with every @ mention type in Cursor: files, folders, code, docs, and past chats
• A strategy for when to explicitly provide context versus letting the agent find it
• Techniques for managing context in long conversations to prevent degradation
• The @Docs workflow for integrating external documentation

The @ System

Type @ in the agent input to open the context menu. Use arrow keys to navigate categories, then type to filter. Press Enter to select.

@Files and Folders

Reference specific files or entire directories to give the agent targeted context.

@src/utils/pagination.ts Add cursor-based pagination to the /api/users endpoint
using the same pattern as this existing utility.

This tells the agent exactly where to look for the existing pattern. Without the @ reference, the agent might search the codebase and find it — or it might not.

Folders: Reference a directory to give the agent an overview of its contents:

@src/api/ Create a new endpoint for user notifications that follows
the patterns used in the existing endpoints in this directory.

After selecting a folder, type / to navigate deeper into subdirectories.

Note

Large files and folders are automatically condensed to fit within context limits. This is usually fine, but for very large files you may want to reference specific code sections instead.

@Code

For more precise context than entire files, use @Code to reference specific functions, classes, or code blocks:

@Code UserService.createUser Refactor this method to add email verification.
Keep the same interface but add a step that sends a verification email
before returning the user object.

This is more efficient than referencing the entire file when you only need the agent to focus on one function.

@Docs

Cursor maintains a library of documentation for popular frameworks and libraries. You can also add your own.

Using built-in docs:

@Docs Next.js How do I implement middleware that checks authentication
on all /api/* routes in the App Router?

Adding custom documentation:

1. Type @Docs in the chat
2. Select Add new doc
3. Paste the URL of the documentation site (e.g., your internal API docs)
4. Cursor crawls and indexes the documentation

Once added, the documentation is available in all conversations. You can manage your docs in Cursor Settings then Indexing and Docs.

Copy-paste prompt for documentation-aware coding

@Docs Drizzle ORM Create a migration that adds a notifications table with:
- id (uuid, primary key)
- user_id (foreign key to users)
- channel (enum: email, sms, push)
- status (enum: pending, sent, failed, delivered)
- created_at (timestamp with default)
- delivered_at (nullable timestamp)

Use the Drizzle migration patterns from the docs, not raw SQL.

@Past Chats

Reference previous conversations to bring context from earlier sessions into the current one.

@Past Chats [notification system planning] We decided on a webhook-based
delivery tracking approach in our earlier conversation. Now implement the
webhook endpoint using that design.

This is significantly better than copy-pasting from an old conversation. The agent gets the full context of the referenced chat, including code changes and tool results.

When to Provide Context Versus Letting the Agent Search

The agent has built-in search tools. It can grep your codebase, read files, and explore directories. So when should you explicitly provide context with @, and when should you let it figure things out?

Provide Explicit Context When:

• You know exactly which files are relevant
• The pattern you want followed is in a specific file
• The task involves modifying existing code (reference the file to be modified)
• You have had a previous conversation that informs this work

Let the Agent Search When:

• You do not know where the relevant code is
• You want the agent to discover how your codebase is structured
• The task is broad and many files might be relevant
• You want the agent to find all instances of a pattern

Caution

A common mistake is over-providing context. Including 10 irrelevant files confuses the agent about what is important. If you know the two files that matter, reference just those two. If you do not know what matters, let the agent search.

The Hybrid Approach

For complex tasks, combine explicit and discovered context:

@src/services/billing/subscription.ts The subscription renewal logic needs
to handle failed payments with a 3-retry strategy. Check how we handle
retries elsewhere in the codebase and use the same pattern.

You pointed to the specific file to modify, but asked the agent to find the retry pattern on its own.

Managing Context in Long Conversations

Every message in a conversation adds to the context window. After 20-30 exchanges, the accumulated context can cause problems:

• The agent starts forgetting instructions from early in the conversation
• Response quality degrades as the model juggles too much information
• Cost increases because every new message includes all previous context

When to Start Fresh

Start a new conversation when:

• You are moving to a different task or feature
• The agent keeps making the same mistake despite corrections
• You have finished one logical unit of work
• The conversation has gone past 15-20 exchanges

How to Carry Context Forward

When starting a new conversation, you do not lose your previous work:

1. @Past Chats — reference the old conversation for its context
2. @Files — reference the files that were modified in the previous session
3. Saved plans — reference .cursor/plans/ files for implementation context

Copy-paste prompt for starting a fresh conversation with context

I'm continuing work on the notification system. In the previous session, we:
- Created the database schema (migrations are complete)
- Implemented the preferences API (/api/users/:id/preferences)
- Started but didn't finish the email worker

@src/services/notifications/email-worker.ts
@.cursor/plans/notification-system.md

Let's pick up where we left off. The email worker needs retry logic
and SendGrid integration.

Advanced Context Techniques

Drag-and-Drop Files

You can drag files directly from the file explorer sidebar into the agent chat. This is the fastest way to add file context without typing @.

Images as Context

Paste screenshots directly into the chat. This works with all models, but Gemini 3 Pro has the strongest image understanding. Use it for:

• Screenshots of UI bugs (“fix this layout issue”)
• Design mockups (“implement this design”)
• Error screenshots (“I’m seeing this error in the browser console”)

The Context Gauge

Hover over the context gauge in the prompt input to see:

• How much of the context window is used
• Which rules are currently active
• Which files and tools are loaded

If you are near the limit, start a new conversation or remove unnecessary context.

Cursor 2.0 Context Changes

Cursor 2.0 simplified the @ mention system. Several explicit context types were removed because the agent now gathers them automatically:

• @Web — removed, the agent can browse the web via MCP or built-in tools
• @Git — removed, ask the agent directly about git history
• @Linter Errors — removed, the agent reads linter output automatically
• @Recent Changes — removed, the agent can query git diff on its own

The remaining @ types (@Files, @Folders, @Code, @Docs, @Past Chats) are the ones where explicit human direction adds value over automatic discovery.

When This Breaks

Agent ignores the files you referenced: This usually means the files are too large and were condensed. Try referencing a specific function with @Code instead of the whole file.

@Docs returns outdated information: Documentation is cached. Go to Cursor Settings then Indexing and Docs and re-index the documentation source.

Past chat reference does not include the right context: The agent gets the full conversation, but very long past chats may be summarized. For critical context, write it into a plan file and reference that instead.

Context window full: You have accumulated too much context. Start a new conversation. Reference only the specific files and plans needed for the current task.

Agent hallucinates despite good context: Sometimes the model gets confused even with correct context. Start a new conversation, provide the same context, and rephrase the question. A fresh start often resolves hallucinations.

What’s Next

Build Your First Feature Put everything together -- rules, context, Plan mode, and Agent mode -- to build a real feature from scratch.