Cursor Codebase Indexing: How the AI Understands Your Repository

When you open a project, Cursor reads your files and converts them into vector embeddings using a custom embedding model. Those embeddings let the agent answer questions like "where do we handle authentication?" or "find all places that call this function" by meaning, not just by exact string match.

Semantic search shines when the relevant code isn't named the way you'd guess, which in a codebase with a few years on it is most of the time. Grep needs the exact string; the embedding index matches on meaning, so the agent can find the auth handler even if it's called gatekeeper.

None of that retires grep. Cursor's harness runs both, and grep is the half that wants an exact string. If you know the function is called getSessionToken, type that rather than describing it.

Indexing runs on its own once you open a workspace, and it keeps itself current as you work. Four points are worth knowing: when it starts, when search turns on, how it stays fresh, and when an idle index gets cleared.

1. 1You open a workspace, and Cursor begins indexing immediately.
2. 2Semantic search becomes available at 80% completion; a progress indicator appears in the status bar.
3. 3The index syncs automatically every 5 minutes, processing only changed files (not the whole repo each time).
4. 4If you haven't opened the project in 6 weeks, the hosted index is deleted; reopening triggers a fresh index.

You meet the 80% gate on day one. The five-minute sync shows up later, usually after a big checkout, when the index trails the working tree for a minute or two and questions about the files you just pulled come back thin.

The six-week deletion catches people months after they last thought about it. A repo nobody has opened since the summer comes back as a fresh index, so the first question you ask lands against something half-built. The instinct at that point is to change models, which does nothing for an index that is still being built. I would wait for the indexing indicator to report done before reading anything into a weak answer.

Not everything in the folder ends up in the index. Cursor follows your ignore files: anything matched by .gitignore or .cursorignore stays out, and so do binaries and files past the size limit. Here is what falls on each side.

Cursor has not put a number on that size limit anywhere I have looked, so read it as a reason to keep generated files out rather than a threshold to tune against.

The index is only half the story. The other half is how Cursor assembles context every time you hit send. LLMs have no short-term memory, so Cursor reminds the model of the conversation on each turn. Every prompt, it summarizes everything discussed so far in the chat and packages that summary with your new message, then pulls in the relevant code via the index.

That percentage you see is context utilization, measured in tokens. A token is just a unit of volume, like a GB or MB. It counts the raw amount of input a model can take. Because Cursor re-summarizes rather than stacks, you get more useful work out of the same window before utilization climbs.

Retrieval runs per prompt, which is more useful than it sounds. The query comes from what you typed, so rewording a question that came back empty can pull different code out of the same index. Cheap enough to try before you go hunting for the file yourself.

Cursor encrypts code chunks during indexing; source is held in memory briefly, then discarded. Filenames are obfuscated and code content is never stored in plaintext on Cursor's servers. What Cursor stores are encrypted embeddings (numeric vectors), which cannot be reversed into your original code.

The table describes the steady state. What decides whether it applies to a given file is the order you did things in: an embedding gets computed the first time Cursor sees a file, so an ignore rule only guarantees a path was never indexed if the rule was in place before that first open. Whether adding it later clears what was already stored is not something Cursor documents, and the only published figure is the six-week inactivity window.

A five-person team and a five-hundred-person one do not reach for the same control here. For the small team I would say .cursorignore plus a habit, and that is too weak as stated, because habits do not survive a new hire. Put the file in the template every repo starts from. On Enterprise, CMEK encrypts the embeddings with a key you hold, which covers who can decrypt what the index stored.

The index respects .gitignore automatically. To exclude additional files without adding them to .gitignore, create a .cursorignore file at the project root. It uses the same syntax as .gitignore.

• `node_modules/`, `dist/`, `build/`: typically already in .gitignore; excluded by default.
• Secrets or env files: add them to .cursorignore if not already in .gitignore.
• Large generated files: files above Cursor's size limit are excluded automatically; very large ones slow indexing.
• Sensitive internal docs: add to .cursorignore if you don't want them fed to the semantic search.

.cursorignore reaches further than the index, which the list above does not say. Cursor describes it as excluding files from semantic search, agent file reading and context selection. Build output can go there safely, and Cursor's own performance guidance says to put generated code and build artifacts there.

The file to weigh first is a generated API client somebody reads every week. Once it is ignored you cannot hand it to the agent on purpose either.

Don't confuse repo size with index control. A C++ program with thousands of source files isn't large by Cursor's standards; it handles very large monorepos performantly. A Cursor demo ran against Grafana, roughly 70K stars and about ten years old, and indexing behaved the way it does on a new project. That is one demo, though, and what it shows is that age and file count alone do not break indexing. How your own repo behaves depends on what is sitting in it.

If you want to hand a team a smaller subset of the codebase, that's a scoping decision, not an indexing one. Reach for .cursorignore to keep things out of the index, or a team rule to constrain what the agent works against.

The semantic index is automatic context the agent searches in the background. For tasks where you know exactly which files are relevant, adding them manually with @filename is faster than hoping the index surfaces the same ones, and in my experience more reliable.

A file you created in the last minute may not have synced into the index yet, and until it does the mention is the only route to it. That is the case where the speed argument stops being the point.

The rest of the when-to-attach question is answered on the @ mentions page, which carries Cursor's own guidance on when to skip the mention.