How the Top-Rank Bonus in QMD Fusion Preserves Exact Matches

The top-rank bonus adds fixed score increments (+0.05 for #1, +0.02 for #2–3) to documents that achieve top positions in any source list, ensuring high-precision exact matches aren't drowned out by documents with marginal support across multiple lists.

QMD (Query Markdown) uses Reciprocal Rank Fusion (RRF) to merge ranked results from multiple search strategies, such as BM25 and vector search. The top-rank bonus in QMD fusion is a precision-focused enhancement that prevents exact matches from being buried by documents that appear in many lists but never at the top.

Understanding Reciprocal Rank Fusion in QMD

Standard RRF calculates a document’s fusion score by summing weight / (k + rank + 1) across every list where it appears. While this effectively surfaces documents with broad support, it creates a vulnerability: a document ranked first in one high-precision list (like an exact BM25 match) can be overtaken by a document ranked third or fourth in several other lists.

The raw RRF score alone doesn't distinguish between a confident #1 ranking and a mediocre #4 ranking when the latter appears repeatedly.

How the Top-Rank Bonus Works

QMD addresses this by injecting a post-processing step that detects and rewards documents achieving top-tier ranks in any individual source list.

Detecting Best Ranks

During the initial fusion pass in src/store.ts (lines 2285–2307), QMD tracks the best rank (topRank) achieved by each document across all input lists. This metadata is stored alongside the accumulating RRF score, creating a record of whether a document ever reached the top positions in any single list.

Applying Fixed Score Boosts

After all RRF contributions are summed, a second loop (lines 2309–2316) applies the bonus:

// src/store.ts – lines 2309-2316
for (const entry of scores.values()) {
  if (entry.topRank === 0) {
    entry.rrfScore += 0.05;      // +0.05 for #1 in any list
  } else if (entry.topRank <= 2) {
    entry.rrfScore += 0.02;      // +0.02 for #2-3 in any list
  }
}

This fixed increment is deliberately calibrated to outweigh the marginal gains a document receives from appearing at lower ranks in multiple lists.

Why This Preserves Exact Matches

The bonus ensures precision-first behavior by altering the score calculus in favor of confident single-source matches.

A document ranked #1 in a BM25 list receives a base RRF contribution of approximately 1.0 / (60 + 0 + 1) ≈ 0.016 (assuming default k=60). Without the bonus, a document ranked #4 in three different lists could accumulate 3 × (1.0 / 64) ≈ 0.047, overtaking the exact match.

The +0.05 top-rank bonus adds a buffer that ensures the #1 document maintains its lead, preserving the exact match's visibility in the final fused ranking.

Practical Implementation Example

The unit test "RRF adds top-rank bonus" in test/store.test.ts (lines 1920–1932) demonstrates this behavior in practice:

import { reciprocalRankFusion } from "./src/store";

// Two simple result lists
const listA = [
  { file: "exact.md", score: 0.9 },   // exact match, rank 0
  { file: "near.md",  score: 0.8 },   // rank 1
];
const listB = [
  { file: "other.md", score: 0.85 }, // appears only here
];

// Fuse without any weight adjustments
const fused = reciprocalRankFusion([listA, listB]);

// Inspect the final scores
console.log(fused.map(r => `${r.file}: ${r.score.toFixed(3)}`));
/*
  exact.md: 0.567   // gets +0.05 bonus for top rank
  other.md: 0.542
  near.md:  0.542   // gets +0.02 bonus for rank 1-2
*/

Without the bonus logic, exact.md and near.md would have significantly lower scores, potentially allowing documents with broad but shallow support to outrank the precise match.

Summary

• Reciprocal Rank Fusion merges multiple ranked lists by summing weighted reciprocal ranks, but raw scores can allow frequent mid-tier documents to outrank rare top-tier matches.
• Top-rank bonus in QMD adds +0.05 to documents ranked #1 in any list and +0.02 to those ranked #2–3, implemented in src/store.ts lines 2309–2316.
• Precision preservation occurs because the fixed bonus outweighs the marginal gains from appearing at lower ranks in multiple lists, ensuring exact matches identified by high-confidence methods remain visible.
• Validation is provided by unit tests in test/store.test.ts that verify the bonus correctly elevates top-ranked documents in fused results.

Frequently Asked Questions

What is the exact bonus amount for top-ranked documents in QMD?

Documents that achieve rank #1 in any source list receive a +0.05 bonus to their final RRF score. Documents ranked #2 or #3 receive a smaller +0.02 bonus. These values are hardcoded constants in the fusion logic at src/store.ts lines 2311–2315.

How does the top-rank bonus differ from standard RRF?

Standard Reciprocal Rank Fusion calculates scores purely from the formula weight / (k + rank + 1), which treats all ranks as relative positions without special consideration for the top spot. The top-rank bonus is a post-processing enhancement that adds a fixed score increment to documents achieving elite positions, explicitly prioritizing precision over the pure democratic aggregation of standard RRF.

Can I disable the top-rank bonus in QMD?

The current implementation in src/store.ts applies the bonus unconditionally during the reciprocalRankFusion function execution. There is no configuration flag exposed to disable this behavior without modifying the source code. To remove the bonus, you would need to comment out or remove the loop at lines 2309–2316 in src/store.ts.

Which source files contain the top-rank bonus implementation?

The core logic resides in src/store.ts between lines 2285–2322, which includes both the rank tracking during score accumulation (lines 2285–2307) and the bonus application (lines 2309–2316). The behavior is validated by unit tests in test/store.test.ts around lines 1920–1932, which explicitly test that the bonus correctly elevates top-ranked documents in the fused output.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}