Hybrid Retrieval
How CortexDB combines BM25, HNSW vectors, graph traversal, and cross-encoder reranking through Reciprocal Rank Fusion.
Hybrid retrieval queries multiple complementary indexes in parallel and fuses the results, so an agent's context is leveraged fully regardless of the query's shape. The full architecture is four channels fused with Reciprocal Rank Fusion (RRF).
Why single-channel retrieval falls short
Pure vector retrieval flattens identifiers (a query about a specific customer returns churn discussions instead of the literal record); pure lexical retrieval misses paraphrases. Agent queries never announce their shape in advance, so a single channel is limiting.
The four channels
- BM25 (Tantivy) — exact terms, identifiers, tokens (
SOC2survives lexically but smears in vectors). - HNSW vectors — conceptual similarity; captures paraphrases.
- Graph traversal — connected context across entities.
- Cross-encoder reranking — re-scores top candidates against the literal query (Cohere
rerank-v3.5).
RRF combines the ranked lists into one StratifiedPack — no per-channel weight tuning, and it tolerates channels with different score distributions.
Default vs configured (self-hosted)
A default self-hosted instance runs BM25 + HNSW vectors + RRF fusion only — verified via
diagnostics=full. The other two channels are opt-in:
- Graph traversal needs the knowledge graph (
CORTEX_ENTITY_GRAPH=1+ enrichment). - Cross-encoder reranking needs a Cohere
rerank-v3.5API key (CORTEX_RERANKER_PROVIDER=cohere).
On managed cloud the fuller stack is configured for you. The "4-channel" framing describes the full capability; see Self-hosting defaults to enable the rest.
What each channel contributes
For the query "what did Priya say about the SOC2 audit last week?":
| Channel | Hit | Why it matters |
|---|---|---|
| BM25 (Tantivy) | literal terms Priya, SOC2, audit | identifiers/acronyms survive lexically |
| HNSW vectors | "the compliance review with Priya last Tuesday" | captures paraphrases |
| Graph traversal | entity Priya → mentioned/owns → recent compliance episodes | connected context that mentions neither term |
| Cross-encoder rerank | re-scores top candidates | resolves close-but-wrong matches |
The temporal phrase "last week" is resolved by the bi-temporal layer before retrieval runs, clipping every channel to the correct validity window.
What it enables
- Comprehensive recall — identifiers and abstract concepts in the same prompt.
- Graceful degradation — BM25 + graph still contribute if the vector channel returns nothing useful.
- Strict boundaries — results are filtered across hierarchical scopes and respect bi-temporal validity.
How CortexDB compares
| System | Lexical | Vector | Entity graph | Reranking | Fusion |
|---|---|---|---|---|---|
| CortexDB | BM25 (Tantivy) | HNSW | Native traversal (opt-in) | Cross-encoder (Cohere, opt-in) | RRF |
| Mem0 | None | Single dense vector | None | None | N/A |
| Zep | Partial | Dense vector | Coupled to write path | None | Custom |
| Pinecone | None | Dense vector | None | None | N/A |
FAQ
What is Reciprocal Rank Fusion? A rank-aggregation method that combines ranked lists into one without per-channel score normalization.
Does hybrid retrieval block the write path? No — the retrieval indices are populated asynchronously from the event log.
See also
- The Five Memory Layers · Knowledge Graph
- Recall Tuning — the knobs behind these channels.