Search & Reciprocal Rank Fusion (RRF)
Relevant source files
The following files were used as context for generating this wiki page:
Reciprocal Rank Fusion (RRF) is a key architectural component in RAGAPPv3 used to combine search results from multiple disparate sources or search algorithms into a single, unified ranked list. This "hybrid search" approach typically merges dense vector retrieval (semantic search) with traditional Full-Text Search (FTS5) to improve retrieval recall and precision.
The system utilizes RRF across several boundaries, including multi-query variants (Step-back, HyDE), multi-scale chunk indexing, and the fusion of document search with user memories. By leveraging RRF, the project ensures that the most relevant information surfaces to the LLM, regardless of whether it was found through keyword matching or semantic similarity.
Sources: backend/app/config.py:126-130, Plan.md:129-142, specs/kms-content-search-rag/SPEC.md:46-56
Architecture & Data Flow
The search architecture follows a multi-stage pipeline where raw queries are transformed, executed against various indices, and then fused using RRF parameters.
This diagram illustrates how the system processes a query through parallel search paths before applying RRF fusion and final reranking.
Sources: backend/app/config.py:166-180, Plan.md:143-160
Hybrid Search & RRF Parameters
The RRF algorithm relies on the k parameter (constant) to control the influence of individual result ranks. A lower k sharper top-list preference, while a higher k smooths the distribution. RAGAPPv3 provides granular control over this constant for different retrieval scenarios.
Configuration Tuning
The following table summarizes the key RRF tuning parameters available in the system configuration:
| Parameter | Type | Default | Description |
|---|---|---|---|
hybrid_rrf_k | int | 60 | RRF k for per-arm dense/FTS fusion. |
multi_query_rrf_k | int | 60 | RRF k for cross-variant fusion (Original + Stepback + HyDE). |
multi_scale_rrf_k | int | 60 | RRF k for multi-scale fusion across different chunk sizes. |
memory_rrf_k | int | 60 | RRF k for memory hybrid retrieval (FTS + Dense). |
rrf_weight_original | float | 1.0 | Weight for the original query arm in fusion. |
rrf_weight_stepback | float | 0.5 | Weight for the step-back variant arm. |
rrf_weight_hyde | float | 0.5 | Weight for the HyDE (Hypothetical Document) arm. |
Sources: backend/app/config.py:126-150, Plan.md:195-212
Search Components
1. Vector Search (Dense)
Utilizes LanceDB to perform semantic similarity searches. The system calculates distance (typically cosine) between query embeddings and document embeddings.
- Metric: Cosine similarity is preferred.
- Logic: Distance is converted to similarity (
1 - distance) or used directly with amax_distance_threshold.
Sources: backend/app/config.py:64-70, Plan.md:65-85
2. Full-Text Search (Sparse)
Uses SQLite FTS5 virtual tables to index metadata and document content. This ensures keyword-heavy queries (e.g., part numbers, specific acronyms) are captured even if semantic similarity is low.
- FTS Tables:
files_search_fts(metadata) andfiles_content_fts(parsed text). - Triggers: Automated triggers keep FTS indices in sync with the primary
filesandmemoriestables.
Sources: backend/app/models/database.py:53-76, specs/kms-content-search-rag/SPEC.md:46-56
3. Memory Retrieval
Hybrid retrieval specifically for user "memories." It combines dense vector search with FTS5 keyword matching via RRF to surface durable user context.
- Relevance Gate: Applies thresholds like
memory_dense_min_similarity(default 0.30) andmemory_rrf_min_score(default 0.005) to filter weak candidates.
Sources: backend/app/config.py:136-146, specs/fix-chat-overlap-memory-interop/SPEC.md:46-56
Implementation Details
RRF Calculation Logic
The RRF score for a document $d$ is calculated by summing the inverse ranks across all search result sets $R$:
$Score(d) = \sum_{r \in R} \frac{weight_r}{k + rank_r(d)}$
The system also includes an exact_match_promote safeguard. If enabled, it promotes the top-1 dense result from the original query into the top-5 fused results to prevent fusion math from demoting highly specific semantic matches.
Sources: backend/app/config.py:166-175, Plan.md:131-142
Multi-Scale & Multi-Query Fusion
RRF is applied horizontally across transformed queries:
- Original Query: The raw user input.
- Step-back Query: A broader, more general version of the query to improve recall.
- HyDE: A hypothetical answer passage generated by an LLM to align embeddings with the answer space rather than the question space.
Sources: backend/app/config.py:180-195, Plan.md:143-160
Conclusion
Reciprocal Rank Fusion acts as the mathematical backbone of the RAGAPPv3 search engine. By abstracting the differences between vector distances and keyword BM25 scores into a rank-based fusion, the system achieves a robust hybrid search capability. This ensures that the RAG pipeline remains effective across diverse document types and query styles, from specific technical keyword searches to broad conceptual inquiries.