@@ -416,6 +416,131 @@ export function createService({ store, mirror, config, onWrite, logger }) {
416416 }
417417 }
418418
419+ /**
420+ * Recall fusion (plan #1). Turns the three ranked signal lists (keyword,
421+ * vector, BM25) into a single merged list. Three recipes, selected by
422+ * config.recallFusion:
423+ * - blend (default): legacy behavior — weighted sum for vector/hybrid, union
424+ * backfill for auto. Byte-identical to pre-fusion code, so enabling the
425+ * config never regresses anybody.
426+ * - rrf: Reciprocal Rank Fusion — Σ 1/(k + rank + 1) over each list a row
427+ * appears in. Rank-based, so the unit mismatch (raw cosine vs keyword
428+ * score vs normalized IDF) is irrelevant.
429+ * - minmax: min-max normalize each source list's scores to [0,1] then take
430+ * the weighted sum — a scale-aware version of `blend`.
431+ * Returns { merged, signals }, where signals is Map<id, {keyword, vector,
432+ * bm25}> so searchMemories can decorate rows when signalTransparency is on.
433+ */
434+ function fuseRecall ( { keyword, vector, bm25, lim, mode, wv, wk, wb } ) {
435+ const recipe = config ?. recallFusion ?? "blend" ;
436+
437+ // Per-source scores are recorded for every recipe so signalTransparency
438+ // works regardless of how the ranking was produced.
439+ const signals = new Map ( ) ;
440+ const addSig = ( id , field , sc ) => {
441+ const cur = signals . get ( id ) ?? { } ;
442+ cur [ field ] = sc ;
443+ signals . set ( id , cur ) ;
444+ } ;
445+ for ( const m of keyword ) addSig ( m . id , "keyword" , m . score ?? 0 ) ;
446+ for ( const m of vector ) addSig ( m . id , "vector" , m . score ?? 0 ) ;
447+ for ( const m of bm25 ) addSig ( m . id , "bm25" , m . score ?? 0 ) ;
448+
449+ const vectorIds = new Set ( vector . map ( ( m ) => m . id ) ) ;
450+ const keywordIds = new Set ( keyword . map ( ( m ) => m . id ) ) ;
451+
452+ let merged ;
453+ if ( recipe === "rrf" ) {
454+ // Rank-based: only the position of a row inside each surviving source
455+ // list matters, so no cross-signal scale calibration is needed.
456+ const k = 60 ; // standard RRF constant (plan #1 documents k=60)
457+ const rows = new Map ( ) ;
458+ const addList = ( list ) => list . forEach ( ( m , idx ) => {
459+ const s = 1 / ( k + idx + 1 ) ;
460+ const cur = rows . get ( m . id ) ;
461+ if ( cur ) cur . score += s ;
462+ else rows . set ( m . id , { ...m , score : s } ) ;
463+ } ) ;
464+ addList ( keyword ) ;
465+ addList ( vector ) ;
466+ addList ( bm25 ) ;
467+ merged = [ ...rows . values ( ) ] . sort ( ( a , b ) => ( b . score ?? 0 ) - ( a . score ?? 0 ) ) . slice ( 0 , lim ) ;
468+ } else if ( recipe === "minmax" ) {
469+ // Scale-aware weighted sum: each source list is min-max normalized to
470+ // [0,1] before blending, so raw cosine and keyword score live on the
471+ // same footing.
472+ const norm = ( list ) => {
473+ if ( ! list . length ) return new Map ( ) ;
474+ let min = Infinity , max = - Infinity ;
475+ for ( const m of list ) { const s = m . score ?? 0 ; if ( s < min ) min = s ; if ( s > max ) max = s ; }
476+ const range = max - min ;
477+ const out = new Map ( ) ;
478+ for ( const m of list ) out . set ( m . id , range > 0 ? ( ( m . score ?? 0 ) - min ) / range : 0.5 ) ;
479+ return out ;
480+ } ;
481+ const kw = norm ( keyword ) , ve = norm ( vector ) , bm = norm ( bm25 ) ;
482+ const rows = new Map ( ) ;
483+ const seed = ( m ) => { if ( ! rows . has ( m . id ) ) rows . set ( m . id , { ...m , score : 0 } ) ; } ;
484+ for ( const m of keyword ) seed ( m ) ;
485+ for ( const m of vector ) seed ( m ) ;
486+ for ( const m of bm25 ) seed ( m ) ;
487+ for ( const [ id , row ] of rows ) {
488+ const k = kw . get ( id ) ?? 0 ;
489+ const v = ve . get ( id ) ?? 0 ;
490+ const b = bm . get ( id ) ?? 0 ;
491+ row . score = v * wv + k * wk + b * wb ;
492+ }
493+ merged = [ ...rows . values ( ) ] . sort ( ( a , b ) => ( b . score ?? 0 ) - ( a . score ?? 0 ) ) . slice ( 0 , lim ) ;
494+ } else {
495+ // blend — the pre-existing per-mode behavior, extracted verbatim.
496+ if ( mode === "keyword" ) {
497+ merged = keyword ;
498+ } else if ( mode === "vector" || mode === "hybrid" ) {
499+ const byId = new Map ( ) ;
500+ for ( const m of vector ) {
501+ const rec = byId . get ( m . id ) ;
502+ byId . set ( m . id , rec ? { ...rec , score : Math . max ( rec . score ?? 0 , m . score ?? 0 ) } : m ) ;
503+ }
504+ for ( const m of keyword ) {
505+ const rec = byId . get ( m . id ) ;
506+ if ( rec ) {
507+ byId . set ( m . id , { ...rec , score : ( rec . score ?? 0 ) * wv + ( m . score ?? 0 ) * wk } ) ;
508+ } else {
509+ byId . set ( m . id , m ) ;
510+ }
511+ }
512+ for ( const m of bm25 ) {
513+ const rec = byId . get ( m . id ) ;
514+ if ( rec ) {
515+ if ( keywordIds . has ( m . id ) ) continue ;
516+ byId . set ( m . id , { ...rec , score : ( rec . score ?? 0 ) + wb * ( m . score ?? 0 ) } ) ;
517+ } else {
518+ byId . set ( m . id , { ...m , score : wb * ( m . score ?? 0 ) } ) ;
519+ }
520+ }
521+ const ranked = [ ...byId . values ( ) ] . sort ( ( a , b ) => ( b . score ?? 0 ) - ( a . score ?? 0 ) ) ;
522+ merged = ranked . slice ( 0 , lim ) ;
523+ if ( merged . length < lim && ! merged . length ) {
524+ merged = keyword . slice ( 0 , lim ) ;
525+ }
526+ } else {
527+ // auto: keyword leads, vector + BM25 fill remaining slots.
528+ merged = keyword . slice ( 0 , lim ) ;
529+ const seen = new Set ( merged . map ( ( m ) => m . id ) ) ;
530+ for ( const m of vector ) {
531+ if ( merged . length >= lim ) break ;
532+ if ( ! seen . has ( m . id ) ) { seen . add ( m . id ) ; merged . push ( m ) ; }
533+ }
534+ for ( const m of bm25 ) {
535+ if ( merged . length >= lim ) break ;
536+ if ( ! seen . has ( m . id ) ) { seen . add ( m . id ) ; merged . push ( m ) ; }
537+ }
538+ }
539+ }
540+
541+ return { merged, signals } ;
542+ }
543+
419544 async function searchMemories ( query , options = { } ) {
420545 const { mode = "auto" , topK = 20 , threshold, useRerank = true , recordRecall = options . recordRecall ?? ( config ?. recallRecordDefault ?? true ) } = options ;
421546 const q = String ( query ?? "" ) . trim ( ) ;
@@ -477,69 +602,17 @@ export function createService({ store, mirror, config, onWrite, logger }) {
477602 // Loose blend weight: BM25 confirms and backfills, never dominates the
478603 // semantic signal. Same-memory overlap boosts, unseen ids backfill.
479604 const wb = 0.3 ;
480- // Path bookkeeping for the boost rule below: which ids each semantic
481- // recall path surfaced.
482- const vectorIds = new Set ( vector . map ( ( m ) => m . id ) ) ;
483- const keywordIds = new Set ( keyword . map ( ( m ) => m . id ) ) ;
484605
485606 // Hybrid blending weights from config when provided.
486607 const wv = config ?. hybridSearchVectorWeight ?? DEFAULT_HYBRID_WEIGHTS . vector ;
487608 const wk = config ?. hybridSearchKeywordWeight ?? DEFAULT_HYBRID_WEIGHTS . keyword ;
488609
489- let merged ;
490- if ( mode === "keyword" ) {
491- merged = keyword ;
492- } else if ( mode === "vector" || mode === "hybrid" ) {
493- // semantic-first: vector recalls lead, keyword + BM25 fill remaining
494- // slots. Weighted blend when sides scored the same memory; otherwise
495- // vector order leads (it is the semantic signal), lexical paths
496- // backfill.
497- const byId = new Map ( ) ;
498- for ( const m of vector ) {
499- const rec = byId . get ( m . id ) ;
500- byId . set ( m . id , rec ? { ...rec , score : Math . max ( rec . score ?? 0 , m . score ?? 0 ) } : m ) ;
501- }
502- for ( const m of keyword ) {
503- const rec = byId . get ( m . id ) ;
504- if ( rec ) {
505- // Same memory from both sides: blend the scores.
506- byId . set ( m . id , { ...rec , score : ( rec . score ?? 0 ) * wv + ( m . score ?? 0 ) * wk } ) ;
507- } else {
508- byId . set ( m . id , m ) ;
509- }
510- }
511- for ( const m of bm25 ) {
512- const rec = byId . get ( m . id ) ;
513- if ( rec ) {
514- // Boost rule: a row the LIKE keyword path already hit carries the
515- // query as a substring, so BM25 tokens are trivially present —
516- // boosting it double-counts lexical evidence. Only vector-recalled
517- // rows (lexical hit is genuinely new information) get the boost.
518- if ( keywordIds . has ( m . id ) ) continue ;
519- byId . set ( m . id , { ...rec , score : ( rec . score ?? 0 ) + wb * ( m . score ?? 0 ) } ) ;
520- } else {
521- byId . set ( m . id , { ...m , score : wb * ( m . score ?? 0 ) } ) ;
522- }
523- }
524- const ranked = [ ...byId . values ( ) ] . sort ( ( a , b ) => ( b . score ?? 0 ) - ( a . score ?? 0 ) ) ;
525- merged = ranked . slice ( 0 , lim ) ;
526- if ( merged . length < lim && ! merged . length ) {
527- // Vector unavailable entirely: fall back to plain keyword.
528- merged = keyword . slice ( 0 , lim ) ;
529- }
530- } else {
531- // auto: keyword leads, vector + BM25 fill remaining slots (legacy
532- // behavior, extended with the third path)
533- merged = keyword . slice ( 0 , lim ) ;
534- const seen = new Set ( merged . map ( ( m ) => m . id ) ) ;
535- for ( const m of vector ) {
536- if ( merged . length >= lim ) break ;
537- if ( ! seen . has ( m . id ) ) { seen . add ( m . id ) ; merged . push ( m ) ; }
538- }
539- for ( const m of bm25 ) {
540- if ( merged . length >= lim ) break ;
541- if ( ! seen . has ( m . id ) ) { seen . add ( m . id ) ; merged . push ( m ) ; }
542- }
610+ const { merged : fusedMerged , signals } = fuseRecall ( { keyword, vector, bm25, lim, mode, wv, wk, wb } ) ;
611+ let merged = fusedMerged ;
612+ // Signal transparency (#2): decorate each returned row with its per-source
613+ // scores and the final fused score. Purely additive — never changes rank.
614+ if ( config ?. signalTransparency === true ) {
615+ merged = merged . map ( ( m ) => ( { ...m , signals : { ...( signals . get ( m . id ) ?? { } ) , final : m . score ?? 0 } } ) ) ;
543616 }
544617
545618 // Search-time semantic dedup (v0.5.0 2.3): near-duplicate rows are
0 commit comments