Cursor Basics
Cursor Codebase Indexing: How the AI Understands Your Repository
Cursor indexes your codebase on your machine. Instant Grep builds a local search index that the agent uses to find exact matches, such as function names and error strings. Older guides describe embeddings stored on Cursor's servers, but Cursor's current docs say it stores no embeddings of your codebase for search.
On this page
What does codebase indexing do in Cursor?
Indexing gives the agent a fast way to find code by exact match. Instant Grep, Cursor's own search engine, builds and queries an index of your repo on your machine, and it needs no configuration. It finds exact matches such as a function name, a variable, an error string or a regex pattern. The agent uses it automatically when you reference a specific symbol.
Index ready — Exact Search, then @Codebase cites the file
0:40 · narratedRead this demo as text
- Open Cursor Settings, Indexing and Docs. Instant Grep is on — Cursor indexes this repo locally. There is no separate Resync percentage here; the toggle is the control.
- Exact Search for filterRecentSearches. Three hits in two files — the index is ready enough to grep.
- Attach Codebase, then ask where the helper lives. Semantic context rides with the question.
- The answer cites recentSearches.ts. Same model — the indexed codebase made the citation specific.
Practice next: Practice this yourself in the hands-on module.
Simulated Cursor 3.12 (macOS, light) — beta educational reconstruction, not the real product.
Instant Grep supports full regex and word-boundary matching, so the agent can build patterns that trace references across files. Cursor says it outperforms ripgrep on large codebases.
The agent can also find files by name and read directory structures, so it can reach code you didn't name. Exact search is still the fastest route when you know the name. If you know the function is called getSessionToken, type that name instead of describing it.
Earlier versions of Cursor uploaded your code to build an embedding index on Cursor's servers. Guides from that time, including earlier versions of this page, describe an 80% threshold before semantic search turned on, a five-minute sync and deletion after six weeks without use. Cursor's search docs now say it doesn't upload file paths or code to build a search index, and it doesn't store embeddings of your codebase for search.
This is covered hands-on in Cursor First Hour — 4 short Units, free to read.
Rather do it than read about it? Run 11 interactive Cursor walkthroughs in a simulated editor. Free, no account needed.
How does Cursor build and maintain the index?
You don't build or maintain the index yourself. Instant Grep runs automatically on your machine, and the Indexing and Docs section of Cursor Settings shows whether it is on.
Cursor's search docs don't say how often Instant Grep refreshes its index, how long it keeps an index you stop using, or whether it shows build progress. The sync interval, deletion window and progress threshold in older guides belonged to the server-side index.
Not every file is open to the agent. Cursor skips anything your ignore files match, plus everything on its default ignore list.
- Included
- Files in the folder you open, and in each folder of a multi-root workspace.
- Excluded
- Files matched by .gitignore or .cursorignoreA file listing paths Cursor must never index or read, kept separate from .gitignore. Press Enter for the full definition., plus Cursor's default ignore list: environment files, lock files, dependency folders, binaries, media and archives, among others.
- Override
- Start a line in .cursorignoreA file listing paths Cursor must never index or read, kept separate from .gitignore. Press Enter for the full definition. with ! to bring back a path the default list skips.
How does code from your repo get into a prompt?
On every turn, Cursor assembles the context the model sees. LLMs have no short-term memory, so Cursor summarizes everything discussed so far in the chat. It packages that summary with your new message and anything you attached with @. Code from the rest of the repo arrives when the agent searches for it and opens what it finds.
A field engineer's description of the mechanic: rather than appending every message and growing the pile, Cursor maintains one coherent storyline and refines it each turn. That keeps context utilization efficient instead of bloating the window with stale back-and-forth.
Every time you send a prompt, we're actually summarizing everything that's been discussed so far in that chat session. It's not just linearly additive. We're trying to clarify and refine and build this clear storyline.
Interactive diagram. Step through it with the Next and Previous controls below, or Tab to a region to read its detail.
Each prompt: summarize the conversation, package it with your message, then let the agent search for the code it needs.
The percentage Cursor shows is context utilization, measured in tokens. A token is a unit of volume for model input, the way a GB or MB is for files. Because Cursor re-summarizes instead of stacking every message, the same window holds more useful work before utilization climbs.
Searching through many files adds a lot of context. For a broad search, the agent can start a subagent that runs many searches in parallel, in its own context window and with a faster model. The subagent returns only the relevant findings, so raw file contents don't pile up in your main conversation. You can also ask for one yourself: "use a subagent to find all the places we validate user input."
Is my source code safe during indexing?
Indexing keeps your code on your machine. Instant Grep builds and queries its index locally, and Cursor doesn't upload file paths or code to build it.
- Data
- Search index
- Stored by Cursor?
- No
- What Cursor's docs say
- Built and queried on your machine, with no upload of code or file paths.
- Data
- Embeddings of your codebase
- Stored by Cursor?
- No
- What Cursor's docs say
- Not stored for search.
- Data
- Repos that cloud agents work on
- Stored by Cursor?
- Yes, while the agent runs
- What Cursor's docs say
- Encrypted copies, deleted after the agent completes.
| Data | Stored by Cursor? | What Cursor's docs say |
|---|---|---|
| Search index | No | Built and queried on your machine, with no upload of code or file paths. |
| Embeddings of your codebase | No | Not stored for search. |
| Repos that cloud agents work on | Yes, while the agent runs | Encrypted copies, deleted after the agent completes. |
Sources: Cursor's agent search docs, and its privacy and data governance docs
Code still leaves your machine when the agent works with it. Each file the agent opens can go into the model request, and Cursor sends prompts and code context to model providers. Cursor's privacy docs name cloud agents as the only feature that requires Cursor to store code.
On Enterprise, CMEK encrypts cloud agent data with a key you manage, and you control key rotation and access.
Cursor's blog post on secure codebase indexing describes the older server-side index. For a security review of Cursor today, read cursor.com/security and Cursor's privacy and data governance docs.
How do I control what gets indexed?
Cursor skips everything in .gitignore. To keep more files away from the agent without touching .gitignore, add a .cursorignore file at the project root. It uses the same syntax as .gitignore.
- node_modules/, dist/, build/
- node_modules/ is on Cursor's default ignore list. Build output is usually in
.gitignorealready. - Secrets or env files
- Cursor ignores .env files by default. Add other secrets, such as key files and credentials, to
.cursorignore. - Large generated files
- Add them to
.cursorignore. In large repos, Cursor recommends excluding irrelevant parts so the agent finds files more accurately. - Sensitive internal docs
- Add them to
.cursorignoreif you don't want the agent to read them.
.cursorignore does more than keep files out of search. Cursor blocks ignored files from the agent, from autocomplete and from @ mentions. Commands the agent runs in the terminal, and other tools that work outside Cursor's file access controls, may still read them. Cursor also says complete protection isn't guaranteed, because LLMs are unpredictable.
Think twice before you ignore a generated file that people read, such as an API client somebody opens every week. Once it is ignored, you can't hand it to the agent on purpose either.
On a team, put .cursorignore in the template every new repo starts from, so the rules don't depend on each person remembering them. For your own machine, Cursor also has a global ignore list in user settings, which applies to every project and starts empty.
To give a team a smaller slice of the codebase, start with the folder they open. Inside that folder, .cursorignore keeps files away from the agent, and a team rule can limit what the agent works against.
A Cursor support engineer's framing: you're fundamentally "just opening a folder". The experience is about what you populate in it. Cursor's own team pulls their website out into a sub-repository so people can iterate on it for documentation without dragging the whole product codebase along.
You could use a team rule if you wanted, or use .cursorignore to exclude certain things from being indexed.
When should I still add context manually with @?
When you already know which files matter, add them with @filename. The agent then starts from those files instead of searching for them, so the result doesn't depend on its search finding the same ones. If you're not sure which files matter, skip the mention and let the agent search.
- Situation
- You know the exact file to edit
- Best approach
- @filename (explicit is faster)
- Situation
- You want the agent to find related code across the repo
- Best approach
- Describe the task; let the agent search
- Situation
- Bug hunt across unfamiliar code
- Best approach
- Let the agent search first, then pin files with @ once found
- Situation
- Architecture question spanning many modules
- Best approach
- Describe the question; the agent can send a subagent to search widely
| Situation | Best approach |
|---|---|
| You know the exact file to edit | @filename (explicit is faster) |
| You want the agent to find related code across the repo | Describe the task; let the agent search |
| Bug hunt across unfamiliar code | Let the agent search first, then pin files with @ once found |
| Architecture question spanning many modules | Describe the question; the agent can send a subagent to search widely |
Use explicit @ context and the agent's own search together.
An @ mention can attach more than files. You can add folders, terminal output, a past chat, a git diff or context from Cursor's built-in browser.
For Cursor's own guidance on when to attach a file and when to skip the mention, see the @ mentions page.
Frequently asked questions
Can I check whether my codebase has finished indexing?
Cursor's search docs don't describe an indexing progress indicator. Instant Grep builds its index on your machine and runs automatically, and the Indexing and Docs section of Cursor Settings shows whether it is on.
Does Cursor store embeddings of my code?
Not for search. Cursor's search docs say Instant Grep builds and queries its index on your machine, and Cursor doesn't upload file paths or code to build a search index or store embeddings of your codebase for search. Guides that describe an embedding index on Cursor's servers are out of date.
Does codebase indexing work on private or air-gapped repositories?
Private repositories, yes. Instant Grep indexes them on your machine, and Cursor doesn't upload code to build the index. A fully air-gapped setup is different, because the agent sends prompts and code context to model providers. Cursor's docs don't describe an offline mode.
How does the index handle very large repositories?
Cursor says Instant Grep outperforms ripgrep on large codebases. In a large repo or monorepo, Cursor recommends excluding irrelevant parts with .cursorignore so the agent finds files more accurately.
Does .cursorignore stop the agent from reading a file?
Mostly. Cursor blocks ignored files from the agent, from autocomplete and from @ mentions. Commands run in the terminal, and other tools that work outside Cursor's file access controls, may still read them, and Cursor says complete protection isn't guaranteed.
Sources & last verified
- Cursor Help: Ignore files (redirected from the old indexing page)
- Cursor docs: Search (Instant Grep)
- Cursor blog: Securely indexing large codebases (describes the older server-side index)
- Cursor blog: Improving agent with semantic search (describes the older server-side index)
- Cursor docs: Ignore file
- Cursor docs: Privacy and data governance
- Cursor Help: @ mentions and context
- Cursor docs: Agent overview
Cursor ships frequently. Last updated October 28, 2026.