How Cursor Instantly Understands Massive Codebases

Dual‑Index Strategy

Cursor maintains two fundamentally different indexes. The semantic (vector) index supports natural‑language queries, while the trigram (inverted) index supports exact regular‑expression searches. The semantic index cannot answer literal pattern queries; the trigram index cannot answer conceptual queries. Cursor’s agent harness queries both simultaneously, which internal testing shows raises agent accuracy by an average of 12.5 % (range 6.5 %–23.5 %), improves code‑retention in large codebases by 2.6 %, and reduces unsatisfied follow‑up requests by 2.2 %.

Building the Semantic Index

AST‑driven chunking with Tree‑Sitter

When a project is opened, Cursor parses every file with tree‑sitter to produce an abstract syntax tree (AST). The AST is traversed and top‑level functions, classes, and methods become individual chunks. Small sibling nodes (e.g., imports, constants) are merged into the preceding chunk as long as the combined byte size stays below MAX_CHUNK_BYTES = 1500. The resulting list of chunk texts is then embedded.

import tree_sitter_python as tspython
from tree_sitter import Language, Parser

PY_LANGUAGE = Language(tspython.language())
parser = Parser(PY_LANGUAGE)
MAX_CHUNK_BYTES = 1500

def chunk_file(source_code: bytes) -> list[str]:
    tree = parser.parse(source_code)
    chunks = []
    for node in tree.root_node.children:
        if node.type in ("function_definition", "class_definition"):
            chunks.append(source_code[node.start_byte:node.end_byte].decode())
        else:
            if chunks and len(chunks[-1])
               + len(source_code[node.start_byte:node.end_byte])
               < MAX_CHUNK_BYTES:
                chunks[-1] += "
" + source_code[node.start_byte:node.end_byte].decode()
            else:
                chunks.append(source_code[node.start_byte:node.end_byte].decode())
    return chunks

Custom embedding model trained on agent trajectories

Instead of using a generic model such as text‑embedding‑ada‑002, Cursor trains its own embedding model. Training data consist of successful agent sessions: each session yields a sequence of file accesses and edits. An LLM ranks the most helpful content at each step, and the embedding model is optimized (contrastive learning) so that similarity scores align with those rankings. The resulting embeddings prioritize chunks that actually helped the agent, not merely syntactic similarity.

Turbopuffer vector store – one namespace per codebase

Embeddings are up‑serted into Turbopuffer, a serverless vector database that supports an unlimited number of namespaces. Each repository gets its own namespace, keyed by a hash of the repo path. Active namespaces stay in memory/NVMe; inactive ones are off‑loaded to object storage and lazily warmed on demand, reducing operational overhead and cutting storage cost by roughly 20×.

import turbopuffer

tpuf = turbopuffer.Turbopuffer(region="gcp-us-central1")
ns = tpuf.namespace(f"codebase-{repo_hash}")

ns.write(
    upsert_rows=[
        {"id": chunk.id,
         "vector": chunk.embedding,
         "file_path": chunk.path}
        for chunk in chunks
    ],
    distance_metric="cosine_distance",
    schema={"file_path":{"type":"string","glob":True}}
)

results = ns.query(
    rank_by=("vector","ANN",query_embedding),
    top_k=20,
    filters=("file_path","Glob","src/**/*.py"),
    include_attributes=["file_path"]
)

Merkle‑Tree Efficient Sync

Embedding computation is expensive, so re‑embedding the entire codebase on every change is infeasible. Cursor builds a Merkle tree where each file is hashed with SHA‑256; each directory hash is the SHA‑256 of its children’s hashes, mirroring Git’s content‑addressable model. When a client syncs, only branches whose hashes differ are traversed, and only the changed files are re‑chunked and re‑embedded.

import hashlib
from pathlib import Path
from dataclasses import dataclass

@dataclass
class MerkleNode:
    path: str
    hash: str
    children: list["MerkleNode"]
    is_file: bool

def hash_file(path: Path) -> str:
    return hashlib.sha256(path.read_bytes()).hexdigest()

def build_merkle_tree(root: Path) -> MerkleNode:
    if root.is_file():
        return MerkleNode(str(root), hash_file(root), [], True)
    children = [build_merkle_tree(p) for p in sorted(root.iterdir())]
    combined = "".join(c.hash for c in children)
    dir_hash = hashlib.sha256(combined.encode()).hexdigest()
    return MerkleNode(str(root), dir_hash, children, False)

def find_changed_files(client: MerkleNode, server: MerkleNode) -> list[str]:
    if client.hash == server.hash:
        return []
    if client.is_file:
        return [client.path]
    server_map = {c.path: c for c in server.children}
    changed =[]
    for c in client.children:
        if c.path not in server_map:
            changed.append(c.path)
        else:
            changed.extend(find_changed_files(c, server_map[c.path]))
    return changed

In a 50 k‑file workspace the Merkle metadata (filenames + hashes) occupies ~3.2 MB. Without the tree every sync would transfer the full set; with it only the mismatched branches are exchanged, typically a tiny fraction of files.

Reusing Teammates’ Indexes

Most engineers work on nearly identical clones of a monorepo (average clone similarity ≈ 92 %). When a new user opens a repository, Cursor computes a simhash of the repository’s content and searches existing namespaces for a close match. If the similarity exceeds a threshold, the server copies the nearest index via copy_from_namespace, reducing first‑query latency dramatically:

Median repo: 7.87 s → 525 ms

90th percentile: 2.82 min → 1.87 s

99th percentile: 4.03 h → 21 s

Security is enforced with Merkle‑tree‑based access proofs: the client uploads its full Merkle tree; the server stores only cryptographic proofs that the client possesses the hashed files. During a semantic query, results are filtered against these proofs, ensuring a user can retrieve only files it actually holds.

Trigram Index

For exact pattern matching Cursor uses a trigram inverted index originally described by Zobel, Moffat, and Sacks‑Davis (1993) and popularized by Russ Cox (2012). Each overlapping three‑character sequence in the codebase is indexed, allowing fast candidate reduction before running a full regex scan. Example: the regex db\.execute\( is broken into literal trigrams db., b.e, .ex, exe, xec, ecu, cut, ute, te(. The posting lists for these trigrams intersect to produce a tiny candidate set, which is then verified with the actual regex.

def extract_trigrams(text: str) -> set[str]:
    return {text[i:i+3] for i in range(len(text)-2)}

def build_trigram_index(files: dict[str,str]) -> dict[str,set[str]]:
    index ={}
    for file_id, content in files.items():
        for trigram in extract_trigrams(content):
            index.setdefault(trigram,set()).add(file_id)
    return index

To avoid large posting lists for common trigrams in monorepos, Cursor extends the basic trigram index with sparse n‑grams (deterministically selected variable‑length n‑grams) and attaches tiny bloom‑filter masks that encode character positions. This effectively upgrades a trigram key to a quadgram‑level filter, dramatically shrinking posting lists.

Dynamic Context Discovery

Cursor does not dump all retrieved chunks into the LLM prompt. Instead, each file is treated as a context unit. The agent receives file paths and decides, based on its current reasoning state, whether to read, tail, or grep the file. This on‑demand retrieval prevents prompt bloat. In A/B tests the approach reduced total token usage by 46.9 %.

End‑to‑End Indexing Pipeline

Project open: build a Merkle tree for the entire codebase.

Initial semantic index: AST‑driven chunking, custom embedding, upload to a Turbopuffer namespace.

Subsequent opens: compute simhash, locate a similar existing index, copy it via copy_from_namespace.

Background sync: diff Merkle trees, re‑embed only changed files, update the namespace asynchronously.

Local regex index: build a trigram/sparse‑n‑gram index on the current Git commit and keep it up‑to‑date with every edit.

Search: semantic queries go to Turbopuffer with Merkle‑proof access control; regex queries use the local index to filter candidates before running the actual regex.

Context delivery: retrieved files are provided as on‑demand resources rather than pre‑injected prompt text.

The novelty lies not in any single component—Merkle trees, trigram indexes, and vector stores have decades of history—but in their combination: using cryptographic hashes for both change detection and access control, training embeddings from agent trajectories instead of generic similarity, and treating files as the primary context unit throughout the system.