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
/**
* Metadata-boost lexical-vote gate (t_d9f863e9): the opt-in
* `search_metadata_boost_gate` config key makes every additive
* metadata/structural boost layer contribute exactly ZERO when the keyword
* lane returned no hits for the query - the BM25 result set is empty before
* boosts, so no lexical vote was cast and a vector-only answer must not be
* floated by layers calibrated over a lexical candidate set.
*
* Pinned here:
* - the gate is a PRE-boost predicate over `inputs.keyword` (the pre-boost
* keyword input the ranker already receives): zero hits = no vote;
* - gated layers contribute exactly zero (not damped), and the receipts
* say so - a `gated: no lexical vote` reason entry and a structured
* `gate` breakdown naming the layers actually suppressed;
* - the pinned layer is NOT gated: it is a bounded signal over explicit
* operator state, always-on by its own design decision;
* - a query with at least one keyword hit leaves every boost fully
* intact, and the gate off keeps today's behavior byte-identical;
* - both guard keys resolve off by default through `resolveSearchConfig`.
*/
import { test, expect, beforeEach, afterEach } from "bun:test";
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { rankResults } from "../../../src/core/search/ranker.ts";
import { resolveSearchConfig } from "../../../src/core/search/index.ts";
import type { HydratedChunk, SemanticHit } from "../../../src/core/search/store.ts";
import type { RankerInputs, RankerOptions } from "../../../src/core/search/ranker.ts";
// βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
// Ranker layer
// βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
const NOW = 1_750_000_000_000; // ms
const FRESH_MTIME = NOW / 1000 - 60; // inside the decay band β full recency amplitude
const OLD_MTIME = NOW / 1000 - 365 * 24 * 3600; // past the decay band β exactly 0 recency
function hyd(chunkId: number, docId: number, mtime: number): HydratedChunk {
return Object.freeze({
chunkId,
documentId: docId,
path: `doc${docId}.md`,
title: `Doc ${docId}`,
content: `chunk ${chunkId}`,
startLine: 1,
endLine: 1,
mtime,
});
}
/**
* Two vector-only candidates (empty keyword lane) wired with EVERY gated
* metadata layer: a fresh mtime (recency), an in-pool inbound link, a
* shared-tag-free link companion, two query-entity matches, activation, a
* co-access companion in the pool, observed reuse, and a declared temporal
* window under a dedicated test. With the gate off these fire exactly as
* today; with the gate on and no lexical vote, every one of them must
* contribute zero.
*/
function vectorOnlyInputs(): RankerInputs {
const semantic: SemanticHit[] = [
{ chunkId: 1, documentId: 10, distance: 0.2 },
{ chunkId: 2, documentId: 99, distance: 0.3 },
];
return {
keyword: [],
semantic,
hydrated: new Map<number, HydratedChunk>([
[1, hyd(1, 10, FRESH_MTIME)],
[2, hyd(2, 99, OLD_MTIME)],
]),
inboundLinkSources: new Map<number, ReadonlySet<number>>([[1, new Set([99])]]),
tagsByDoc: new Map<number, ReadonlySet<string>>([[1, new Set(["ops"])]]),
entityMatchByChunk: new Map<number, number>([[1, 2]]),
activationByChunk: new Map<number, number>([[1, 1]]),
coAccessByChunk: new Map<number, ReadonlyMap<number, number>>([
[1, new Map<number, number>([[99, 4]])],
]),
reuseRateByChunk: new Map<number, number>([[1, 1]]),
eventTimeMsByChunk: new Map<number, number>([[1, NOW - 86_400_000]]),
};
}
const BASE_OPTS: RankerOptions = {
keywordWeight: 0.6,
semanticWeight: 0.4,
limit: 10,
nowMs: NOW,
};
test("gate off (default) leaves every boost intact and writes no gate receipt", () => {
// The option ABSENT is the off state: the layers fire at full amplitude
// and no gate breakdown appears. The gate's byte-identity when a vote IS
// cast is owned by the one-keyword-hit test below.
const ungated = rankResults(vectorOnlyInputs(), BASE_OPTS);
expect(ungated[0]!.breakdown!.gate).toBeUndefined();
// The metadata layers actually fired: the gated runs have something to gate.
expect(ungated[0]!.breakdown!.recency).toBeGreaterThan(0);
expect(ungated[0]!.breakdown!.entity).toBeGreaterThan(0);
});
test("gate on + no lexical vote: every gated layer contributes exactly zero", () => {
const gated = rankResults(vectorOnlyInputs(), { ...BASE_OPTS, metadataBoostGate: true });
const b = gated[0]!.breakdown!;
expect(b.keyword).toBe(0);
expect(b.link).toBe(0);
expect(b.recency).toBe(0);
expect(b.entity).toBe(0);
expect(b.activation).toBe(0);
expect(b.coAccess).toBe(0);
expect(b.reuse).toBe(0);
expect(b.sessionFocus).toBe(0);
// The semantic relevance term is untouched - only the boost layers gate.
expect(b.semantic).toBeGreaterThan(0);
});
test("a gated query that declared a window reports the temporal layer as zero", () => {
const gated = rankResults(vectorOnlyInputs(), {
...BASE_OPTS,
metadataBoostGate: true,
temporalIntent: {
range: { sinceMs: NOW - 86_400_000, untilMs: NOW },
historical: false,
recencyDamping: 1,
signature: "test-window",
},
});
const b = gated[0]!.breakdown!;
// The query declared a window, so the layer is present - gated to zero,
// not absent: absence is the no-window statement.
expect(b.temporal).toBe(0);
expect(b.recency).toBe(0);
expect(b.gate!.suppressedLayers).toContain("temporal");
});
test("gate on + no lexical vote: the receipts say why", () => {
const gated = rankResults(vectorOnlyInputs(), { ...BASE_OPTS, metadataBoostGate: true });
const gate = gated[0]!.breakdown!.gate!;
expect(gate.active).toBe(true);
expect(gate.lexicalVote).toBe(false);
// Every layer whose raw contribution was nonzero is named as suppressed.
// The temporal layer needs a declared window; a dedicated test covers it.
expect(gate.suppressedLayers).toContain("link");
expect(gate.suppressedLayers).toContain("recency");
expect(gate.suppressedLayers).toContain("entity");
expect(gate.suppressedLayers).toContain("activation");
expect(gate.suppressedLayers).toContain("coAccess");
expect(gate.suppressedLayers).toContain("reuse");
expect(gated[0]!.reasons.some((r) => r.startsWith("gated: no lexical vote"))).toBe(true);
});
test("a gated vector-only query ranks identically to boost-free ranking", () => {
const gated = rankResults(vectorOnlyInputs(), { ...BASE_OPTS, metadataBoostGate: true });
// Boost-free: the same relevance inputs with every signal map removed
// and an mtime past the decay band, where the freshness prior floors to
// exactly zero - the score the semantic term alone produces.
const bare = rankResults(
{
keyword: [],
semantic: [{ chunkId: 1, documentId: 10, distance: 0.2 }],
hydrated: new Map<number, HydratedChunk>([[1, hyd(1, 10, OLD_MTIME)]]),
inboundLinkSources: new Map(),
tagsByDoc: new Map(),
},
BASE_OPTS,
);
expect(gated[0]!.score).toBeCloseTo(bare[0]!.score, 12);
});
test("the pinned layer is not gated", () => {
const inputs = {
...vectorOnlyInputs(),
pinnedDocIds: new Set<number>([10]),
};
const gated = rankResults(inputs, { ...BASE_OPTS, metadataBoostGate: true });
const b = gated[0]!.breakdown!;
expect(b.pinned).toBeGreaterThan(0);
expect(b.gate!.suppressedLayers).not.toContain("pinned");
});
test("one keyword hit leaves every boost fully intact", () => {
const inputs: RankerInputs = {
...vectorOnlyInputs(),
keyword: [{ chunkId: 1, documentId: 10, bm25: -2 }],
};
const gateOn = rankResults(inputs, { ...BASE_OPTS, metadataBoostGate: true });
const gateOff = rankResults(inputs, BASE_OPTS);
expect(gateOn.map((r) => r.score)).toEqual(gateOff.map((r) => r.score));
expect(gateOn[0]!.reasons).toEqual(gateOff[0]!.reasons);
const gate = gateOn[0]!.breakdown!.gate!;
expect(gate.active).toBe(false);
expect(gate.lexicalVote).toBe(true);
expect(gate.suppressedLayers).toEqual([]);
// The boost layers actually fired under the cast vote.
expect(gateOn[0]!.breakdown!.recency).toBeGreaterThan(0);
});
// βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
// Config resolution (default off; the key follows search_relational_arm_enabled)
// βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
let tmp: string;
let configPath: string;
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "osb-boost-gate-"));
configPath = join(tmp, "config.yaml");
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
});
test("search_metadata_boost_gate resolves, default off", () => {
writeFileSync(configPath, `vault: ${tmp}\n`);
const cfg = resolveSearchConfig({ vault: tmp, configPath });
expect(cfg.recall.metadataBoostGateEnabled).toBe(false);
});
test("search_metadata_boost_gate: true resolves onto the recall config", () => {
writeFileSync(configPath, `vault: ${tmp}\nsearch_metadata_boost_gate: true\n`);
const cfg = resolveSearchConfig({ vault: tmp, configPath });
expect(cfg.recall.metadataBoostGateEnabled).toBe(true);
});