Skip to content

Commit 39d11f5

Browse files
committed
fix(retrieval): honor mode contract in rrf/minmax + searchMemories docs
CodeRabbit flagged that opt-in fusion recipes could change keyword-only behavior. Verified: rrf/minmax ignored mode entirely, so a mode=keyword request would pull vector/BM25 rows in. Align both recipes with blend: - mode=keyword short-circuits to keyword-only (byte-for-byte mirror of the blend branch), so no recipe ever bleeds vector/BM25 into the text-only path. - mode=auto re-applies keyword-leads ordering for rrf/minmax, preserving the pre-fusion auto contract (keyword first, recipe fills the slots). Also adds a JSDoc for searchMemories and a regression test asserting mode=keyword stays keyword-only across all three recipes. Default remains blend=legacy; zero behavior change for existing users.
1 parent 5c2d76b commit 39d11f5

3 files changed

Lines changed: 98 additions & 0 deletions

File tree

‎dsh-mneme/lib/service.js‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -449,6 +449,14 @@ export function createService({ store, mirror, config, onWrite, logger }) {
449449
const vectorIds = new Set(vector.map((m) => m.id));
450450
const keywordIds = new Set(keyword.map((m) => m.id));
451451

452+
// Mode contract (aligns rrf/minmax with blend): keyword-only searches must
453+
// stay keyword-only regardless of recipe, so enabling an opt-in recipe can
454+
// never pull vector/BM25 rows into a mode="keyword" request. This mirrors
455+
// the blend branch's `mode === "keyword"` short-circuit (byte-for-byte).
456+
if (mode === "keyword") {
457+
return { merged: keyword.slice(0, lim), signals };
458+
}
459+
452460
let merged;
453461
if (recipe === "rrf") {
454462
// Rank-based: only the position of a row inside each surviving source
@@ -538,9 +546,41 @@ export function createService({ store, mirror, config, onWrite, logger }) {
538546
}
539547
}
540548

549+
// Mode contract, auto (aligns rrf/minmax with blend): keyword leads, the
550+
// recipe fills the remaining slots. blend.auto already front-loads keyword;
551+
// rrf/minmax rank across sources, so re-apply the same "keyword first"
552+
// ordering here to preserve the pre-fusion auto contract — the keyword
553+
// hit list keeps its power, and only slots it couldn't fill go to the
554+
// recipe's ranking.
555+
if (recipe !== "blend" && mode === "auto" && keyword.length) {
556+
const head = keyword.slice(0, lim);
557+
const seen = new Set(head.map((m) => m.id));
558+
const tail = merged.filter((m) => !seen.has(m.id)).slice(0, Math.max(0, lim - head.length));
559+
merged = head.concat(tail);
560+
}
561+
541562
return { merged, signals };
542563
}
543564

565+
/**
566+
* Search memories for a query. Merges up to three recall sources (keyword,
567+
* vector, BM25) according to config.recallFusion (blend/rrf/minmax — see
568+
* fuseRecall), then optionally decorates rows with per-source signals
569+
* (config.signalTransparency), applies semantic dedup (non-keyword modes),
570+
* reranking, and epistemic trust re-weighting, and finally hands the merged
571+
* list to the recall-layer recorder.
572+
*
573+
* options:
574+
* mode — 'auto' (default) | 'keyword' | 'vector' | 'hybrid'
575+
* topK — max rows (default 20)
576+
* threshold — explicit vector score floor (overrides adaptive)
577+
* useRerank — apply the reranker if available (default true)
578+
* recordRecall — write a recall_runs audit row (default from config)
579+
*
580+
* Returns an array of memory rows { id, title, content, score, source, ... },
581+
* with `signals` added when config.signalTransparency is on. Never throws:
582+
* a vector/rerank failure degrades to keyword results.
583+
*/
544584
async function searchMemories(query, options = {}) {
545585
const { mode = "auto", topK = 20, threshold, useRerank = true, recordRecall = options.recordRecall ?? (config?.recallRecordDefault ?? true) } = options;
546586
const q = String(query ?? "").trim();

‎dsh-mneme/src/service.js‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -449,6 +449,14 @@ export function createService({ store, mirror, config, onWrite, logger }) {
449449
const vectorIds = new Set(vector.map((m) => m.id));
450450
const keywordIds = new Set(keyword.map((m) => m.id));
451451

452+
// Mode contract (aligns rrf/minmax with blend): keyword-only searches must
453+
// stay keyword-only regardless of recipe, so enabling an opt-in recipe can
454+
// never pull vector/BM25 rows into a mode="keyword" request. This mirrors
455+
// the blend branch's `mode === "keyword"` short-circuit (byte-for-byte).
456+
if (mode === "keyword") {
457+
return { merged: keyword.slice(0, lim), signals };
458+
}
459+
452460
let merged;
453461
if (recipe === "rrf") {
454462
// Rank-based: only the position of a row inside each surviving source
@@ -538,9 +546,41 @@ export function createService({ store, mirror, config, onWrite, logger }) {
538546
}
539547
}
540548

549+
// Mode contract, auto (aligns rrf/minmax with blend): keyword leads, the
550+
// recipe fills the remaining slots. blend.auto already front-loads keyword;
551+
// rrf/minmax rank across sources, so re-apply the same "keyword first"
552+
// ordering here to preserve the pre-fusion auto contract — the keyword
553+
// hit list keeps its power, and only slots it couldn't fill go to the
554+
// recipe's ranking.
555+
if (recipe !== "blend" && mode === "auto" && keyword.length) {
556+
const head = keyword.slice(0, lim);
557+
const seen = new Set(head.map((m) => m.id));
558+
const tail = merged.filter((m) => !seen.has(m.id)).slice(0, Math.max(0, lim - head.length));
559+
merged = head.concat(tail);
560+
}
561+
541562
return { merged, signals };
542563
}
543564

565+
/**
566+
* Search memories for a query. Merges up to three recall sources (keyword,
567+
* vector, BM25) according to config.recallFusion (blend/rrf/minmax — see
568+
* fuseRecall), then optionally decorates rows with per-source signals
569+
* (config.signalTransparency), applies semantic dedup (non-keyword modes),
570+
* reranking, and epistemic trust re-weighting, and finally hands the merged
571+
* list to the recall-layer recorder.
572+
*
573+
* options:
574+
* mode — 'auto' (default) | 'keyword' | 'vector' | 'hybrid'
575+
* topK — max rows (default 20)
576+
* threshold — explicit vector score floor (overrides adaptive)
577+
* useRerank — apply the reranker if available (default true)
578+
* recordRecall — write a recall_runs audit row (default from config)
579+
*
580+
* Returns an array of memory rows { id, title, content, score, source, ... },
581+
* with `signals` added when config.signalTransparency is on. Never throws:
582+
* a vector/rerank failure degrades to keyword results.
583+
*/
544584
async function searchMemories(query, options = {}) {
545585
const { mode = "auto", topK = 20, threshold, useRerank = true, recordRecall = options.recordRecall ?? (config?.recallRecordDefault ?? true) } = options;
546586
const q = String(query ?? "").trim();

‎dsh-mneme/test/benchmark.test.js‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,3 +74,21 @@ test("recallFusion recipes produce distinct fused scores for the same memory", a
7474
// so they must not all collapse onto the same numeric score.
7575
assert.ok(new Set(Object.values(scores)).size > 1, `recipes score differently: ${JSON.stringify(scores)}`);
7676
});
77+
78+
// PR1 + CodeRabbit: an opt-in recipe must never change keyword-only behavior.
79+
// mode="keyword" is the documented text-only path; regardless of recipe, the
80+
// result must contain only keyword-sourced rows — no vector/BM25 bleed-in.
81+
// (Note: on a scattered-CJK query the keyword source can itself be empty, in
82+
// which case auto correctly falls back to BM25 — that is the pre-fusion blend
83+
// behavior and is NOT a regression. Only mode="keyword" is a hard text path.)
84+
test("opt-in recipes keep mode=keyword keyword-only (no vector/BM25 bleed)", async () => {
85+
for (const recipe of ["blend", "rrf", "minmax"]) {
86+
const svc = seedService({ recallFusion: recipe });
87+
const rows = await svc.searchMemories("rust 异步", { mode: "keyword", topK: 5, useRerank: false });
88+
const keywordOnly = rows.every((r) => r.source === "keyword");
89+
assert.ok(
90+
keywordOnly,
91+
`${recipe} under mode=keyword must keep only keyword rows; got sources: ${[...new Set(rows.map((r) => r.source))].join(",")}`
92+
);
93+
}
94+
});

0 commit comments

Comments
 (0)