---
topic: ai-technology
author: Crashtech Editorial
published: Nov 17, 2026 · read: 5 min
---

How Cursor Indexes Your Entire Codebase Without Ever Storing Your Code

Cursor's semantic search runs on embeddings, not source. The server never persists a line, and a Merkle tree keeps the index in sync as you type.

– –

“How does an AI tool understand my entire codebase” usually gets answered with “it sends your code to a server” — true for a single autocomplete request, but not the whole story for a tool that needs to reason about thousands of files without re-sending all of them on every keystroke. Cursor’s architecture is a genuinely careful answer to a harder question: how do you index a codebase’s meaning well enough to search it semantically, while keeping the actual source code off the server except for the specific instant it’s needed for a specific answer.

The core separation: what gets stored versus what gets fetched

Two representations of your code exist in this system, and they’re treated completely differently:

Embeddings — stored permanently the index
Fixed-length numerical vectors capturing a code chunk’s semantic meaning, computed once during indexing and stored in a vector database (Turbopuffer). Effectively one-way — a vector lets you compute similarity, not reconstruct the original text.
Source code — fetched on demand, never persisted the content
The actual text of your files. Sent to the server only when a specific, already-identified chunk is needed to answer a specific query, decrypted for that one operation, then discarded immediately.

This separation is what makes “search my entire codebase” and “don’t store my code” compatible requirements instead of contradictory ones — search happens entirely against the vector representation; source is a just-in-time fetch, not a standing copy.

The indexing pipeline, step by step

  1. Chunk and obfuscate locally

    On initial indexing, the client splits project files into smaller chunks — typically function-sized — and assigns each an obfuscated identifier. Even file names are not transmitted in plaintext; the server never learns your project’s file structure directly.

  2. Encrypt, transmit, embed, discard

    Each chunk is encrypted locally before it leaves the client. The server decrypts it, computes an embedding using a model built for this purpose, stores the resulting vector against the obfuscated ID — and discards the actual chunk content and any identifying metadata immediately afterward.

  3. Query time: search vectors, not text

    When a developer asks a question, the query itself is converted into an embedding, and a vector similarity search runs against the stored index — finding conceptually relevant code chunks by meaning, without the server needing to see any actual source at this stage.

  4. Fetch only what's actually needed

    If answering the question requires the real source of a matched chunk (not just knowing it’s relevant), the server requests that specific chunk — by its obfuscated ID — from the client. The client sends the corresponding code, encrypted; the server decrypts it for that single operation and discards it again once the response is generated.

What this design actually protects against

The architecture doesn’t claim the server can never see your code — it can, on demand, for a specific chunk, for a specific request. What it prevents is a standing, queryable, human-readable copy of your codebase sitting on a third-party server indefinitely. The blast radius of any single compromised request is one chunk, not the whole project.

Advertisement

Keeping the index honest as code changes: the Merkle tree

An index that goes stale the moment you edit a file is useless for a tool meant to understand your project in real time. Re-hashing and re-comparing every file on every sync would work, but it’s wasteful — cost scaling with total project size on every check, even when only one file changed.

A Merkle tree solves this specific problem. Each file’s content hashes into a leaf; leaves combine pairwise into parent hashes, up to a single root hash representing the entire project’s state:

                    root_hash
                   /          \
              hash(A,B)      hash(C,D)
              /      \        /      \
          hash(A)  hash(B) hash(C)  hash(D)
             |        |       |        |
          file A   file B  file C   file D

The client maintains a tree of its current file state; the server maintains its own tree of what it last indexed. Comparing the two root hashes tells you in one comparison whether anything changed. If something did, walking down through mismatched subtrees — rather than every leaf — pinpoints exactly which files diverged, in a number of comparisons proportional to what actually changed, not to total project size. Only those specific files get re-chunked, re-encrypted, and re-embedded; everything else is left untouched.

This is the same structural idea Merkle trees are used for elsewhere — git’s own object model, blockchain state verification — applied here to a much more mundane but equally real problem: keeping two parties’ view of a large, frequently-changing dataset in sync without constantly re-transmitting all of it.

Why the autocomplete path is architecturally simpler

Semantic search over the whole project needs the embedding-plus-on-demand-fetch machinery described above. The moment-to-moment autocomplete path — predicting what you’re about to type — doesn’t, because it only ever needs a small, local snippet of current context, not the whole project’s meaning.

That path is correspondingly simpler and faster: a small code snippet is encrypted locally, sent for one inference call, a completion comes back, and the snippet is never persisted server-side at all — no embedding, no vector storage, nothing kept beyond the single request-response cycle. Different problem, deliberately different (and lighter) architecture.

Do

Match the data-handling architecture to what each feature actually needs — a single-shot completion needs nothing stored; whole-project semantic search needs a persistent index, but that index can be built from vectors instead of raw content.

Don't

Default every feature to the same heavyweight indexing pipeline. Autocomplete doesn’t need vector storage or Merkle sync — building it that way would add latency and complexity solving a problem that specific feature doesn’t have.

Takeaway

The interesting engineering decision here isn’t “encrypt data in transit” — that’s table stakes. It’s the structural choice to make the server’s standing memory of your codebase be a set of one-way vectors instead of the code itself, and to treat any access to actual source as a deliberate, scoped, discard-after-use operation rather than a persistent cache. The Merkle tree is what makes that architecture viable at the speed a live coding tool needs — keeping two views of a large, constantly-changing project in sync by comparing hashes instead of re-transmitting content, so the privacy-preserving design doesn’t come at the cost of the index actually staying current.

Advertisement

Frequently asked questions

How can Cursor answer questions about an entire codebase without storing the code?

It doesn't search the code directly — it searches embeddings, numerical vectors that represent each code chunk's meaning. The server computes these vectors once during indexing, stores only the vectors (not the source), and discards the actual code and file names immediately after. A semantic search matches the query's embedding against stored vectors, and only if a specific matching chunk is actually needed does the server request that one piece of source from the client on demand.

If embeddings are stored instead of source code, can the original code be reconstructed from them?

Embedding functions are designed to be effectively one-way — they compress meaning into a fixed-length vector, discarding the specific tokens, syntax, and structure needed to reverse the process. A stored embedding lets you compute similarity to other embeddings; it doesn't hand back the source text that produced it, which is the property that makes storing embeddings instead of code a real privacy boundary rather than just an inconvenience for an attacker.

Why does Cursor use a Merkle tree to keep the index synchronized instead of just re-scanning changed files?

A Merkle tree lets the client and server each maintain a hash of their view of the project's file state, structured so that comparing two trees quickly identifies exactly which subset of files differ, without transmitting or hashing every file's full content on every check. This makes periodic sync cheap even on large codebases — the comparison cost scales with what actually changed, not with total project size.

What happens when the server needs the actual source code, not just its embedding?

The embedding is enough to find which chunk of code is relevant to a query, but not enough to answer a question about its contents. When the server determines a specific chunk (identified only by an obfuscated ID) is needed, it requests that chunk from the client, which sends the corresponding source over an encrypted channel. The server decrypts it for that one request and discards it again afterward — the code exists on the server only for the duration of that specific operation.

Why encrypt code locally before sending it, if the connection to the server is already secure?

Transport encryption (TLS) protects data in transit between client and server, but the server itself still receives and can act on the plaintext once it arrives. Encrypting locally, before transmission, means the specific application logic on the server is deliberately built to decrypt only what a given operation needs and discard it immediately — a stronger, architecture-level privacy commitment than relying on transport security alone.

/* Comments */