# Semantic index V3Code builds a searchable index of your codebase on your own hardware. It's what lets the agent find relevant code by *meaning*, not just exact text, and it's a big reason the agent seems to understand a project the moment you start typing. ## Reading comes first A quick philosophy note, because it shapes everything below: V3Code leans on the agent **reading real code** and uses the index for **fast recall when it's needed** — not as a replacement for reading. We've found models are more accurate when they read more and reach for the index to jump straight to the right place. They hit harder and miss less. The index makes that fast; it doesn't do the thinking. ## Local by default The index lives on your machine in a local **IndexedDB** store (database `v3code-index`), with embeddings kept as compact **int8-quantized vectors** (\~4× smaller than float32, scored directly with a per-vector scale). Your code is never uploaded to build or query it. See [Privacy](/account/privacy). ## Embeddings: a fast code model by default The embedding model is chosen by `v3code.semanticIndex.embedModel` (default `auto`): | Model | Dim | Engine | Notes | | -------------------------------- | ---- | -------------------------------------- | ------------------------------------------------------------------------------------ | | **`potion-code-16M`** (default) | 256 | Model2Vec **static** (no forward pass) | Tuned for code and used as the supported local default. | | `Qwen3-Embedding-0.6B` (quality) | 1024 | llama.cpp (GPU) | Optional higher-quality path when it is selected and local hardware has room for it. | Older local-embedding selections now resolve to the supported default instead of loading retired backends. If the current embedding model cannot load, V3Code keeps lexical search available rather than presenting vector search as ready. ## Why a small model is enough: structural enrichment A lightweight embedder would normally cost recall. V3Code buys it back with **structure**. Chunks are cut **structurally** with tree-sitter (parent/child code blocks, not blind line windows), and the code graph is upgraded with real **LSP-derived edges** (`v3code.semanticIndex.lspGraphEdges`, on by default, tightly budgeted). That structural signal — surrounding symbol, file, and relationships — sharpens recall and ranking, so the small, fast model punches above its size. ## How ranking works Retrieval is a **hybrid, RRF-fused** search, not a single vector lookup: - **Lexical channel** — IDF token overlap (weight 0.4). - **Dense vector channel** — int8 cosine over the embeddings (weight 0.6). - **Previous-model channel** — dual-space scoring during a model swap (0.5). - **Recency** — a multiplicative boost (up to \~1.25× for the most-recently-touched code). - **Graph neighbors** — one-hop expansion over the code graph after ranking. Channels are merged with Reciprocal Rank Fusion at **k = 30** (deliberately steeper than the classic 60), with adaptive widening when too few strong results come back. Child chunks collapse into their parent (top-3, decayed). An optional local **`Qwen3-Reranker-0.6B`** cross-encoder can reorder the top candidates. `semantic_search` returns up to `topK` results (default **30**). ## Staying current - **Builds on startup** (`autoRebuildOnStartup`, on by default) and follows edits. - **Incremental** via a content-hash (Merkle-style) manifest — only changed files are re-chunked and re-embedded — plus a content-addressed store so switching branches back to a known state is instant. - **Security denylist** — secrets-shaped files (`.env*`, `.ssh/`, `.aws/`, …) are never indexed, regardless of your include settings. ## 1.4.9-0098: background work with room to breathe This release corrects the cadence of background memory indexing. Once a bounded idle slice finishes, V3Code now waits before asking for another idle slot instead of treating an idle deadline as a waiting period. The change avoids needless repeated background work in an otherwise idle editor; it is a targeted scheduling fix, not a promise that every project will index at the same speed. ## More than one engine — one search V3Code doesn't lean on a single index. It runs a **layered retrieval system**, and all of it answers through one `semantic_search` call — you never think about which engine served a result. The fusion is adaptive: it leans on lexical signal when vectors are sparse and on vectors when they're strong. ### The local semantic index The engine described above — meaning-based recall, in your editor, on your hardware. It starts on the supported `potion-code-16M` default. The optional Qwen3 path is available when you select it and your local setup supports it. ### The native symbol sidecar Vectors are great at "what does this *mean*" and bad at "where is this *exactly*." So V3Code ships a second engine — a purpose-built **Rust sidecar** for precision: - **Trigram-indexed** (Tantivy) for instant substring and identifier search, with a recall → regex-confirm pass so matches are exact, not fuzzy. - **Symbol-aware** — tree-sitter parses every file into a symbol index of definitions and references across many languages. - **Cross-file resolved** — stack-graphs follow real **go-to-definition** and **find-references** edges, not text look-alikes, so "what uses this?" is answered by the actual call graph. - **Hot-swappable** — it runs as its own process (the ripgrep model): it can start, be killed, or restart mid-flight without ever breaking search. If it's not there, the system degrades gracefully. The payoff is symbol lookups and change-impact traces in **single-digit milliseconds**, riding alongside the semantic index's meaning-based recall. It's also what powers [graph-anchored memory](/editor/memory). ### The cloud index (opt-in, paid) An optional hosted index — **never required**. It exists so people on **low-end hardware**, or who want indexing to run against their own **BYOK** models, can offload the work. It's a per-workspace service with its own lexical, vector, and symbol-graph search. Local-hardware users never need it; and if your local index ever hits trouble, V3Code falls back to the cloud index **free** so search keeps working. **In short: local for your own hardware, cloud for low-end machines or BYOK-model indexing — your choice.** > Info: > > The indexing stack is actively evolving (deeper sidecar fusion and a cloud-model path are in progress). This page describes current default behavior.