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
/**
* Pure ranking function. Combines normalised BM25, cosine semantic
* similarity, link-graph boost, and recency boost into the final score.
*
* Anchored in docs/plans/2026-05-16-brain-search-design.md §7.
*
* The ranker imports no I/O modules. Callers (search.ts) gather the
* inputs from the store and pass them in. This makes it trivially
* testable and substitutable.
*
* Freshness is measured from the authoring instant the document declares
* (`documents.authored_at`) when that instant is usable, falling back to
* the filesystem mtime the indexer recorded. Any indexed note can populate
* that column - the indexer reads the frontmatter key off every markdown
* file - so the fallback is not a niche path, and "usable" is enforced here
* rather than assumed. See {@link freshnessAnchorSeconds} and
* `authored-at.ts`.
*/
import { clamp01 } from "../math.ts";
import { PAGE_TIER_DEFAULT, tierWeight, type PageTier } from "../brain/page-meta/tier.ts";
import { usableAuthoredAtSeconds } from "./authored-at.ts";
import { weibullDecay, DEFAULT_RECENCY, type WeibullRecencyOptions } from "./recency.ts";
import { scoreSessionFocusTarget } from "./session-focus.ts";
import { rrfFuse, DEFAULT_RRF_K, type FusionMode } from "./fusion.ts";
import { temporalProximity, DEFAULT_WINDOW_PAD_DAYS } from "./temporal-bridge.ts";
import type { TemporalIntent } from "./temporal-intent.ts";
import type { KeywordHit, SemanticHit, HydratedChunk } from "./store.ts";
import type {
BrainSearchResult,
ScoreBreakdown,
SearchSessionFocus,
WeightProfile,
} from "./types.ts";
export interface RankerInputs {
readonly keyword: ReadonlyArray<KeywordHit>;
readonly semantic: ReadonlyArray<SemanticHit>;
readonly hydrated: ReadonlyMap<number, HydratedChunk>;
/** For each chunkId: set of OTHER document ids linking to its document. */
readonly inboundLinkSources: ReadonlyMap<number, ReadonlySet<number>>;
/** For each chunkId: the tag set of its document. */
readonly tagsByDoc: ReadonlyMap<number, ReadonlySet<string>>;
/**
* Optional importance tier per documentId. Missing entries (and
* the absent map entirely) resolve to `supporting`, whose tier
* weight is `1.0` - so a vault without any tier tags ranks
* bit-identically to pre-tier behaviour.
*/
readonly tierByDoc?: ReadonlyMap<number, PageTier>;
/**
* Optional per-chunk count of query entities the chunk also carries
* (v0.13.0). Missing entries (and the absent map) contribute zero
* boost, so the entity layer adds nothing until the index is
* populated by a reindex.
*/
readonly entityMatchByChunk?: ReadonlyMap<number, number>;
/**
* Optional per-chunk count of DERIVED person-variant forms the chunk
* also carries (write-honesty-egress-consent, F3): forms the query
* expansion DERIVED (first-initial-plus-surname, reversed word order,
* operator nicknames) rather than forms the registry declares. Kept
* in a lane of its own so a declared-form match always outranks a
* derived-variant match between otherwise-equal candidates: per-match
* 0.01, capped at 0.02 - each strictly below the declared lane above.
* Missing entries (and the absent map) leave the layer unwired: no
* reason entry, no breakdown key, byte-identical scores. Never a
* retrieval mechanism - the candidate set arrives fixed and this lane
* only reorders it.
*/
readonly derivedEntityMatchByChunk?: ReadonlyMap<number, number>;
/**
* Optional per-chunk effective activation in [0, 1] (Time-Aware
* Recall & Activation Suite): access-reinforced strength already
* decayed by the content-type half-life. Missing entries (and the
* absent map) contribute zero boost, so a vault without recorded
* accesses ranks bit-identically to pre-activation behaviour.
*/
readonly activationByChunk?: ReadonlyMap<number, number>;
/**
* Optional co-access companions per chunk (t_c5ef25a3): for each
* chunkId, the OTHER document ids habitually co-retrieved with its
* document, with the recorded pair count. Only companions that are
* also in the current candidate pool contribute (the same
* pool-membership rule the link boost uses), so the boost re-ranks a
* working set without floating unrelated documents.
*/
readonly coAccessByChunk?: ReadonlyMap<number, ReadonlyMap<number, number>>;
/**
* Optional freshness trend per documentId (t_ee09a6ce), read from
* the `freshness_trend` frontmatter the dream refresh stamps on
* preference pages. Maps to a bounded multiplier on the relevance
* portion (strengthening 1.05, weakening 0.93, stale 0.85); absent
* entries (and the absent map) stay neutral.
*/
readonly trendByDoc?: ReadonlyMap<number, string>;
/**
* Optional observed-reuse score per chunk in [0, 1] (t_65588d8b): the
* folded USED-vs-CONTRADICTED rate of the chunk's document, the preferred
* outcome signal over predicted importance. Missing entries (and the
* absent map) contribute zero boost, so a vault with no observed-use
* verdicts ranks bit-identically.
*/
readonly reuseRateByChunk?: ReadonlyMap<number, number>;
/**
* Optional relational RRF arm (t_09b7ccea): chunk ids from typed-edge
* fan-out, best-first. Only consulted in `rrf` fusion. A relational-only
* chunk (not already a keyword/semantic candidate) is admitted as a
* candidate so a genuinely related node can surface. Absent or empty
* leaves ranking byte-identical.
*/
readonly relationalRankedChunkIds?: ReadonlyArray<number>;
/**
* Optional DECLARED event time per chunk in unix ms (t_58fc4720): the
* validity-window start the document states in its frontmatter. Read
* only by the query-side temporal layer, and only for chunks that
* actually declare one - a missing entry (and the absent map) falls
* back to the chunk's storage mtime, the same "validity start, else
* mtime" rule `temporal-bridge.ts` applies.
*/
readonly eventTimeMsByChunk?: ReadonlyMap<number, number>;
/**
* Optional pinned flag per documentId (t_f7bef96a): the per-note
* `pinned` frontmatter state the indexer persisted into
* `documents.pinned`, read through the store's pinned-documents lookup.
*
* A document in the set earns the capped boost; every other one - a
* measured not-pinned row or one the index has not re-examined since
* the column existed - contributes nothing and reports by absence in
* the breakdown exactly like an unwired layer. An absent or empty set
* leaves every score and the breakdown shape byte-identical to
* pre-feature ranking.
*/
readonly pinnedDocIds?: ReadonlySet<number>;
}
/**
* Bounded additive-boost caps. Every one of these layers is a re-ranker
* over an already-relevant candidate set: large enough to reorder it,
* never large enough to float an irrelevant chunk. They are named here,
* together, because their PROPORTION to each other is the calibration -
* a cap is only meaningful relative to its siblings.
*/
/** Inbound links plus shared tags, combined. */
export const LINK_BOOST_CAP = 0.05;
/** The inbound-link half of {@link LINK_BOOST_CAP}. */
const LINK_ONLY_BOOST_CAP = 0.03;
/** The shared-tag half of {@link LINK_BOOST_CAP}. */
const TAG_ONLY_BOOST_CAP = 0.02;
/** Query entities the chunk also carries. */
export const ENTITY_BOOST_CAP = 0.04;
/**
* Derived person-variant matches (write-honesty-egress-consent, F3):
* half the declared per-match rate and half the declared cap, so a
* declared-form match always outranks a derived-variant match between
* otherwise-equal candidates.
*/
export const DERIVED_ENTITY_BOOST_CAP = 0.02;
/** Access-reinforced, type-decayed activation. */
export const ACTIVATION_BOOST_CAP = 0.04;
/** Habitual co-retrieval companions inside the candidate pool. */
export const CO_ACCESS_BOOST_CAP = 0.03;
/** Folded USED-vs-CONTRADICTED outcome rate: the strongest evidence layer. */
export const REUSE_BOOST_CAP = 0.06;
/**
* Query-declared temporal window (t_58fc4720). Set level with the reuse
* cap - the top of the band - because it corrects a prior that is itself
* worth up to the full recency amplitude (0.05) in the WRONG direction:
* a smaller cap could not overcome the freshness prior it exists to
* offset, and the layer would be decorative.
*/
export const TEMPORAL_INTENT_BOOST_CAP = 0.06;
/**
* Explicit operator/agent pin (t_f7bef96a): a document whose frontmatter
* carries `pinned: true`, persisted by the indexer into
* `documents.pinned`. Set level with the link cap - the reinforce scale -
* because it is the same kind of signal: a bounded nudge over an
* already-relevant candidate set, never an override of the relevance term
* (BM25's lead is an order of magnitude above it). Always-on rather than
* config-gated: it is a bounded signal over explicit operator state, not
* a behaviour mode, and it is inspectable through the reason strings.
*/
export const PINNED_BOOST_CAP = 0.05;
/** Freshness-trend multipliers on the relevance portion. */
const TREND_MULTIPLIERS: ReadonlyMap<string, number> = new Map([
["strengthening", 1.05],
["weakening", 0.93],
["stale", 0.85],
]);
/**
* Relation-only supersede fade (t_c4a9cef8), applied through kernel 1 by
* the supersede-fade adjuster - NOT inside `rankResults`. It lives here,
* beside the freshness multipliers, because it is the same family of
* bounded score-scaling constant: a candidate a surfaced `superseded_by`
* relation marks superseded is faded to this share of its score so a
* stale memory that survived the tombstone drop cannot outrank the memory
* that replaced it. A pool with no such relation ranks byte-identically.
*/
export const SUPERSEDE_FADE_MULTIPLIER = 0.5;
export interface RankerOptions {
readonly keywordWeight: number;
readonly semanticWeight: number;
readonly limit: number;
/** Unix-ms reference time for recency. Defaults to Date.now(). */
readonly nowMs?: number;
/** When false, semantic_score is ignored regardless of inputs. */
readonly semanticEnabled?: boolean;
/**
* Weibull recency curve parameters. Absent uses {@link DEFAULT_RECENCY},
* which approximates the legacy step function. Callers (search.ts)
* thread the resolved config here.
*/
readonly recency?: WeibullRecencyOptions;
/**
* Per-query ranking multipliers from the query plan (v0.20.0). Absent
* (or an all-1.0 neutral profile) leaves every layer at its configured
* weight, so ranking is bit-identical to pre-intent behaviour.
*/
readonly weightProfile?: WeightProfile;
readonly sessionFocus?: SearchSessionFocus | null;
/**
* Rank-fusion mode (Embedding Provider Suite). `linear` (default) is
* the weighted sum of normalised BM25 and cosine; `rrf` fuses the two
* lanes by reciprocal rank. Absent or `linear` keeps ranking
* bit-identical to pre-suite behaviour.
*/
readonly fusionMode?: FusionMode;
/** RRF damping constant; defaults to {@link DEFAULT_RRF_K}. */
readonly rrfK?: number;
/**
* The time window the query declares (t_58fc4720), resolved by
* `temporal-intent.ts` at the query-plan seam. When present it adds a
* capped proximity boost for candidates whose event time falls in (or
* near) the window, and damps the query-independent freshness prior
* when that window is historical. Absent or null leaves ranking
* byte-identical, including the `temporal` breakdown key, which is
* then omitted rather than reported as zero.
*/
readonly temporalIntent?: TemporalIntent | null;
/**
* Metadata-boost lexical-vote gate (t_d9f863e9), from
* `search_metadata_boost_gate`. When true, a query whose keyword lane
* returned no hits (no lexical vote - the pre-boost BM25 result set is
* empty) contributes exactly ZERO from every additive metadata/structural
* boost layer: link (with its tag half), freshness, entity, activation,
* co-access, observed reuse, temporal intent and session focus. The
* relevance terms (keyword, semantic, rrf), the relevance-portion
* multipliers (tier, trend) and the pinned layer - a bounded signal over
* explicit operator state, always-on by its own decision - are not
* metadata boosts and stay live. Absent or false leaves every layer
* byte-identical, and a gated run names its suppressed layers in
* `reasons`/`breakdown`.
*/
readonly metadataBoostGate?: boolean;
}
const DAY_MS = 24 * 60 * 60 * 1000;
/** Min-max normalise BM25 within the candidate set. Lower BM25 is better. */
function normalizeBm25(hits: ReadonlyArray<KeywordHit>): Map<number, number> {
const out = new Map<number, number>();
if (hits.length === 0) return out;
// FTS5 bm25() returns smaller-is-better values (often negative). We invert
// to "larger is better" by negating, then min-max.
const scores = hits.map((h) => -h.bm25);
const min = Math.min(...scores);
const max = Math.max(...scores);
if (max === min) {
for (const h of hits) out.set(h.chunkId, 1);
return out;
}
hits.forEach((h, i) => {
out.set(h.chunkId, (scores[i]! - min) / (max - min));
});
return out;
}
/** Map L2-on-unit-vectors distance → cosine similarity in [0, 1]. */
function semanticFromDistance(distance: number): number {
const sim = 1 - (distance * distance) / 2;
return clamp01(sim);
}
/**
* Freshness decay for a candidate whose age is measured from
* `anchorSeconds` (unix seconds - the same unit both `documents.mtime`
* and `documents.authored_at` are stored in, so no conversion enters
* here).
*/
function recencyBoost(anchorSeconds: number, nowMs: number, opts: WeibullRecencyOptions): number {
const ageMs = Math.max(0, nowMs - anchorSeconds * 1000);
const ageDays = ageMs / DAY_MS;
return weibullDecay(ageDays, opts);
}
/**
* The instant a candidate's age is measured from, in unix seconds: the
* authoring instant the document declares, else the filesystem mtime the
* indexer recorded when it wrote the file.
*
* `mtime` answers "when did this vault last touch the file", which is a
* storage fact. Freshness is a question about the content, and only
* `authored_at` answers it: a conversation imported today whose turns
* happened a year ago is a year old, however new its file is.
*
* The real exposure: the indexer reads `authored_at` off the frontmatter of
* EVERY indexed markdown file (`authoredAtFromFrontmatter`), so any note in
* the vault can populate the column, not only the artifacts session import
* and the inbox backfill write. A vault whose notes declare no `authored_at`
* still resolves to `mtime` for every candidate - the pre-existing behaviour,
* exactly - but that is a property of the CORPUS, not a limit on who can
* reach this layer.
*
* Which is why the anchor is not the declared value but the USABLE one: an
* instant later than the query clock cannot be an authoring instant, and
* taken at face value it pinned the document at the top of the decay curve
* permanently (`weibullDecay` returns its full amplitude for a non-positive
* age). Such a document falls back to `mtime` - the storage fact is the only
* instant left, and it is exactly where the same note sat before this layer
* existed. Clamping to now instead would hold it at maximum freshness
* forever, which is the defect and not its fix.
*/
function freshnessAnchorSeconds(usableAuthoredAt: number | null, mtime: number): number {
return usableAuthoredAt ?? mtime;
}
interface Candidate {
chunkId: number;
documentId: number;
keywordScore: number;
semanticScore: number;
searchType: "keyword" | "semantic" | "hybrid" | "link";
mtime: number;
}
/** Fixed-precision so the same vault yields the same reason strings. */
function fmt(x: number): string {
return x.toFixed(3);
}
/** The structured gate receipt a breakdown carries; see {@link RankerOptions.metadataBoostGate}. */
type BoostGateReceipt = NonNullable<ScoreBreakdown["gate"]>;
/**
* Assemble the explainable-recall `reasons` array from the per-layer
* values the ranker already computed. One entry per layer that fired;
* a layer contributing exactly zero is omitted so the array stays
* meaningful. The tier layer is reported only when it is not the
* neutral 1.0 multiplier. The lexical-vote gate appends one entry when it
* actually suppressed something, so a gated run says why its metadata
* layers are silent.
*/
function buildReasons(parts: {
keywordScore: number;
semanticScore: number;
linkBoost: number;
recency: number;
tierMul: number;
entityBoost?: number;
derivedEntityBoost?: number;
activationBoost?: number;
coAccessBoost?: number;
reuseBoost?: number;
pinnedBoost?: number;
trend?: string;
trendMul?: number;
sessionFocus?: number;
rrf?: number;
temporalBoost?: number;
temporalDamping?: number;
gate?: { readonly suppressed: number };
}): ReadonlyArray<string> {
const reasons: string[] = [];
if (parts.keywordScore > 0) reasons.push(`fts5_bm25: ${fmt(parts.keywordScore)}`);
if (parts.semanticScore > 0) reasons.push(`semantic_cos: ${fmt(parts.semanticScore)}`);
if (parts.rrf && parts.rrf > 0) reasons.push(`rrf: ${fmt(parts.rrf)}`);
if (parts.entityBoost && parts.entityBoost > 0) {
reasons.push(`entity_match: ${fmt(parts.entityBoost)}`);
}
// Derived person-variant lane (F3), named apart from the declared
// entity_match so attribution can tell the two tiers apart.
if (parts.derivedEntityBoost !== undefined && parts.derivedEntityBoost > 0) {
reasons.push(`entity_variant: ${fmt(parts.derivedEntityBoost)}`);
}
if (parts.activationBoost && parts.activationBoost > 0) {
reasons.push(`activation: ${fmt(parts.activationBoost)}`);
}
if (parts.coAccessBoost && parts.coAccessBoost > 0) {
reasons.push(`co_access: ${fmt(parts.coAccessBoost)}`);
}
if (parts.reuseBoost && parts.reuseBoost > 0) {
reasons.push(`observed_reuse: ${fmt(parts.reuseBoost)}`);
}
if (parts.pinnedBoost && parts.pinnedBoost > 0) {
reasons.push(`pinned: ${fmt(parts.pinnedBoost)}`);
}
if (parts.trend !== undefined && parts.trendMul !== undefined && parts.trendMul !== 1) {
reasons.push(`freshness_trend: ${parts.trend} x${fmt(parts.trendMul)}`);
}
if (parts.linkBoost > 0) reasons.push(`link_boost: ${fmt(parts.linkBoost)}`);
if (parts.recency > 0) reasons.push(`recency: ${fmt(parts.recency)}`);
// Query-side temporal intent, kept SEPARATE from the `recency` entry
// above so a ranking change is attributable to one layer or the other.
// Reported whenever the layer had an effect - a zero boost still
// matters when the window damped the freshness prior, which is exactly
// the case for an out-of-window recent document.
if (
parts.temporalBoost !== undefined &&
(parts.temporalBoost > 0 || (parts.temporalDamping ?? 1) !== 1)
) {
const damping = parts.temporalDamping ?? 1;
const suffix = damping === 1 ? "" : ` recency x${fmt(damping)}`;
reasons.push(`temporal_intent: ${fmt(parts.temporalBoost)}${suffix}`);
}
if (parts.tierMul !== 1) reasons.push(`tier: ${fmt(parts.tierMul)}`);
if (parts.sessionFocus && parts.sessionFocus !== 0) {
reasons.push(`session_focus: ${parts.sessionFocus >= 0 ? "+" : ""}${fmt(parts.sessionFocus)}`);
}
if (parts.gate !== undefined && parts.gate.suppressed > 0) {
const noun = parts.gate.suppressed === 1 ? "layer" : "layers";
reasons.push(`gated: no lexical vote suppressed ${parts.gate.suppressed} ${noun}`);
}
return Object.freeze(reasons);
}
/**
* Structured sibling of {@link buildReasons} over the same per-layer
* values. Every component is a number: zero for an additive layer that
* did not fire, 1 for a neutral multiplier. No omission and no
* formatting, so callers (the MCP `explain` projection, `feedback.ts`)
* read the contributions without re-parsing the reason strings.
*/
function buildBreakdown(parts: {
keywordScore: number;
semanticScore: number;
linkBoost: number;
recency: number;
tierMul: number;
entityBoost?: number;
derivedEntityBoost?: number;
activationBoost?: number;
coAccessBoost?: number;
reuseBoost?: number;
pinnedBoost?: number;
trendMul?: number;
sessionFocus?: number;
rrf?: number;
temporalBoost?: number;
gate?: BoostGateReceipt;
}): ScoreBreakdown {
return Object.freeze({
keyword: parts.keywordScore,
semantic: parts.semanticScore,
rrf: parts.rrf ?? 0,
entity: parts.entityBoost ?? 0,
// Derived person-variant lane (F3): present only when the chunk
// actually matched a derived form - absent, not zero, otherwise -
// so a result without derived matches keeps the pre-feature shape.
...(parts.derivedEntityBoost !== undefined ? { entityDerived: parts.derivedEntityBoost } : {}),
activation: parts.activationBoost ?? 0,
coAccess: parts.coAccessBoost ?? 0,
reuse: parts.reuseBoost ?? 0,
...(parts.pinnedBoost !== undefined ? { pinned: parts.pinnedBoost } : {}),
link: parts.linkBoost,
recency: parts.recency,
tier: parts.tierMul,
trend: parts.trendMul ?? 1,
sessionFocus: parts.sessionFocus ?? 0,
// Present whenever the gate is CONFIGURED on, so an operator can tell
// an armed gate that found its vote from one that had none; absent
// entirely (byte-identical shape) when the gate is off.
...(parts.gate !== undefined ? { gate: parts.gate } : {}),
// The one layer reported by ABSENCE rather than by zero: a query
// that declared no window has no temporal component at all, and a
// consumer must be able to tell that from a window the candidate
// simply fell outside of.
...(parts.temporalBoost !== undefined ? { temporal: parts.temporalBoost } : {}),
});
}
export function rankResults(inputs: RankerInputs, opts: RankerOptions): BrainSearchResult[] {
const nowMs = opts.nowMs ?? Date.now();
const semanticEnabled = opts.semanticEnabled !== false;
const recencyOpts = opts.recency ?? DEFAULT_RECENCY;
// Per-query intent multipliers. Absent or neutral (all 1.0) leaves the
// score bit-identical to pre-intent behaviour.
const kwMul = opts.weightProfile?.keywordMul ?? 1;
const semMul = opts.weightProfile?.semanticMul ?? 1;
const entMul = opts.weightProfile?.entityMul ?? 1;
const recMul = opts.weightProfile?.recencyMul ?? 1;
// Query-side temporal intent (t_58fc4720). Null (the default) keeps
// the damping neutral and leaves the layer entirely unreported.
const temporalIntent = opts.temporalIntent ?? null;
const temporalDamping = temporalIntent?.recencyDamping ?? 1;
// Metadata-boost lexical-vote gate (t_d9f863e9): the lexical vote is
// "the keyword lane produced at least one hit for this query", read off
// the PRE-boost keyword input - the same array every keyword-lane
// consumer above reads. Loop-invariant, so the predicate is evaluated
// once and every candidate's boosts answer the same question.
const lexicalVote = inputs.keyword.length > 0;
const gateActive = opts.metadataBoostGate === true && !lexicalVote;
const kwNorm = normalizeBm25(inputs.keyword);
const semNorm = new Map<number, number>();
if (semanticEnabled) {
for (const h of inputs.semantic) {
semNorm.set(h.chunkId, semanticFromDistance(h.distance));
}
}
// Reciprocal Rank Fusion (Embedding Provider Suite): fuse the lanes by
// rank position instead of weighted magnitude. Off by default; when on,
// it replaces the linear relevance term while every boost still applies.
const fusionMode: FusionMode = opts.fusionMode ?? "linear";
let rrfByChunk: Map<number, number> | null = null;
if (fusionMode === "rrf") {
const keywordRanked = inputs.keyword
.toSorted((a, b) => a.bm25 - b.bm25) // lower BM25 = better
.map((h) => h.chunkId);
const semanticRanked = semanticEnabled
? inputs.semantic.toSorted((a, b) => a.distance - b.distance).map((h) => h.chunkId)
: [];
rrfByChunk = rrfFuse({
keywordRankedChunkIds: keywordRanked,
semanticRankedChunkIds: semanticRanked,
relationalRankedChunkIds: inputs.relationalRankedChunkIds ?? [],
k: opts.rrfK ?? DEFAULT_RRF_K,
// The intent profile weights the per-lane CONTRIBUTIONS, not the
// fused score: a post-fusion multiplier is a constant factor on
// every candidate and could not express a lane preference at all.
// A neutral profile passes 1 on both lanes, which is the classic
// weightless term bit for bit.
laneWeights: { keyword: kwMul, semantic: semMul },
});
}
const candidates = new Map<number, Candidate>();
for (const h of inputs.keyword) {
candidates.set(h.chunkId, {
chunkId: h.chunkId,
documentId: h.documentId,
keywordScore: kwNorm.get(h.chunkId) ?? 0,
semanticScore: 0,
searchType: "keyword",
mtime: inputs.hydrated.get(h.chunkId)?.mtime ?? 0,
});
}
if (semanticEnabled) {
for (const h of inputs.semantic) {
const existing = candidates.get(h.chunkId);
if (existing) {
existing.semanticScore = semNorm.get(h.chunkId) ?? 0;
existing.searchType = "hybrid";
} else {
candidates.set(h.chunkId, {
chunkId: h.chunkId,
documentId: h.documentId,
keywordScore: 0,
semanticScore: semNorm.get(h.chunkId) ?? 0,
searchType: "semantic",
mtime: inputs.hydrated.get(h.chunkId)?.mtime ?? 0,
});
}
}
}
// Relational arm candidates (t_09b7ccea): admit relational-only chunks
// (surfaced via the typed-edge fan-out lane but not matched by keyword or
// semantic) so a genuinely related node can enter the fused ranking. Only
// in rrf mode, where the lane above already contributes their score.
// searchType "link" - a typed-graph traversal hit. Empty lane = no
// additions, so ranking stays byte-identical. The admitted ids are
// tracked separately: searchType "link" has other producers (polarity
// pull-in, graph traversal), so structural admission keys on THIS set,
// never on the searchType.
const relationalOnlyIds = new Set<number>();
if (rrfByChunk !== null && inputs.relationalRankedChunkIds) {
for (const chunkId of inputs.relationalRankedChunkIds) {
if (candidates.has(chunkId)) continue;
const hyd = inputs.hydrated.get(chunkId);
if (hyd === undefined) continue;
relationalOnlyIds.add(chunkId);
candidates.set(chunkId, {
chunkId,
documentId: hyd.documentId,
keywordScore: 0,
semanticScore: 0,
searchType: "link",
mtime: hyd.mtime,
});
}
}
// Cross-result tables for boosts.
const candidateChunks = Array.from(candidates.values());
const candidateDocIds = new Set(candidateChunks.map((c) => c.documentId));
// Build a per-document tag map so the tag boost counts distinct docs,
// not chunks. Without this dedup a doc with K candidate chunks would
// inflate every other candidate's tag count K-fold.
const tagsByDocId = new Map<number, ReadonlySet<string>>();
for (const c of candidateChunks) {
if (tagsByDocId.has(c.documentId)) continue;
const t = inputs.tagsByDoc.get(c.chunkId);
if (t && t.size > 0) tagsByDocId.set(c.documentId, t);
}
function linkBoostFor(c: Candidate): number {
const sources = inputs.inboundLinkSources.get(c.chunkId);
if (!sources || sources.size === 0) return 0;
let count = 0;
for (const s of sources) {
if (s === c.documentId) continue;
if (candidateDocIds.has(s)) count++;
}
const raw = count * 0.02;
return Math.min(LINK_ONLY_BOOST_CAP, raw);
}
function tagBoostFor(c: Candidate): number {
const mine = tagsByDocId.get(c.documentId);
if (!mine || mine.size === 0) return 0;
let count = 0;
for (const [otherDocId, theirs] of tagsByDocId) {
if (otherDocId === c.documentId) continue;
for (const tag of mine) {
if (theirs.has(tag)) {
count++;
break;
}
}
}
const raw = count * 0.01;
return Math.min(TAG_ONLY_BOOST_CAP, raw);
}
const ranked: BrainSearchResult[] = [];
for (const c of candidateChunks) {
const hyd = inputs.hydrated.get(c.chunkId);
if (!hyd) continue;
const link = linkBoostFor(c);
const tag = tagBoostFor(c);
const linkBoost = Math.min(LINK_BOOST_CAP, link + tag);
// Freshness prior, damped when the query named a historical window:
// the prior points at "now" and the query points at the past, so
// leaving it undamped would fight the layer below. Damped, never
// removed - `recencyAmplitude: 0` stays the only off switch.
// Age runs from the authoring instant when the record declares a usable
// one (D1) - see `freshnessAnchorSeconds` for why, and for what "usable"
// rules out. Resolved ONCE per candidate: the freshness prior, the
// reported field and the chronology tie-break must not disagree about
// whether this row carries an authoring instant.
const authoredAt = usableAuthoredAtSeconds(hyd.authoredAt, nowMs);
const recency =
recencyBoost(freshnessAnchorSeconds(authoredAt, c.mtime), nowMs, recencyOpts) *
recMul *
temporalDamping;
// Relevance term: reciprocal-rank-fused when in rrf mode, otherwise
// the weighted sum of the normalised lanes. The fused value already
// carries the intent multipliers (applied per lane, above); the
// CONFIGURED lane weights stay out of it, because they calibrate two
// score magnitudes and rank fusion reads no magnitudes.
const rrf = rrfByChunk?.get(c.chunkId) ?? 0;
const weighted =
rrfByChunk !== null
? rrf
: opts.keywordWeight * kwMul * c.keywordScore +
(semanticEnabled ? opts.semanticWeight * semMul : 0) * c.semanticScore;
// Tier multiplier applied to the relevance portion only so the
// tag / link / recency boosts stay tier-neutral. Default
// `supporting` → 1.0 keeps untagged vaults bit-identical.
const tier = inputs.tierByDoc?.get(c.documentId) ?? PAGE_TIER_DEFAULT;
const tierMul = tierWeight(tier);
// Freshness-trend multiplier (t_ee09a6ce): like tier, it scales the
// relevance portion only. Unstamped documents (and unknown labels)
// stay at the neutral 1.0.
const trend = inputs.trendByDoc?.get(c.documentId);
const trendMul = trend !== undefined ? (TREND_MULTIPLIERS.get(trend) ?? 1) : 1;
// Entity boost: capped contribution from shared query entities.
// Per-match 0.02, capped at 0.04 so it only re-ranks an already
// relevant set - never enough to float an irrelevant chunk.
const entityMatches = inputs.entityMatchByChunk?.get(c.chunkId) ?? 0;
const entityBoost = Math.min(ENTITY_BOOST_CAP, entityMatches * 0.02 * entMul);
// Derived person-variant lane (F3): strictly below the declared
// lane above, capped, and reported by ABSENCE when it does not
// fire (undefined, not zero) so a result without derived matches
// keeps its pre-feature breakdown shape.
const derivedEntityMatches = inputs.derivedEntityMatchByChunk?.get(c.chunkId) ?? 0;
const derivedEntityBoost =
derivedEntityMatches > 0
? Math.min(DERIVED_ENTITY_BOOST_CAP, derivedEntityMatches * 0.01 * entMul)
: undefined;
// Activation boost (Time-Aware Recall & Activation Suite): the
// effective (type-decayed) activation scales into a capped 0.04
// contribution - a re-ranker for habitually-recalled memories,
// never enough to float an irrelevant chunk.
const activation = clamp01(inputs.activationByChunk?.get(c.chunkId) ?? 0);
const activationBoost = Math.min(ACTIVATION_BOOST_CAP, activation * ACTIVATION_BOOST_CAP);
// Co-access companion boost (t_c5ef25a3): per habitual companion
// that is ALSO in the candidate pool, 0.005 per recorded pair
// count, capped at 0.03 - surfaces the rest of a recurring working
// set without floating unrelated documents.
let coAccessRaw = 0;
const companions = inputs.coAccessByChunk?.get(c.chunkId);
if (companions !== undefined) {
for (const [docId, count] of companions) {
if (docId === c.documentId) continue;
if (candidateDocIds.has(docId)) coAccessRaw += count * 0.005;
}
}
const coAccessBoost = Math.min(CO_ACCESS_BOOST_CAP, coAccessRaw);
// Observed-reuse boost (t_65588d8b): the folded USED-vs-CONTRADICTED
// rate of the chunk's document. Capped at 0.06 - larger than the
// activation / co-access caps so a memory the agent demonstrably reused
// outranks one merely predicted-important, yet still a bounded re-ranker
// that never floats an irrelevant chunk. Zero (byte-identical) when no
// observed-use verdicts exist.
const reuseRate = clamp01(inputs.reuseRateByChunk?.get(c.chunkId) ?? 0);
const reuseBoost = Math.min(REUSE_BOOST_CAP, reuseRate * REUSE_BOOST_CAP);
// Pinned boost (t_f7bef96a): the operator/agent pin the indexer
// persisted. A pinned document earns the full cap; any other is
// undefined, not zero, so the layer stays absent from `reasons` and
// `breakdown` and an unpinned result keeps its pre-feature shape.
const pinnedBoost =
inputs.pinnedDocIds?.has(c.documentId) === true ? PINNED_BOOST_CAP : undefined;
// Query-side temporal intent (t_58fc4720): proximity of the
// candidate's EVENT time (declared validity start, else storage
// mtime) to the window the query named, scaled into a capped
// contribution. Undefined - not zero - when the query named no
// window, so the layer stays absent from `reasons` and `breakdown`.
let temporalBoost: number | undefined;
if (temporalIntent !== null) {
const eventMs = inputs.eventTimeMsByChunk?.get(c.chunkId) ?? c.mtime * 1000;
const proximity = temporalProximity(eventMs, temporalIntent.range, DEFAULT_WINDOW_PAD_DAYS);
temporalBoost = Math.min(TEMPORAL_INTENT_BOOST_CAP, proximity * TEMPORAL_INTENT_BOOST_CAP);
}
const sessionFocus = scoreSessionFocusTarget(hyd, opts.sessionFocus, nowMs);
// Metadata-boost lexical-vote gate (t_d9f863e9): when the gate is on
// and the keyword lane cast no vote, every additive metadata/structural
// layer contributes exactly ZERO - not damped - and each layer whose
// contribution was nonzero is named as suppressed. Gate off (or a cast
// vote) hands every raw value straight through, byte-identically.
const suppressedLayers: string[] = [];
const zeroWithoutVote = (layer: string, raw: number): number => {
if (!gateActive || raw === 0) return raw;
suppressedLayers.push(layer);
return 0;
};
const linkBoostVoted = zeroWithoutVote("link", linkBoost);
const recencyVoted = zeroWithoutVote("recency", recency);
const entityBoostVoted = zeroWithoutVote("entity", entityBoost);
const derivedEntityBoostVoted =
derivedEntityBoost === undefined
? undefined
: zeroWithoutVote("entityDerived", derivedEntityBoost);
const activationBoostVoted = zeroWithoutVote("activation", activationBoost);
const coAccessBoostVoted = zeroWithoutVote("coAccess", coAccessBoost);
const reuseBoostVoted = zeroWithoutVote("reuse", reuseBoost);
const temporalBoostVoted =
temporalBoost === undefined ? undefined : zeroWithoutVote("temporal", temporalBoost);
const sessionFocusVoted = zeroWithoutVote("sessionFocus", sessionFocus);
const gateReceipt: BoostGateReceipt | undefined =
opts.metadataBoostGate === true
? Object.freeze({
active: gateActive,
lexicalVote,
suppressedLayers: Object.freeze([...suppressedLayers]),
})
: undefined;
const score = clamp01(
weighted * tierMul * trendMul +
linkBoostVoted +
recencyVoted +
entityBoostVoted +
(derivedEntityBoostVoted ?? 0) +
activationBoostVoted +
coAccessBoostVoted +
reuseBoostVoted +
(pinnedBoost ?? 0) +
(temporalBoostVoted ?? 0) +
sessionFocusVoted,
);
ranked.push(
Object.freeze({
documentId: c.documentId,
chunkId: c.chunkId,
path: hyd.path,
title: hyd.title,
content: hyd.content,
startLine: hyd.startLine,
endLine: hyd.endLine,
score,
keywordScore: c.keywordScore,
semanticScore: c.semanticScore,
linkBoost: linkBoostVoted,
recencyBoost: recencyVoted,
// Conversation chronology (S1): expose the authoring instant only
// when the note carries a usable one, so a note with no turn instant
// keeps the byte-identical result shape - and a note whose declared
// instant the ranker refused does not hand a consumer, as an
// authoring instant, a value the ranking itself would not trust.
...(authoredAt !== null ? { authoredAt } : {}),
searchType: c.searchType,
// The typed-edge arm contributed this candidate (t_09b7ccea).
// searchType "link" names only the arm-EXCLUSIVE admissions; this
// flag carries the arm's full contribution set for the relational
// rerank pin (t_d9f863e9) downstream. Absent when the arm did not
// run, so an arm-off pipeline emits rows byte-identically.
...(inputs.relationalRankedChunkIds?.includes(c.chunkId) === true
? { relationalOrigin: true }
: {}),
reasons: buildReasons({
reuseBoost: reuseBoostVoted,
pinnedBoost,
keywordScore: c.keywordScore,
semanticScore: semanticEnabled ? c.semanticScore : 0,
linkBoost: linkBoostVoted,
recency: recencyVoted,
tierMul,
entityBoost: entityBoostVoted,
derivedEntityBoost: derivedEntityBoostVoted,
activationBoost: activationBoostVoted,
coAccessBoost: coAccessBoostVoted,
...(trend !== undefined ? { trend, trendMul } : {}),
sessionFocus: sessionFocusVoted,
rrf: rrfByChunk !== null ? rrf : 0,
...(temporalBoostVoted !== undefined
? { temporalBoost: temporalBoostVoted, temporalDamping }
: {}),
...(gateReceipt !== undefined
? { gate: { suppressed: gateReceipt.suppressedLayers.length } }
: {}),
}),
breakdown: buildBreakdown({
reuseBoost: reuseBoostVoted,
pinnedBoost,
keywordScore: c.keywordScore,
semanticScore: semanticEnabled ? c.semanticScore : 0,
linkBoost: linkBoostVoted,
recency: recencyVoted,
tierMul,
entityBoost: entityBoostVoted,
derivedEntityBoost: derivedEntityBoostVoted,
activationBoost: activationBoostVoted,
coAccessBoost: coAccessBoostVoted,
trendMul,
sessionFocus: sessionFocusVoted,
rrf: rrfByChunk !== null ? rrf : 0,
...(temporalBoostVoted !== undefined ? { temporalBoost: temporalBoostVoted } : {}),
...(gateReceipt !== undefined ? { gate: gateReceipt } : {}),
}),
}),
);
}
// Tie-break ladder, top to bottom: final_score desc, then (under an
// active window only) temporal desc, then authoring instant desc, then
// keywordScore desc, mtime desc, chunkId asc. The last four are design
// §7 plus the conversation-chronology rung; the temporal rung sits
// above all of them - see below for why that is one step higher than a
// purely freshness-facing correction would place it.
// Conversation chronology (S1): on an EXACT hybrid-score tie, order by
// more recent authoring instant FIRST - but only when BOTH results carry
// an `authored_at`. A pair where either side has none falls through to
// the historical tie-break, so any non-tied pair (and every pair without
// turn instants) keeps today's order byte-identically.
// D1 narrowed this rung's domain without emptying it. Now that the same
// instant drives the freshness prior above, two instants inside the live
// decay band separate the SCORE and never arrive here. What still does:
// a pair whose instants both decay to the same value (the epsilon floor
// in `recency.ts` swallows anything past roughly half a year), a
// composite `clamp01` saturated, and a vault that turned the freshness
// layer off. Those are ordinary, so the rung stays.
// Query-side temporal intent (t_58fc4720): under an active window the
// temporal layer separates the tie FIRST - above the whole ladder
// below, `keywordScore` included, not only above the two freshness
// rungs.
//
// Two reasons, and the second is why the rung sits one step higher than
// a freshness-only correction would need:
//
// - the authoring instant and `mtime` both order NEWER first, which
// is the very bias a declared historical window contradicts, and a
// saturating `clamp01` can hide a candidate's larger temporal
// contribution behind an exact score tie;
// - `keywordScore` is already a COMPONENT of `score`. On an exact
// tie it re-applies a signal the composite has already counted,
// which cannot separate what that composite could not. The window
// is an axis the query stated and the score may have saturated
// away, so it is the one that still carries information here.
//
// Equal contributions (including both zero) and an absent window fall
// straight through to the historical ladder, byte-identically.
ranked.sort((a, b) => {
// Structural direct-hit precedence (truth-correctable-time-aware): a
// relational-only admission is admitted BELOW the organic tail in the
// pre-rerank fused order. The arm's lane weight is neutral, so on raw
// RRF a relational-only rank 1 could float above a deep keyword direct
// hit; this rung makes that structurally impossible - the traversal
// widens the pool, it never outranks what the lanes matched. With the
// arm off the set is empty and the rung never fires, byte-identically.
const aRelationalOnly = relationalOnlyIds.has(a.chunkId);
const bRelationalOnly = relationalOnlyIds.has(b.chunkId);
if (aRelationalOnly !== bRelationalOnly) return aRelationalOnly ? 1 : -1;
if (b.score !== a.score) return b.score - a.score;
// Structural declared-before-derived entity precedence, as a TIE-BREAK
// on exact score ties only: candidates are partitioned into TIERS -
// declared, then neutral, then derived-only - and the tiers compare
// only after the composite scores have had their say, so the capped
// boost lanes stay the ranking mechanism and a single entity match can
// never float a low-scoring chunk above a higher-scoring one (nor sink
// a derived-only direct hit below the cut). The lane sizes (declared
// 0.02 per match capped at 0.04, derived 0.01 capped at 0.02) already
// rank declared above derived among otherwise-equal candidates; the
// tier orders what the lanes could not separate - ties left by a zeroed
// boost or a saturated cap. A tier, not a pairwise rule: within one
// score value the partition is a strict weak ordering, and across
// values the score decides, so the sort never depends on the input
// order.
const aDeclared = (inputs.entityMatchByChunk?.get(a.chunkId) ?? 0) > 0;
const bDeclared = (inputs.entityMatchByChunk?.get(b.chunkId) ?? 0) > 0;
const aDerivedOnly =
aDeclared === false && (inputs.derivedEntityMatchByChunk?.get(a.chunkId) ?? 0) > 0;
const bDerivedOnly =
bDeclared === false && (inputs.derivedEntityMatchByChunk?.get(b.chunkId) ?? 0) > 0;
const tierOf = (declared: boolean, derivedOnly: boolean): number =>
declared ? 0 : derivedOnly ? 2 : 1;
const tierDelta = tierOf(aDeclared, aDerivedOnly) - tierOf(bDeclared, bDerivedOnly);
if (tierDelta !== 0) return tierDelta;
if (temporalIntent !== null) {
const aTemporal = a.breakdown?.temporal ?? 0;
const bTemporal = b.breakdown?.temporal ?? 0;
if (aTemporal !== bTemporal) return bTemporal - aTemporal;
}
// Read off the RESULT, not the hydrated row: the result carries the
// usable instant this run resolved, so a row whose declared instant was
// refused above cannot win the rung the refusal exists to protect.
const aAuthored = a.authoredAt ?? null;
const bAuthored = b.authoredAt ?? null;
if (aAuthored !== null && bAuthored !== null && aAuthored !== bAuthored) {
return bAuthored - aAuthored;
}
if (b.keywordScore !== a.keywordScore) return b.keywordScore - a.keywordScore;
const am = inputs.hydrated.get(a.chunkId)?.mtime ?? 0;
const bm = inputs.hydrated.get(b.chunkId)?.mtime ?? 0;
if (bm !== am) return bm - am;
return a.chunkId - b.chunkId;
});
return ranked.slice(0, Math.max(1, opts.limit));
}