Context Management

The AI's responses are only as good as the context it has. Understanding how Cursor manages context—and how you can control it—leads to significantly better results.

How Cursor Builds Context

Automatic Context

Cursor automatically includes:

1. Current file: The file you're editing
2. Selection: Any highlighted code
3. Cursor position: Where your cursor is
4. Open tabs: Files you have open
5. Recent edits: Your recent changes
6. Related files: Imports and dependencies
7. Type definitions: Types used in your code

Codebase Indexing

Cursor indexes your entire codebase for:

• Semantic search: Finding relevant code by meaning
• Symbol lookup: Functions, classes, variables
• File relationships: Import/export connections
• Pattern recognition: Coding style and conventions

Viewing Current Context

In Chat

The context bar shows what's included:

Context: main.ts (current) | utils.ts (import) | types.ts (types)

In Composer

Composer shows context more explicitly:

Files in context:
📄 src/components/Button.tsx (added manually)
📄 src/lib/utils.ts (auto-detected import)
📄 src/types/index.ts (auto-detected types)

Adding Context Manually

Using @ Mentions

The most direct way to add context:

Example Usage

@components/Button.tsx @components/Input.tsx
Create a new Form component that combines these

@Codebase Where do we handle user authentication?
Then create a similar pattern for API key auth.

Folder Context

Reference entire directories:

@src/components/
Update all components to use the new design tokens

Excluding Context

The .cursorignore File

Create .cursorignore in your project root:

# Don't index large generated files
dist/
build/
.next/
node_modules/

# Sensitive data
.env*
secrets/
*.pem
*.key

# Large data files
*.csv
*.json
data/

# Dependencies
vendor/
packages/*/node_modules/

Why Exclude Files?

1. Performance: Large files slow indexing
2. Relevance: Generated code adds noise
3. Security: Keep secrets out of context
4. Accuracy: Irrelevant code confuses suggestions

What to Always Exclude

# Build outputs
dist/
build/
.next/
out/

# Dependencies
node_modules/
vendor/
.venv/
venv/

# Generated code
*.generated.ts
*.d.ts
coverage/

# Large data
*.csv
*.log
*.sql

# Secrets
.env*
*.pem
*.key
secrets/

Context Strategies

Strategy 1: Minimal Context

For simple questions, less is more:

# Just ask about a specific file
@utils.ts What does the formatDate function do?

Strategy 2: Related Files

For changes that span related code:

@api/users.ts @hooks/useUsers.ts @types/user.ts
Add a new field "role" to users throughout

Strategy 3: Pattern Reference

Show existing patterns you want to follow:

@components/UserCard.tsx @components/ProductCard.tsx
Create an OrderCard following the same patterns

Strategy 4: Full Codebase Search

When you don't know where something is:

@Codebase How is caching implemented in this project?

Context Window Limits

AI models have context limits. When you exceed them:

1. Oldest context gets truncated
2. Some files may be partially included
3. Responses may miss important details

Managing Large Contexts

Be selective:

# ❌ Too broad
@src/ Fix all the issues

# ✅ Targeted
@src/components/Button.tsx @src/components/Input.tsx
Fix the accessibility issues in these form components

Use semantic search:

# Instead of including many files
@Codebase Find where we handle form validation
# Then specifically reference those files

Break into steps:

# First: Understand
@Codebase Where is error handling done?

# Then: Modify specific files
@lib/errors.ts @api/middleware.ts
Update these to use the new error format

Indexing Your Codebase

Checking Index Status

Cursor shows indexing status in the status bar:

• Indexing...: Still processing
• Indexed: Ready for semantic search
• Warning icon: Indexing issues

Reindexing

If suggestions seem outdated:

1. Open Command Palette (Cmd+Shift+P)
2. Run "Cursor: Reindex Workspace"
3. Wait for indexing to complete

Indexing Large Projects

For very large codebases:

1. Use .cursorignore liberally
2. Exclude test fixtures and data
3. Exclude generated files
4. Consider workspace folders for subsets

Context in Different Features

Tab Completion Context

Tab uses:

• Current file
• Open files
• Import chain
• Type definitions
• Recent edits

Inline Edit (Cmd+K) Context

Includes:

• Current file
• Selected code
• Immediately related symbols

Chat Context

Uses:

• Attached files (@ mentions)
• Conversation history
• Current file (if open)

Composer Context

Most extensive:

• All added files
• Codebase search results
• Full import chains
• Recent conversation

Debugging Context Issues

"AI doesn't understand my code"

1. Check if file is in .cursorignore
2. Verify codebase is indexed
3. Explicitly @ mention the relevant files
4. Include type definitions

"Suggestions reference wrong patterns"

1. Add .cursorrules with correct patterns
2. @ mention files with correct patterns
3. Exclude files with old patterns from context

"Responses are too generic"

1. Add more specific context
2. Include example code you want followed
3. Reference your types and interfaces

Advanced Context Techniques

Context Templates

Create files specifically for AI context:

# ARCHITECTURE.md

## Overview
This is a monorepo with three packages...

## Conventions
We use [patterns]...

## Key Files
- src/core/... handles...
- src/api/... handles...

Then reference in prompts:

@ARCHITECTURE.md Help me add a new feature following our patterns

Symbol-Based Context

Reference specific symbols rather than whole files:

@UserService @AuthMiddleware @validateToken
Update the auth flow to support refresh tokens

Git Context for Changes

@Git Show me what changed in the last 3 commits
Then help me write release notes

Summary

• Cursor builds context automatically from your files
• @ mentions add specific files, symbols, or search
• .cursorignore excludes files from indexing
• Context limits require selective inclusion
• Different features use different context scopes
• Indexing powers semantic search

Next Steps

Context tells AI what to see. Notepads let you maintain persistent reference information that persists across sessions—perfect for project documentation and shared knowledge.