Semantic Search

semantic_search searches code by meaning and returns its constituent rankings directly. The vector and BM25 legs are function-oriented, using function-level chunks with enclosing class or file summary context. The co-edit leg is file-oriented. It searches code, not prose or markdown.

Semantic search is opt-in. Build Bifrost with the nlp feature:

cargo build --features nlp --bin bifrost

Then enable background indexing for the process:

BIFROST_SEMANTIC_INDEX=auto bifrost --root /path/to/project --mcp core

Without the nlp feature, the nlp toolset publishes no tools and core degrades to symbol|workspace. This example is intentionally scoped to symbol navigation plus semantic search and does not expose query_code. Add extended to the composition when the same agent also needs structural queries.

Index

The semantic index shares .brokk/bifrost_cache.db with the analyzer cache. Explicit-root processes place it at the primary repository root and therefore share it across linked worktrees. MCP sessions bound through client roots keep it under the exact approved root instead. Vectors and BM25 rows are keyed by content hash, so switching branches re-points rows instead of re-embedding unchanged content.

Once enabled, a background build starts when the workspace is activated. semantic_search waits until the index is ready, and the file watcher keeps it updated incrementally.

refresh forces a full rebuild of the code index. Normal tool calls already apply watcher-detected file changes automatically, so most hosts should not call refresh during routine operation.

Model and Runtime

Embeddings use voyageai/voyage-4-nano, downloaded from the Hugging Face hub on first use, and run in a PyTorch SDPA sidecar launched with:

uv run scripts/voyage_sidecar.py

Rust keeps the indexing pipeline and token counting in-process. The sidecar owns model forward passes and selects CUDA, Apple Metal, or CPU at runtime.

Environment

Variable	Description
BIFROST_SEMANTIC_INDEX=auto	Enables background indexing. The default is off.
BIFROST_EMBED_MODEL_DIR	Local directory containing config.json, tokenizer.json, and model.safetensors; takes precedence over the hub.
BIFROST_EMBED_MODEL_ID	Alternate Hugging Face repository id.
`BIFROST_ACCELERATOR=auto	cpu
`BIFROST_SIDECAR_DEVICES=<uuid	index,…>`

If BIFROST_SIDECAR_DEVICES is unset, Bifrost honors an existing CUDA_VISIBLE_DEVICES list. If that is also unset, it uses every GPU reported by nvidia-smi. If no CUDA GPU is visible, it launches one unpinned sidecar, which may use Metal or CPU.

BIFROST_ACCELERATOR is a Bifrost tool-availability gate, not a CUDA device binding.