Cursor Codebase Indexing

Set up and optimize Cursor's codebase indexing system. Indexing creates embeddings of your code, enabling

@Codebase

How Indexing Works

Your Code Files
      │
      ▼
  Syntax Chunking ─── splits files into meaningful code blocks
      │
      ▼
  Embedding Generation ─── converts chunks to vector representations
      │
      ▼
  Vector Storage (Turbopuffer) ─── cloud-hosted nearest-neighbor search
      │
      ▼
  @Codebase Query ─── your question → embedding → similarity search → relevant chunks

Key Architecture Details

• Merkle tree for change detection: only modified files are re-indexed (every 10 minutes)
• No plaintext storage: code is not stored server-side; only embeddings and obfuscated metadata
• Privacy Mode compatible: with Privacy Mode on, embeddings are computed without retaining source code
• Indexing runs in the background; small projects complete in seconds, large projects (50K+ files) may take hours initially

Initial Setup

1. Open your project in Cursor
2. Indexing starts automatically on first open
3. Check status: look at the bottom status bar for "Indexing..." indicator
4. View indexed files:

   Cursor Settings

   >

   Features

   >

   Codebase Indexing

   >

   View included files

Verify Indexing Status

The status bar shows:

• "Indexing..." with progress indicator -- initial indexing in progress
• "Indexed" -- indexing complete,

  @Codebase

  queries are available
• No indicator -- indexing may be disabled or not started

Configuration

.cursorignore

Exclude files from indexing and AI features. Place in project root. Uses

.gitignore

# .cursorignore

# Build artifacts (large, not useful for AI context)
dist/
build/
out/
.next/
target/

# Dependencies
node_modules/
vendor/
venv/
.venv/

# Generated files
*.min.js
*.min.css
*.bundle.js
*.map
*.lock

# Large data files
*.csv
*.sql
*.sqlite
*.parquet
fixtures/
seed-data/

# Secrets (defense in depth -- also use .gitignore)
.env*
**/secrets/
**/credentials/

.cursorindexingignore

Exclude files from indexing only but keep them accessible to AI features when explicitly referenced:

# .cursorindexingignore

# Large test fixtures -- don't index, but allow @Files reference
tests/fixtures/
e2e/recordings/

# Documentation build output
docs/.vitepress/dist/

Difference:

.cursorignore

.cursorindexingignore

@Files

Default Exclusions

Cursor automatically excludes everything in

.gitignore

.cursorignore

Using the Index

@Codebase Queries

Ask semantic questions about your entire codebase:

@Codebase where is user authentication handled?

@Codebase show me all API endpoints that accept file uploads

@Codebase how does the payment processing flow work?

@Codebase find all places where we connect to Redis

@Codebase

@Codebase vs @Files vs Text Search

@Codebase

@Files

@Folders

Ctrl+Shift+F

Use

@Codebase

@Files

Optimization for Large Projects

Monorepo Strategy

For monorepos with many packages, open the specific package directory instead of the root:

# Instead of opening the entire monorepo:
cursor /path/to/monorepo           # Indexes everything -- slow

# Open the specific package:
cursor /path/to/monorepo/packages/api   # Indexes only this package -- fast

Or use

.cursorignore

# .cursorignore -- monorepo, focus on api and shared
packages/web/
packages/mobile/
packages/admin/
# packages/api/    ← not listed, so it IS indexed
# packages/shared/ ← not listed, so it IS indexed

Re-Indexing

If search results are stale or indexing appears stuck:

1. Cmd+Shift+P

   >

   Cursor: Resync Index

2. Wait for status bar to show indexing progress
3. If that fails, delete the local cache:
   • macOS:

     ~/Library/Application Support/Cursor/Cache/

   • Linux:

     ~/.config/Cursor/Cache/

   • Windows:

     %APPDATA%\Cursor\Cache\

4. Restart Cursor and allow full re-index

File Watcher Limits (Linux)

On Linux, large projects may hit the file watcher limit:

# Check current limit
cat /proc/sys/fs/inotify/max_user_watches

# Increase (temporary)
sudo sysctl fs.inotify.max_user_watches=524288

# Increase (permanent)
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Enterprise Considerations

• Data residency: Embeddings are stored in Turbopuffer (cloud). Obfuscated filenames and no plaintext code, but metadata exists
• Privacy Mode: With Privacy Mode on, embeddings are computed with zero data retention at the provider
• Air-gapped environments: Indexing requires network access to Cursor's embedding API. Not available offline
• Indexing scope: Only files in the currently open workspace are indexed. Closing a project removes its index from active queries

Troubleshooting

Resources

• Codebase Indexing Docs
• Ignore Files
• Secure Codebase Indexing