Context Mode
Read Context Mode search code: RRF fusion, reranking and the empty-result fallback
Follow the two lexical matchers, rank fusion key, bounded reranking and conditional fuzzy retry in ContentStore rather than assuming generic vector search.
What you will learn
- RRF adds position contributions from Porter and trigram lists.
- Proximity reranking operates after a bounded slice.
- Fuzzy retry occurs only when the initial filtered fusion is empty.
Before you start
- Basic JSON and MCP concepts
- An isolated test client and invented data
Explain the chapter’s actual implementation boundary and verify it with an explicit evidence fixture.
Key takeaways
- RRF adds position contributions from Porter and trigram lists.
- Proximity reranking operates after a bounded slice.
- Fuzzy retry occurs only when the initial filtered fusion is empty.
Two matchers feed a position-based score
ContentStore’s private rrfSearch method requests Porter and trigram results using OR mode. It chooses a candidate count of at least ten or twice the supplied limit. Each matcher contributes reciprocal rank with a constant of sixty: the first item contributes 1/61, the second 1/62. An item found by both lists accumulates contributions. This uses list position, not a calibrated probability of correctness.
The fusion map identifies an item by source and title joined together, not by a unique chunk row ID. That is a useful review question for documents containing repeated headings: inspect whether multiple chunks share that identity and how they appear after fusion. This article flags the key’s semantics; it does not assert a demonstrated data-loss bug or claim to have executed the full database pipeline.
The order of filtering and reranking matters
searchWithFallback refreshes stale file-backed sources before querying. With a session allow-set it requests a larger bounded candidate pool, applies the session filter, slices the surviving fused results to the requested limit and then applies proximity reranking. This order means proximity cannot promote a candidate that has already fallen outside that sliced set. Raising a candidate budget and changing a final limit are different experiments.
The reranker combines title matches, the tightest span containing the query terms and a capped phrase-frequency signal. It sorts by that boost first, then the existing rank. Code-shaped chunks receive a stronger title weight than prose-shaped chunks. Rather than calling all these values “BM25 scores,” record the match layer and use a fixture to observe which stage changed the order.
Fuzzy correction is conditional, not a second vote every time
When the filtered fused search has any results, the function returns them immediately with the rrf match layer. Only an empty result set reaches word correction and a second fused search. Successful correction is labeled rrf-fuzzy; otherwise the function returns an empty array. Therefore a weak initial match can prevent typo correction from being attempted. Test that case separately from a typo with no initial matches.
The small code example computes a position contribution only. It is an editorial arithmetic fixture, not a replacement for ContentStore or evidence that SQLite, stemming, token cleanup and permissions all work. To extend the investigation, inspect store-bytecap tests alongside retrieval tests: chunk size and boundaries can change the candidate universe before any ranking formula runs.
Implementation steps
- 1
Follow rrfSearch and its source/title map key.
- 2
Trace filter, slice and rerank in that order.
- 3
Compare a repeated-heading fixture with unique headings.
- 4
Test an empty typo query and a weak nonempty match separately.
Copy-ready example
// Editorial arithmetic fixture; not the upstream search runtime.
const contribution = position => 1 / (60 + position);
console.log(contribution(1));
console.log(contribution(2) + contribution(2));Frequently asked questions
Does a high RRF value mean the answer is correct?
No. It measures agreement between ranked lists, not factual correctness or confidence.
Will typo correction improve every weak result?
The reviewed path only retries with correction when the initial filtered fusion returns no results.
Sources
- README.mdSource checked 2026-09-07
- package.jsonSource checked 2026-09-07
- LICENSESource checked 2026-09-07
- src/store.tsSource checked 2026-09-07
- src/search/unified.tsSource checked 2026-09-07
- src/server.tsSource checked 2026-09-07
- src/executor.tsSource checked 2026-09-07
- src/security.tsSource checked 2026-09-07
- src/session/purge.tsSource checked 2026-09-07
- tests/store-bytecap.test.tsSource checked 2026-09-07