Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
5.5 KB
Raw Blame
/**
 * Rank-fusion strategies for hybrid recall (Embedding Provider Suite).
 *
 * The default `linear` mode (a weighted sum of min-max-normalised BM25
 * and cosine, computed in `ranker.ts`) is unchanged. This module adds
 * `rrf` - Reciprocal Rank Fusion - which combines the sparse and dense
 * lanes by RANK POSITION rather than by score magnitude.
 *
 * RRF ignores the CONFIGURED lane weights (`search_keyword_weight` /
 * `search_semantic_weight`) on purpose: those calibrate two score
 * magnitudes against each other, and this fusion reads no magnitudes. It
 * does NOT ignore what the caller asked for. A per-query intent profile
 * (`query-plan.ts`, composed with the learned recall weights) states a
 * preference between the lanes themselves - a quoted phrase wants the
 * lexical lane - and that preference is applied to the per-lane
 * CONTRIBUTION, the standard weighted-RRF formulation:
 *
 *   rrf(chunk) = sum over lanes of w_lane / (k + rank_in_lane)
 *
 * so it stays rank-based and scale-free. `w_lane = 1` on every lane
 * reproduces the classic term exactly, which is what a query that
 * declared no intent gets.
 *
 * The raw RRF sums are min-max-normalised to [0, 1] so the fused relevance is
 * on the same scale as the linear path and composes with the same
 * downstream boosts (link / recency / entity / tier / session focus).
 */

import { SearchError } from "./search-error.ts";

/** Canonical RRF damping constant from the original Cormack et al. paper. */
export const DEFAULT_RRF_K = 60;

/** The weight of a lane the caller expressed no preference about. */
export const NEUTRAL_LANE_WEIGHT = 1;

/**
 * The relational fan-out arm is always neutral: the intent profile
 * describes a lexical-versus-semantic preference, and a typed-edge
 * traversal is neither, so there is no multiplier that would honestly
 * apply to it.
 */
const RELATIONAL_LANE_WEIGHT = NEUTRAL_LANE_WEIGHT;

/**
 * Per-lane multipliers for {@link rrfFuse}. Both default to
 * {@link NEUTRAL_LANE_WEIGHT}; both must be finite and strictly positive.
 */
export interface RrfLaneWeights {
  readonly keyword: number;
  readonly semantic: number;
}

/** The command that clears the learned half of a lane weight. */
const LEARNED_WEIGHTS_RESET_COMMAND = "o2b search weights --reset";

/**
 * A lane weight of zero would delete the lane and a negative one would
 * invert its rank order - in both cases the fusion silently answers a
 * question nobody asked. The bounded intent profiles cannot produce
 * either; a hand-edited learned-weights file can, so the refusal names
 * that file's reset command as the exit.
 */
function assertLaneWeight(weight: number, lane: keyof RrfLaneWeights): void {
  if (Number.isFinite(weight) && weight > 0) return;
  throw new SearchError(
    "INVALID_INPUT",
    `rrf fusion: the ${lane} lane weight must be a finite positive number, got ${weight}. ` +
      "A non-positive weight inverts the lane's rank order instead of down-weighting it. " +
      "The weight is the query intent profile composed with the learned recall weights; " +
      `clear the learned half with: ${LEARNED_WEIGHTS_RESET_COMMAND}`,
  );
}

export type FusionMode = "linear" | "rrf";

const FUSION_MODES: ReadonlySet<string> = new Set(["linear", "rrf"]);

export function isFusionMode(value: string): value is FusionMode {
  return FUSION_MODES.has(value);
}

/**
 * Fuse two lanes by reciprocal rank and min-max-normalise the result to
 * [0, 1]. Each input is the lane's chunk ids in best-first order; a chunk
 * contributes `w_lane / (k + position)` for each lane it appears in.
 * Returns a map from chunk id to its normalised fused relevance. An empty
 * input on both lanes yields an empty map.
 *
 * `laneWeights` is the per-query intent preference. Omitting it (or
 * passing {@link NEUTRAL_LANE_WEIGHT} on both lanes) yields the classic
 * weightless term, bit for bit.
 */
export function rrfFuse(opts: {
  keywordRankedChunkIds: ReadonlyArray<number>;
  semanticRankedChunkIds: ReadonlyArray<number>;
  /**
   * Optional relational arm (t_09b7ccea): chunk ids from typed-edge
   * fan-out, best-first. Absent or empty contributes nothing, so the
   * two-lane fusion is byte-identical when the relational arm is off.
   */
  relationalRankedChunkIds?: ReadonlyArray<number>;
  k: number;
  /** Per-lane intent multipliers; absent means neutral on both lanes. */
  laneWeights?: RrfLaneWeights;
}): Map<number, number> {
  const k = Math.max(1, opts.k);
  const keywordWeight = opts.laneWeights?.keyword ?? NEUTRAL_LANE_WEIGHT;
  const semanticWeight = opts.laneWeights?.semantic ?? NEUTRAL_LANE_WEIGHT;
  assertLaneWeight(keywordWeight, "keyword");
  assertLaneWeight(semanticWeight, "semantic");
  const raw = new Map<number, number>();
  const accumulate = (ids: ReadonlyArray<number>, weight: number): void => {
    for (let i = 0; i < ids.length; i++) {
      const id = ids[i]!;
      raw.set(id, (raw.get(id) ?? 0) + weight / (k + (i + 1)));
    }
  };
  accumulate(opts.keywordRankedChunkIds, keywordWeight);
  accumulate(opts.semanticRankedChunkIds, semanticWeight);
  if (opts.relationalRankedChunkIds) {
    accumulate(opts.relationalRankedChunkIds, RELATIONAL_LANE_WEIGHT);
  }

  if (raw.size === 0) return raw;

  const scores = [...raw.values()];
  const min = Math.min(...scores);
  const max = Math.max(...scores);
  const out = new Map<number, number>();
  if (max === min) {
    for (const id of raw.keys()) out.set(id, 1);
    return out;
  }
  for (const [id, score] of raw) {
    out.set(id, (score - min) / (max - min));
  }
  return out;
}