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
hybrid (default)
Section titled “hybrid (default)”RRF fusion of three lanes:
- Vector lane — KNN over embedded code chunks.
- BM25 lane — Okapi BM25 (
k1=1.2,b=0.75) over symbol names, signatures, docs, and body text. - Exact symbol lane — scope-aware identifier resolution against the symbol index,
so
query: "spawn"matches function definitions namedspawnexactly.
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.
semantic
Section titled “semantic”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).
keyword
Section titled “keyword”Native BM25 alone. No vectors, no symbol resolution. Works even with embeddings disabled. Full-text search over code.
{ "query": "spawn", "lane": "keyword", "limit": 50}Reading results
Section titled “Reading results”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.
Configuration
Section titled “Configuration”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"Discipline
Section titled “Discipline”- Use
code_searchfor queries about what code does. “Find code that spawns a background task” → semantic search. - Use the
keywordlane for term search. “Find the wordspawn” → faster, no embeddings. - Use the
hybridlane when you want all signals. Symbol matches win for exact names, semantic search wins for meaning, BM25 wins for terminology. - Read with
code_readonly 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.