Skip to content

Semantic Search

Search your code by meaning, not exact text. Powers context retrieval in both Ask and Agent modes. Agent mode can call search_vector_db explicitly.

Related: Code indexing covers the indexer side; this page covers the query side.

Quick start

Section titled “Quick start”
CodeBuddy: Index Workspace for Semantic Search

Once indexed, both modes auto-retrieve relevant code. Files matching .codebuddyignore are excluded — run CodeBuddy: Init .codebuddyignore for a starter file.

Query pipeline

Section titled “Query pipeline”
graph TB Q["Query"] --> V["Vector search<br/>Pre-normalized query, cosine similarity<br/>Top candidates from up to 5000 rows"] Q --> K["FTS4 keyword search<br/>Tokenized query, BM25 via matchinfo"] V --> SF["Score fusion<br/>vector × 0.7 + text × 0.3"] K --> SF SF --> TD["Temporal decay (optional)<br/>score × e^(−λ × age)"] TD --> MMR["MMR diversity re-rank (optional)<br/>Jaccard similarity"] MMR --> TK["Top-K (default 10)"]

Fallback ladder — if hybrid fails or returns nothing:

  1. Hybrid (vector + FTS4)
  2. FTS4 keyword only
  3. Legacy vector (simpler cosine scan)
  4. Legacy keyword (basic text matching)
  5. Common files (README, package.json, entry points)

Embedding providers

Section titled “Embedding providers”
ProviderSetting valueModel / endpoint
Gemini (default)"gemini"text-embedding-004
OpenAI"openai"text-embedding-3-small
Local"local"/embeddings on local server (e.g. nomic-embed-text)

Set via codebuddy.vectorDb.embeddingModel. Local embedding needs a model that speaks the OpenAI embeddings API.

Perf notes

Section titled “Perf notes”
  • Pre-normalized query vectors + aligned Float32Array for fast cosine similarity.
  • Time-budgeted vector scans — yields every 8 ms to keep UI responsive.
  • Prepared statements — FTS4 uses cached prepared statements with reset() reuse.
  • Workspace switch safety — mid-scan workspace switch is detected and aborted cleanly.
  • Background reindex — file changes trigger re-index after the debounce delay via worker threads.

Settings

Section titled “Settings”

Full list in Settings Reference. Key knobs:

Vector DB:

SettingDefaultPurpose
codebuddy.vectorDb.enabledtrueMaster toggle
codebuddy.vectorDb.embeddingModel"gemini"gemini / openai / local
codebuddy.vectorDb.maxTokens6000Max tokens per chunk
codebuddy.vectorDb.searchResultLimit8Top-K for results
codebuddy.vectorDb.performanceMode"balanced"balanced / performance / memory
codebuddy.vectorDb.fallbackToKeywordSearchtrueKeyword fallback when vectors fail
codebuddy.vectorDb.cacheEnabledtrueCache search results

Hybrid search tuning:

SettingDefaultPurpose
codebuddy.hybridSearch.vectorWeight0.7Semantic weight (0–1)
codebuddy.hybridSearch.textWeight0.3Keyword weight (0–1)
codebuddy.hybridSearch.topK10Max results (1–50)
codebuddy.hybridSearch.mmr.enabledfalseDiversity re-ranking
codebuddy.hybridSearch.mmr.lambda0.70 = max diversity, 1 = max relevance
codebuddy.hybridSearch.temporalDecay.enabledfalseRecency bias
codebuddy.hybridSearch.temporalDecay.halfLifeDays30Score half-life (days, 1–365)

Weights auto-normalize to sum to 1.0.

Context integration

Section titled “Context integration”
  • Ask mode — ContextEnhancementService retrieves relevant chunks, adds them to the system prompt alongside @-mentions.
  • Agent mode — the LLM can call search_vector_db explicitly; the system prompt is also enriched with auto-retrieved context before reasoning starts.
Section titled “Related”