Skip to content

Code Search

code_search (basemind code search on the CLI) finds code by meaning, full-text term, or exact symbol match. Three lanes fuse results via Reciprocal Rank Fusion (RRF): vector (semantic), BM25 (keyword), and exact symbol. Optional cross-encoder reranking, set in basemind.toml, re-scores the fused results. Returns code pointers (path, line / end_line, symbol); read a hit with code_read.

--features code-search or --features full

RRF fusion of three lanes:

  1. Vector lane — KNN over embedded code chunks.
  2. BM25 lane — Okapi BM25 (k1=1.2, b=0.75) over symbol names, signatures, docs, and body text.
  3. Exact symbol lane — scope-aware identifier resolution against the symbol index, so query: "spawn" matches function definitions named spawn exactly.

Fusion is score-scale-agnostic, so it blends L2 distance, BM25 score, and symbol order without normalization. Degrades gracefully if a lane is unavailable (e.g., without embeddings).

{
"query": "retry a failed upload with backoff",
"lane": "hybrid",
"limit": 10
}

Each hit carries per-lane provenance: matched_lanes lists which of exact / vector / keyword matched, plus the 1-based rank in each contributing lane (exact_rank, vector_rank, keyword_rank). This lets you tell an exact-symbol match from a semantic neighbor or a cross-lane agreement without a second call.

Vector KNN alone — pure semantic search. No text matching, no symbol resolution. Useful when you want “code that means this” regardless of naming.

{
"query": "spawn background task",
"lane": "semantic",
"limit": 20
}

Requires embeddings to be enabled ([code_search] embed = true; the default is false, so this lane returns nothing until you opt in).

Native BM25 alone. No vectors, no symbol resolution. Works even with embeddings disabled. Full-text search over code.

{
"query": "spawn",
"lane": "keyword",
"limit": 50
}

code_search returns pointers: path, 1-based line / end_line and the enclosing symbol. Read the body with code_read on the hit’s span:

{
"path": "src/scanner.rs",
"line": 120,
"end_line": 160
}

The two-call pattern mirrors code_symbols then code_read: a cheap search returns pointers, then you read only what you need. The CLI also keeps basemind code chunk <path> --chunk-id <id>, which fetches one chunk body by id.

In basemind.toml:

[code_search]
embed = false # toggle embeddings (default: false; the keyword lane needs none)
embed_include = [] # when non-empty, embed only matching files (globs, repo-relative)
embed_exclude = [] # never embed these; still chunked + keyword-searchable (wins over embed_include)
[code_search.reranker]
enabled = true # cross-encoder reranking (default: false)
preset = "bge-reranker-base"
  • Use code_search for queries about what code does. “Find code that spawns a background task” → semantic search.
  • Use the keyword lane for term search. “Find the word spawn” → faster, no embeddings.
  • Use the hybrid lane when you want all signals. Symbol matches win for exact names, semantic search wins for meaning, BM25 wins for terminology.
  • Read with code_read only what you need. Search returns pointers; don’t waste tokens re-reading the whole file.
  • Enable the reranker if latency allows ([code_search.reranker] enabled = true). Cross-encoder reranking improves top-1 relevance but adds ~50–100 ms per query.

Code intelligence · Document search