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
/**
 * Kernel 1 - the deterministic retrieval rank-adjustment sink
 * (t_5f61130a).
 *
 * One stage between ranking and result emission where registered
 * adjusters return a verdict per candidate:
 *   - `keep`     - no change,
 *   - `multiply` - scale the candidate's score by a bounded factor and
 *                  append an explainability reason,
 *   - `exclude`  - drop the candidate from the pool and record it (with
 *                  reasons) so it is counted, never silently dropped.
 *
 * The sink is a pure function: callers (search.ts) build the adjuster
 * list per query and hand in the already-ranked pool. It is mounted on
 * BOTH the semantic and the pure-lexical paths because both flow through
 * the same ranked pool before the final slice.
 *
 * Byte-identical opt-out is the load-bearing invariant: with no adjuster
 * registered - and when every adjuster only ever returns `keep` or a
 * neutral `multiply(1)` - the exact input array is returned unchanged
 * (same reference, same objects), so a vault that engages no adjuster
 * ranks bit-identically to pre-kernel behaviour.
 *
 * Language-agnostic by construction: an adjuster's verdict carries a
 * structural reason token it chooses, never a natural-language word list.
 */

import { clamp01 } from "../math.ts";
import type { BrainSearchResult } from "./search-result.ts";

/** A per-candidate verdict returned by a {@link RankAdjuster}. */
export type RankAdjustVerdict =
  | { readonly kind: "keep" }
  | { readonly kind: "multiply"; readonly factor: number; readonly reason: string }
  | { readonly kind: "exclude"; readonly reason: string };

/** Keep the candidate unchanged. */
export function keepVerdict(): RankAdjustVerdict {
  return KEEP;
}
const KEEP: RankAdjustVerdict = Object.freeze({ kind: "keep" });

/** Scale the candidate's score by `factor`, tagging it with `reason`. */
export function multiplyVerdict(factor: number, reason: string): RankAdjustVerdict {
  return Object.freeze({ kind: "multiply", factor, reason });
}

/** Drop the candidate from the pool, recording `reason`. */
export function excludeVerdict(reason: string): RankAdjustVerdict {
  return Object.freeze({ kind: "exclude", reason });
}

/**
 * One registered adjuster. `name` namespaces the reasons it emits so a
 * receipt can attribute an exclusion / fade to the adjuster that caused
 * it. `adjust` is pure over the single candidate it is handed.
 */
export interface RankAdjuster {
  readonly name: string;
  adjust(result: BrainSearchResult): RankAdjustVerdict;
}

/** A candidate the sink removed, with the namespaced reasons why. */
export interface RankAdjustExclusion {
  readonly documentId: number;
  readonly chunkId: number;
  readonly path: string;
  readonly reasons: ReadonlyArray<string>;
}

/** The sink's output: surviving results plus the recorded exclusions. */
export interface RankAdjustOutcome {
  readonly results: ReadonlyArray<BrainSearchResult>;
  readonly excluded: ReadonlyArray<RankAdjustExclusion>;
}

const EMPTY_EXCLUSIONS: ReadonlyArray<RankAdjustExclusion> = Object.freeze([]);

/**
 * Apply every registered adjuster to every candidate.
 *
 * For each candidate the sink collects verdicts from all adjusters:
 * any `exclude` removes the candidate (its reasons, from every adjuster
 * that excluded, are recorded), otherwise the `multiply` factors compose
 * as a product and the reasons are appended. Survivors are re-sorted by
 * the ranker's tie-break family only when a score actually moved or a
 * candidate was excluded; when nothing changes the input array is
 * returned unchanged.
 */
export function applyRankAdjusters(
  ranked: ReadonlyArray<BrainSearchResult>,
  adjusters: ReadonlyArray<RankAdjuster>,
): RankAdjustOutcome {
  if (adjusters.length === 0) return { results: ranked, excluded: EMPTY_EXCLUSIONS };

  const survivors: BrainSearchResult[] = [];
  const excluded: RankAdjustExclusion[] = [];
  let changed = false;

  for (const candidate of ranked) {
    const excludeReasons: string[] = [];
    const multiplyReasons: string[] = [];
    let factor = 1;
    for (const adjuster of adjusters) {
      const verdict = adjuster.adjust(candidate);
      if (verdict.kind === "exclude") {
        excludeReasons.push(`${adjuster.name}:${verdict.reason}`);
      } else if (verdict.kind === "multiply" && verdict.factor !== 1) {
        factor *= verdict.factor;
        multiplyReasons.push(`${adjuster.name}:${verdict.reason}`);
      }
    }

    if (excludeReasons.length > 0) {
      changed = true;
      excluded.push(
        Object.freeze({
          documentId: candidate.documentId,
          chunkId: candidate.chunkId,
          path: candidate.path,
          reasons: Object.freeze(excludeReasons),
        }),
      );
      continue;
    }

    if (factor === 1) {
      survivors.push(candidate);
      continue;
    }

    changed = true;
    survivors.push(
      Object.freeze({
        ...candidate,
        score: clamp01(candidate.score * factor),
        reasons: Object.freeze([...candidate.reasons, ...multiplyReasons]),
      }),
    );
  }

  if (!changed) return { results: ranked, excluded: EMPTY_EXCLUSIONS };

  // Same tie-break family as the ranker and the relation-polarity phase:
  // score desc, keywordScore desc, chunkId asc - deterministic for equal
  // scores.
  survivors.sort((a, b) => {
    if (b.score !== a.score) return b.score - a.score;
    if (b.keywordScore !== a.keywordScore) return b.keywordScore - a.keywordScore;
    return a.chunkId - b.chunkId;
  });

  return { results: survivors, excluded: Object.freeze(excluded) };
}