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
/**
* Cross-encoder rerank stage - the final reader step
* (retrieval-precision-quality-loop, card A / t_110867f5).
*
* {@link applyCrossEncoderRerank} re-scores the top-K fused candidates
* jointly against the query using a learned cross-encoder, then re-orders
* that block by the returned relevance scores. It is appended AFTER the
* heuristic reranks (relevance rerank, entity boost, MMR, usage decay) in
* the reader tail, so it is the last word on ordering.
*
* Three invariants, mirroring the embedding-provider discipline:
* 1. Disabled (the default) -> the input is returned unchanged, with no
* HTTP call, no allocation of a new array, and no telemetry. The
* reader tail is byte-identical to the pre-feature baseline.
* 2. Enabled but unconfigured -> fail closed. Endpoint resolution
* (`resolveOpenAiCompatEndpoint`) throws a typed `SearchError`, the
* same discipline `openai-compat.ts` applies when semantic is
* enabled without a base_url/model/key. This is a configuration
* error the operator must fix, not a hot-path degrade.
* 3. Enabled and configured but the endpoint errors at request time ->
* degrade gracefully to the heuristic-ordered input (never throw
* into the hot path) and emit one fail-open telemetry event.
*/
import { resolveOpenAiCompatEndpoint } from "../embeddings/provider-resolve.ts";
import type { BrainSearchResult, ResolvedRerankConfig } from "../types.ts";
import { makeRerankProvider } from "./provider.ts";
import type { RerankProvider } from "./contract.ts";
import type { DecisionProvider } from "../../decision-model/contract.ts";
import type { DecisionRerankExtras } from "./decision-model.ts";
import {
RERANK_FAILURE_CATEGORY,
RerankEndpointError,
rerankCategoryForError,
type RerankFailureCategory,
} from "./failure.ts";
import { classifyRerankSunset, rerankSunsetHasPassed } from "./sunset.ts";
import type { EmbeddingSunsetSurvey } from "../embeddings/sunset.ts";
/** Fixed-precision so the reason string is stable for a given score. */
function fmtScore(x: number): string {
return x.toFixed(4);
}
interface RerankTelemetryBase {
/** Number of top candidates handed to the cross-encoder. */
readonly candidateCount: number;
}
/** The rerank re-ordered the top-K block. */
export interface RerankAppliedEvent extends RerankTelemetryBase {
readonly status: "applied";
}
/** The rerank request failed and the heuristic order was served. */
export interface RerankErrorEvent extends RerankTelemetryBase {
readonly status: "error";
/** Why, as a closed category computed from the typed failure. */
readonly category: RerankFailureCategory;
/** The provider-shaped failure message, for the operator-facing warning. */
readonly reason: string;
}
export type RerankTelemetryEvent = RerankAppliedEvent | RerankErrorEvent;
export interface ApplyCrossEncoderRerankOptions {
/** Inject a provider (tests / alternate backends). Defaults to the HTTP one. */
readonly provider?: RerankProvider;
/** Environment map for env-key resolution; defaults to `process.env`. */
readonly env?: Readonly<Record<string, string | undefined>>;
/** Per-request timeout override for the default provider. */
readonly timeoutMs?: number;
/**
* Fail-open telemetry sink. Invoked at most once per call - on success
* (`applied`) or on a request-time degrade (`error`). Never invoked on
* the disabled path. The caller wraps this so a throwing sink can never
* fail the search.
*/
readonly onTelemetry?: (event: RerankTelemetryEvent) => void;
/**
* Visibility tokens for a result path, or null when unresolvable. Used
* only by the `decision-model` kind, which never sends a candidate whose
* page is private or whose visibility cannot be resolved.
*/
readonly resolveVisibility?: (path: string) => ReadonlyArray<string> | null;
/**
* The `<private>` regions of a result's page, or null when the page
* cannot be read. `decision-model` kind only: a chunk that carries part
* of a region is never sent.
*/
readonly resolvePrivateRegions?: (path: string) => ReadonlyArray<string> | null;
/**
* Skip the `decision-model` kind for this call (the hook surfaces, which
* run under a tighter time budget than a decision request). The order is
* returned unchanged and `onDecisionFallback` fires.
*/
readonly skipDecisionModel?: boolean;
/**
* Called when the `decision-model` kind returned the heuristic order in
* place of the configured one (degraded, not active, or skipped).
*/
readonly onDecisionFallback?: () => void;
/** Inject a decision provider (tests). `decision-model` kind only. */
readonly decisionProvider?: DecisionProvider;
/** Receives the extra decision answers (e.g. `answerable`). */
readonly onDecisionExtras?: (extras: DecisionRerankExtras) => void;
/**
* Decision-model kind only: the `status` and `updated` frontmatter
* values of a result's page, sent beside its passage.
*/
readonly resolveMeta?: (path: string) => Readonly<Record<string, string>> | null;
/** The eval gate measures `enforce` whatever the configured mode. */
readonly decisionModeOverride?: "shadow" | "enforce";
/**
* The caller's cancellation (the composite hybrid deadline). An aborted
* call stops its provider request and rejects with the signal's reason
* instead of degrading, because nobody is waiting for the order.
*/
readonly signal?: AbortSignal;
/**
* `openai-compat` kind only: consult the rerank sunset survey for the
* configured model, and skip the request once its announced shutdown
* date has passed. Absent: the survey is not consulted (direct callers
* and tests that measure the endpoint they are pointed at).
*/
readonly sunset?: RerankSunsetOptions;
}
/**
* The sunset skip's inputs. The clock is the caller's own, so this stage
* reads no wall clock; the survey defaults to the shipped one.
*/
export interface RerankSunsetOptions {
readonly nowMs: number;
readonly survey?: EmbeddingSunsetSurvey;
/** Called once when the configured model is past its announced date. */
readonly onSkip: () => void;
}
interface Scored {
readonly result: BrainSearchResult;
readonly index: number;
readonly score: number;
}
/**
* Re-order the top-K block by cross-encoder score, honouring the
* `minScore` floor. Deterministic given the scores: qualifying candidates
* (score >= floor) sort by score descending, ties broken by original
* index; below-floor candidates keep their original relative order and
* sit below the qualifying ones. Each reranked hit gains a
* `cross_encoder:` reason so explainability shows the stage fired.
*/
function reorderTopK(
head: ReadonlyArray<BrainSearchResult>,
scores: ReadonlyArray<number>,
minScore: number,
): BrainSearchResult[] {
const scored: Scored[] = head.map((result, index) => ({
result,
index,
score: scores[index] ?? Number.NEGATIVE_INFINITY,
}));
const qualifying = scored.filter((s) => s.score >= minScore);
const belowFloor = scored.filter((s) => s.score < minScore);
qualifying.sort((a, b) => b.score - a.score || a.index - b.index);
return [...qualifying, ...belowFloor].map((s) =>
Object.freeze({
...s.result,
reasons: Object.freeze([...s.result.reasons, `cross_encoder: ${fmtScore(s.score)}`]),
}),
);
}
/**
* Apply the optional cross-encoder rerank stage. Returns the input
* unchanged when disabled or on a request-time endpoint error; throws a
* typed `SearchError` when enabled but the endpoint is unconfigured.
*/
export async function applyCrossEncoderRerank(
results: ReadonlyArray<BrainSearchResult>,
query: string,
config: ResolvedRerankConfig,
opts: ApplyCrossEncoderRerankOptions = {},
): Promise<ReadonlyArray<BrainSearchResult>> {
// Invariant 1: disabled -> zero-cost no-op, byte-identical input.
if (!config.enabled) return results;
// The decision-model kind owns its own fail-open and privacy rules and
// never emits rerank telemetry: a failed decision is recorded in the
// `decision_model_call` record and returns the heuristic order unchanged.
if (config.kind === "decision-model") {
if (opts.skipDecisionModel === true) {
opts.onDecisionFallback?.();
return results;
}
// eslint-disable-next-line @typescript-eslint/no-require-imports
const { applyDecisionModelRerank } =
require("./decision-model.ts") as typeof import("./decision-model.ts");
return applyDecisionModelRerank(results, query, config, {
...(opts.resolveVisibility !== undefined
? { resolveVisibility: opts.resolveVisibility }
: {}),
...(opts.resolvePrivateRegions !== undefined
? { resolvePrivateRegions: opts.resolvePrivateRegions }
: {}),
...(opts.onDecisionFallback !== undefined ? { onFallback: opts.onDecisionFallback } : {}),
...(opts.decisionProvider !== undefined ? { provider: opts.decisionProvider } : {}),
...(opts.env !== undefined ? { env: opts.env } : {}),
...(opts.onDecisionExtras !== undefined ? { onExtras: opts.onDecisionExtras } : {}),
...(opts.resolveMeta !== undefined ? { resolveMeta: opts.resolveMeta } : {}),
...(opts.decisionModeOverride !== undefined
? { modeOverride: opts.decisionModeOverride }
: {}),
...(opts.signal !== undefined ? { signal: opts.signal } : {}),
});
}
// Resolve the provider. The bundled offline reranker ("local") needs no
// endpoint - it is deterministic and network-free. The remote
// "openai-compat" path resolves fail-closed (Invariant 2): a misconfigured
// endpoint throws a typed SearchError (an operator error, not a hot-path
// degrade). An injected provider (tests) bypasses both.
let provider = opts.provider;
if (!provider) {
if (config.kind === "local") {
// eslint-disable-next-line @typescript-eslint/no-require-imports
const { LocalRerankProvider } = require("./local.ts") as typeof import("./local.ts");
provider = new LocalRerankProvider();
} else {
const endpoint = resolveOpenAiCompatEndpoint(
{
enabled: true,
baseUrl: config.baseUrl,
model: config.model,
envKey: config.envKey,
apiKey: config.apiKey,
env: opts.env,
...(config.allowInsecureHttp === true ? { allowInsecureHttp: true } : {}),
},
"search_rerank",
);
// resolveOpenAiCompatEndpoint only returns null when `enabled` is
// false, which we ruled out above; the narrowing keeps TS honest.
if (endpoint === null) return results;
provider = makeRerankProvider(endpoint, { timeoutMs: opts.timeoutMs });
}
}
if (results.length === 0) return results;
// A model past its announced shutdown can only refuse the request, so
// none is made. Only the remote kind keys on a model string a vendor
// can retire; `local` is this build's own reranker.
if (config.kind === "openai-compat" && opts.sunset !== undefined) {
const verdict = classifyRerankSunset(config.model, opts.sunset.nowMs, opts.sunset.survey);
if (rerankSunsetHasPassed(verdict)) {
opts.sunset.onSkip();
return results;
}
}
const topK = Math.min(Math.max(1, config.topK), results.length);
const head = results.slice(0, topK);
const tail = results.slice(topK);
const documents = head.map((r) => r.content);
let scores: number[];
try {
scores = await provider.rerank(
query,
documents,
opts.signal !== undefined ? { signal: opts.signal } : undefined,
);
if (scores.length !== documents.length) {
throw new RerankEndpointError(`expected ${documents.length} scores, got ${scores.length}`, {
category: RERANK_FAILURE_CATEGORY.malformed,
});
}
} catch (e) {
// A cancelled call is not an endpoint failure: no telemetry, and the
// caller's own abort reason travels up.
if (opts.signal?.aborted === true) throw opts.signal.reason;
// Invariant 3: request-time degrade. Return the heuristic ordering
// untouched and emit one fail-open telemetry event.
opts.onTelemetry?.({
status: "error",
category: rerankCategoryForError(e),
reason: e instanceof Error ? e.message : String(e),
candidateCount: topK,
});
return results;
}
const reordered = reorderTopK(head, scores, config.minScore);
opts.onTelemetry?.({ status: "applied", candidateCount: topK });
return [...reordered, ...tail];
}