Hybrid semantic search: meaning + keywords, fused

The retrieval layer reads from the local hybrid index built during source indexing. From that index, two distinct paths emerge: a human-facing Search view tuned for ranked readable results, and a machine-facing retrieval path tuned to feed an LLM in Matrix and Evidence Scan.

1. 1

   Premium gate & validation

   The Search view requires Premium and at least a 2-character query.

2. 2

   Query embedding

   Your query is embedded once by the same Nomic model used at index time, with the "search_query: " prefix. One embedding per search, not one per source.

3. 3

   Candidate gathering

   The service pulls a wide candidate pool from each side of the index:

   • Semantic side — top-K nearest vectors (cosine distance) via sqlite-vec if available, or a brute-force scan if not.
   • Keyword side — BM25-ranked matches from the FTS5 table.

   The pool is over-fetched (typically 8× the requested limit, capped at 1,000) so the ranking step has enough material to work with.

4. 4

   Ranking & scoring

   Candidates are scored as a weighted sum:

   0.72 × semantic_score
   + 0.28 × keyword_score
   + 0.08    if the query appears verbatim in the chunk
   + 0.05    if the match is in a heading

   The first topResultCount slots (default 10) are filled unconditionally — you always see the strongest matches even if their scores are low. Additional slots are gated by the similarityThreshold preference (default 72%), so noisy long-tail matches do not pad the list.

5. 5

   Final results

   The Search view returns at most 120 results, sorted by composite score descending — tuned for human-readable relevance.

These two features use different code paths that bypass the project-wide Search view. Both pull from the same hybrid index, but with different scoping and fusion strategies.

RRF is the fusion formula used everywhere retrieval feeds an LLM:

score(chunk) = Σ   1 / (k + rank_in_list)

           with k = 60   (canonical default)

Each chunk's rank in the semantic list and the keyword list both contribute. The result: chunks that appear high in either list rank well, and chunks that appear in both are rewarded twice.

Why RRF instead of the weighted-sum scoring used by the Search view? RRF is rank-based, so it does not care about score-scale differences between cosine distance and BM25 — that makes it more robust when retrieval needs to feed an LLM (Matrix and Evidence Scan) rather than a human-readable list.

When both indexes return zero matches — e.g. a freshly added column with a vague prompt that does not match any chunk well — Matrix and Evidence Scan fall back to document-order chunks: typically the abstract, introduction, and first few sections. This means the AI always has something relevant to look at, which is better than failing the cell.