Package com.tnsai.memory.advanced

Class HybridMemoryRetriever

java.lang.Object

com.tnsai.memory.advanced.HybridMemoryRetriever

public final class HybridMemoryRetriever
extends Object

Combines BM25 text search and vector semantic search via Reciprocal Rank Fusion.

For each query, both the BM25 index and the vector store are searched independently. The two ranked result lists are then fused using RRF to produce a single ranked list that balances lexical and semantic relevance. Raw RRF scores are normalized against the number of non-empty result streams so callers can apply a stable 0.0..1.0 relevance threshold.

Constructor Summary

Constructors

Constructor	Description
HybridMemoryRetriever(BM25Index bm25Index, VectorMemoryStore vectorStore)	Creates a hybrid retriever with default RRF (k=60).
HybridMemoryRetriever(BM25Index bm25Index, VectorMemoryStore vectorStore, ReciprocalRankFusion rrf)	Creates a hybrid retriever with a custom RRF combiner.

Method Summary

Modifier and Type	Method	Description
int	candidateCount()	Returns an upper bound on the number of distinct entries this retriever can return without overflowing its internal candidate multiplier.
List<ScoredEntry>	search(String query, int topK)	Searches using both BM25 and vector search, then fuses results via RRF.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

HybridMemoryRetriever

public HybridMemoryRetriever(BM25Index bm25Index,
 VectorMemoryStore vectorStore)

Creates a hybrid retriever with default RRF (k=60).

Parameters:

bm25Index - the BM25 text search index

vectorStore - the vector semantic search store

HybridMemoryRetriever

public HybridMemoryRetriever(BM25Index bm25Index,
 VectorMemoryStore vectorStore,
 ReciprocalRankFusion rrf)

Creates a hybrid retriever with a custom RRF combiner.

Parameters:

bm25Index - the BM25 text search index

vectorStore - the vector semantic search store

rrf - the RRF combiner to use

Method Details

search

public List<ScoredEntry> search(String query,
 int topK)

Searches using both BM25 and vector search, then fuses results via RRF.

Each search retrieves up to candidateMultiplier * topK candidates before fusion to ensure sufficient diversity.

The returned score is normalized to 0.0..1.0. An entry ranked first in every non-empty stream scores 1.0; empty streams are not counted in the normalization ceiling.

Parameters:

query - the search query

topK - maximum number of final results

Returns:

fused results sorted by descending normalized RRF score

candidateCount

public int candidateCount()

Returns an upper bound on the number of distinct entries this retriever can return without overflowing its internal candidate multiplier.

Entries may exist in both backing stores, so the value can exceed the number of distinct entry IDs.

Returns:

a safe upper bound on available retrieval candidates