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
/**
* Retrieval feedback loop (recall-trust-suite, Feature B).
*
* Explicit recall feedback is the operator (or a downstream agent)
* saying "this result helped" / "this result was noise". Each event is
* one small JSON file under `Brain/search/feedback/` — the same
* conflict-free one-file-per-signal pattern `Brain/inbox/` uses, so
* multi-device vaults never produce sync conflicts on a shared
* append-only file.
*
* Learned weights are a PURE FOLD over the event set: deterministic,
* order-insensitive, bounded to [LEARNED_WEIGHT_MIN, LEARNED_WEIGHT_MAX],
* and replayable from the events at any time. The derived file
* (`Brain/search/learned-weights.json`) is a cache of that fold —
* deleting it (reset) loses nothing. Operator configuration stays the
* base policy: the multipliers compose with the configured weights and
* cannot drift outside the documented bounds.
*
* Privacy: events carry an FNV-1a hash of the query, never the raw
* query text.
*
* A store-only machine (design D14 item 1) appends each event as a
* `search-feedback` ledger row instead of a file, and keeps the learned
* weights cache in device-local state ({@link learnedWeightsFile}).
*/
import { legacyVaultOf } from "../brain/no-vault.ts";
import {
mkdirSync,
readdirSync,
readFileSync,
rmSync,
statSync,
writeFileSync,
existsSync,
} from "node:fs";
import { dirname, join } from "node:path";
import { canonicalJson } from "../integrity/digest.ts";
import { machineStatePath } from "../state/machine-state.ts";
import type { DualWriteRecord } from "../store/dual-write.ts";
import { ledgerRowRecord } from "../store/dual-write-records.ts";
import { readLedgerRows } from "../store/read/ledger-rows.ts";
import { rowNamesPrivatePage } from "../store/reference-privacy.ts";
import { STORE_PARTITIONS } from "../store/constants.ts";
import { listShards } from "../store/shard-list.ts";
import { isStoreOnly } from "../store/store-only.ts";
import { partitionDir, resolveConfiguredStoreRoot } from "../store/store-paths.ts";
import { storeWrite } from "../store/store-write.ts";
import type { BrainSearchResult, ResolvedSearchConfig, WeightProfile } from "./types.ts";
import type { TransportReach } from "../graph/transport-reach.ts";
import { semanticLaneMissing, type RetrievalDegradationCode } from "./retrieval-trail.ts";
/** Lower bound for one learned per-layer multiplier. */
export const LEARNED_WEIGHT_MIN = 0.8;
/** Upper bound for one learned per-layer multiplier. */
export const LEARNED_WEIGHT_MAX = 1.2;
/** Step scale for the fold: full agreement moves a layer by ±this much. */
export const LEARNED_WEIGHT_STEP = 0.5;
/** Per-layer scoring contributions captured at retrieval time. */
export interface LayerContributions {
readonly keyword: number;
readonly semantic: number;
readonly entity: number;
readonly recency: number;
}
export interface RecallFeedbackEvent {
/** Unix-ms timestamp the feedback was given. */
readonly ts: number;
/** FNV-1a hash of the normalised query — never the raw query text. */
readonly queryHash: string;
/** Vault-relative path of the result being judged. */
readonly resultPath: string;
readonly verdict: "up" | "down";
readonly contributions: LayerContributions;
}
export interface LearnedWeights extends WeightProfile {
/** Number of events the fold consumed. */
readonly events: number;
/** ISO timestamp of the most recent event in the fold. */
readonly updatedAt: string | null;
}
export const NEUTRAL_LEARNED_WEIGHTS: LearnedWeights = Object.freeze({
keywordMul: 1,
semanticMul: 1,
entityMul: 1,
recencyMul: 1,
events: 0,
updatedAt: null,
});
export function feedbackDir(vault: string | null): string {
return join(legacyVaultOf(vault, "feedbackDir"), "Brain", "search", "feedback");
}
export function learnedWeightsPath(vault: string): string {
return join(vault, ...LEARNED_WEIGHTS_SEGMENTS);
}
/**
* Where this machine keeps the learned weights: {@link learnedWeightsPath}
* on an unswitched machine. The weights are a cache folded from the
* feedback events (design D14 item 11) that the migration drops, so a
* store-only machine keeps it in its device-local machine state
* (`machineStatePath`), at the same vault-relative path.
*/
export function learnedWeightsFile(vault: string | null): string {
return machineStatePath(vault, ...LEARNED_WEIGHTS_SEGMENTS);
}
/** Vault-relative segments of the folded learned weights. */
const LEARNED_WEIGHTS_SEGMENTS = ["Brain", "search", "learned-weights.json"] as const;
/** The store ledger of feedback events (FORMAT.md, the migration's ledgers). */
export const SEARCH_FEEDBACK_LEDGER = "search-feedback";
/**
* The store row of one feedback event: `private` when it names a private
* page or one that cannot be judged, else `private` when this machine
* holds it (the judged path says what the user looked for).
*/
function feedbackRowRecord(vault: string | null, event: RecallFeedbackEvent): DualWriteRecord {
return ledgerRowRecord(
SEARCH_FEEDBACK_LEDGER,
event,
rowNamesPrivatePage(vault, event) ? "private" : "private-when-held",
);
}
/** Deterministic FNV-1a 32-bit hash, hex-encoded (same family as query-plan). */
export function fnv1aHex(input: string): string {
let h = 0x811c9dc5;
for (let i = 0; i < input.length; i++) {
h ^= input.charCodeAt(i);
h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
}
return h.toString(16).padStart(8, "0");
}
function round6(x: number): number {
return Math.round(x * 1e6) / 1e6;
}
/**
* Read the per-layer contributions off a search result. Keyword,
* semantic, and recency are first-class fields; the entity layer is read
* from the structured `breakdown` the ranker emits. A result without a
* breakdown (a synthetic traversal expansion or relation-polarity
* pull-in) genuinely has no entity contribution, so 0 is correct - not a
* lossy fallback.
*/
export function contributionsFromResult(result: BrainSearchResult): LayerContributions {
return Object.freeze({
keyword: result.keywordScore,
semantic: result.semanticScore,
entity: result.breakdown?.entity ?? 0,
recency: result.recencyBoost,
});
}
/**
* Record one feedback event as its own file and refresh the derived
* learned-weights file. The filename derives from the timestamp plus a
* content hash, so recording the identical event twice is idempotent.
*/
export function recordRecallFeedback(vault: string | null, event: RecallFeedbackEvent): string {
// One `search-feedback` ledger row on a store-only machine (design D14
// item 1); an unswitched machine keeps its event file, with no dual write
// (format version 1 has none for this ledger; the migration imports the
// files).
let file: string;
if (isStoreOnly({ vault })) {
file = storeWrite(() => feedbackRowRecord(vault, event), { vault })[0]?.path ?? "";
} else {
const dir = feedbackDir(vault);
mkdirSync(dir, { recursive: true });
const body = JSON.stringify(event, null, 2) + "\n";
file = join(dir, `${event.ts}-${fnv1aHex(body)}.json`);
writeFileSync(file, body);
}
writeLearnedWeights(vault, computeLearnedWeights(loadFeedbackEvents(vault)));
return file;
}
export function loadFeedbackEvents(vault: string | null): RecallFeedbackEvent[] {
// The `search-feedback` ledger rows on a store-only machine. A file name
// made the same event recorded twice one file; in the store an identical
// row is counted once for the same reason.
return dedupeIdentical(
readLedgerRows<unknown>(SEARCH_FEEDBACK_LEDGER, loadLegacyFeedbackEvents, { vault }).filter(
isFeedbackEvent,
),
).toSorted((a, b) => a.ts - b.ts || a.resultPath.localeCompare(b.resultPath));
}
/** Rows with identical content, kept once (first occurrence). */
export function dedupeIdentical<T>(rows: ReadonlyArray<T>): T[] {
const seen = new Set<string>();
return rows.filter((row) => {
const key = canonicalJson(row);
if (seen.has(key)) return false;
seen.add(key);
return true;
});
}
/** Whether a parsed file or a store row is a well-formed feedback event. */
function isFeedbackEvent(parsed: unknown): parsed is RecallFeedbackEvent {
if (parsed === null || typeof parsed !== "object") return false;
const e = parsed as Partial<RecallFeedbackEvent>;
const c = e.contributions;
// Every layer must be a finite number: a malformed contributions
// object would otherwise feed NaN into the fold's totals.
const contributionsValid =
c !== undefined &&
c !== null &&
[c.keyword, c.semantic, c.entity, c.recency].every(
(v) => typeof v === "number" && Number.isFinite(v),
);
return (
typeof e.ts === "number" &&
(e.verdict === "up" || e.verdict === "down") &&
typeof e.resultPath === "string" &&
contributionsValid
);
}
function loadLegacyFeedbackEvents(vault: string): RecallFeedbackEvent[] {
const dir = feedbackDir(vault);
let files: string[];
try {
files = readdirSync(dir).filter((f) => f.endsWith(".json"));
} catch {
return [];
}
const out: RecallFeedbackEvent[] = [];
for (const f of files.toSorted()) {
try {
const parsed: unknown = JSON.parse(readFileSync(join(dir, f), "utf8"));
if (isFeedbackEvent(parsed)) out.push(parsed);
} catch {
// One malformed file never breaks the fold.
}
}
out.sort((a, b) => a.ts - b.ts || a.resultPath.localeCompare(b.resultPath));
return out;
}
/**
* The deterministic fold. Per layer: each event contributes its
* contribution share (this layer's value over the event's total) signed
* by the verdict; the layer's multiplier is
* `1 + STEP * netSignal / totalEvents`, clamped to the documented
* bounds. Order-insensitive by construction (a sum), and a layer that
* never contributed stays exactly 1.
*/
export function computeLearnedWeights(events: ReadonlyArray<RecallFeedbackEvent>): LearnedWeights {
if (events.length === 0) return NEUTRAL_LEARNED_WEIGHTS;
const net = { keyword: 0, semantic: 0, entity: 0, recency: 0 };
let counted = 0;
let latestTs = 0;
for (const e of events) {
const c = e.contributions;
const total = c.keyword + c.semantic + c.entity + c.recency;
if (total <= 0) continue; // zero-contribution events carry no layer signal
counted++;
const sign = e.verdict === "up" ? 1 : -1;
net.keyword += (sign * c.keyword) / total;
net.semantic += (sign * c.semantic) / total;
net.entity += (sign * c.entity) / total;
net.recency += (sign * c.recency) / total;
if (e.ts > latestTs) latestTs = e.ts;
}
if (counted === 0) {
return Object.freeze({ ...NEUTRAL_LEARNED_WEIGHTS, events: events.length });
}
const mul = (n: number): number => {
const raw = 1 + (LEARNED_WEIGHT_STEP * n) / counted;
return round6(Math.min(LEARNED_WEIGHT_MAX, Math.max(LEARNED_WEIGHT_MIN, raw)));
};
return Object.freeze({
keywordMul: mul(net.keyword),
semanticMul: mul(net.semantic),
entityMul: mul(net.entity),
recencyMul: mul(net.recency),
events: events.length,
updatedAt: latestTs > 0 ? new Date(latestTs).toISOString() : null,
});
}
export function writeLearnedWeights(vault: string | null, weights: LearnedWeights): void {
const path = learnedWeightsFile(vault);
mkdirSync(dirname(path), { recursive: true });
writeFileSync(path, JSON.stringify(weights, null, 2) + "\n");
}
/**
* On a store-only machine the weights file is a device-local cache of the
* `search-feedback` rows, which sync between devices: it is folded again
* when it is missing (right after the migration, which drops it) or when
* the ledger holds another number of events than it folded (rows another
* device recorded). Best effort: a failure leaves the cache as it is.
*/
function refreshStoreWeights(vault: string | null): void {
if (!isStoreOnly({ vault })) return;
try {
const path = learnedWeightsFile(vault);
// The ledger and the cache as they stand: unchanged since this process
// last refreshed them, nothing is read again (a query asks twice).
const stamp = refreshStamp(path);
if (stamp !== null && REFRESHED.get(path) === stamp) return;
const events = loadFeedbackEvents(vault);
let cached: number | null = null;
if (existsSync(path)) {
try {
const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<LearnedWeights>;
cached = typeof parsed.events === "number" ? parsed.events : null;
} catch {
// A cache cut short or damaged: folded again from the ledger.
cached = null;
}
} else if (events.length === 0) {
return;
}
if (cached !== events.length) writeLearnedWeights(vault, computeLearnedWeights(events));
const after = refreshStamp(path);
if (after !== null) REFRESHED.set(path, after);
} catch {
// The cache stays as it is.
}
}
/** Per weights file: the stamp of the ledger and the cache it was last refreshed at. */
const REFRESHED = new Map<string, string>();
/**
* The size and modification time of every `search-feedback` ledger shard
* of the configured store and of the cache file: a row recorded here or
* synced in from another device changes it. Null when it cannot be told
* (the store cannot be listed), and the refresh then reads the ledger.
*/
function refreshStamp(cachePath: string): string | null {
try {
const root = resolveConfiguredStoreRoot().root;
const parts: string[] = [];
for (const partition of STORE_PARTITIONS) {
const shards = listShards(partitionDir(root, partition), {
stream: "ledgers",
ledger: SEARCH_FEEDBACK_LEDGER,
});
for (const shard of shards) {
const stat = statSync(shard.path);
parts.push(`${shard.path}:${stat.size}:${stat.mtimeMs}`);
}
}
const cache = existsSync(cachePath) ? statSync(cachePath) : null;
parts.push(cache === null ? "no-cache" : `cache:${cache.size}:${cache.mtimeMs}`);
return parts.toSorted().join("|");
} catch {
return null;
}
}
export function readLearnedWeights(vault: string | null): LearnedWeights | null {
refreshStoreWeights(vault);
try {
const parsed = JSON.parse(readFileSync(learnedWeightsFile(vault), "utf8")) as LearnedWeights;
// All four multipliers must be finite numbers inside the bounds the
// fold itself clamps to — a partially-corrupt file must not feed NaN
// into the weight composition, and a hand-edited one must not inject a
// value `computeLearnedWeights` could never have produced. Zero deletes
// a lane and a negative value inverts its rank order under rank fusion,
// so the bound is the guard, not merely finiteness.
const muls = [parsed.keywordMul, parsed.semanticMul, parsed.entityMul, parsed.recencyMul];
const inBounds = (m: unknown): boolean =>
typeof m === "number" &&
Number.isFinite(m) &&
m >= LEARNED_WEIGHT_MIN &&
m <= LEARNED_WEIGHT_MAX;
if (!muls.every(inBounds)) return null;
if (typeof parsed.events !== "number") return null;
return parsed;
} catch {
return null;
}
}
/**
* Delete the derived weights file. The events stay — the fold can replay.
* On a store-only machine, where a missing cache is folded again on read,
* the reset leaves neutral weights over the events seen so far instead:
* the next feedback, here or synced in, folds them all again, as an
* unswitched machine does.
*/
export function resetLearnedWeights(vault: string | null): void {
if (isStoreOnly({ vault })) {
writeLearnedWeights(vault, {
...NEUTRAL_LEARNED_WEIGHTS,
events: loadFeedbackEvents(vault).length,
});
return;
}
rmSync(learnedWeightsFile(vault), { force: true });
}
/**
* Stable fingerprint of the learned-weights state for the query-cache
* key: "off" when no derived file exists, else a hash of its content.
*/
export function learnedWeightsFingerprint(vault: string | null): string {
refreshStoreWeights(vault);
const path = learnedWeightsFile(vault);
if (!existsSync(path)) return "off";
try {
return fnv1aHex(readFileSync(path, "utf8"));
} catch {
return "off";
}
}
/** True when every multiplier is exactly neutral (1.0). */
export function isNeutralLearnedWeights(w: WeightProfile): boolean {
return w.keywordMul === 1 && w.semanticMul === 1 && w.entityMul === 1 && w.recencyMul === 1;
}
/**
* Compose the intent profile with the learned multipliers. Both factors
* are bounded ([0.7, 1.4] and [0.8, 1.2]), so the product is naturally
* bounded in [0.56, 1.68]; no extra clamp is needed and the composition
* stays transparent (each factor is visible in diagnostics).
*/
export function composeWeightProfiles(
intent: WeightProfile | undefined,
learned: WeightProfile,
): WeightProfile {
const base = intent ?? { keywordMul: 1, semanticMul: 1, entityMul: 1, recencyMul: 1 };
return Object.freeze({
keywordMul: round6(base.keywordMul * learned.keywordMul),
semanticMul: round6(base.semanticMul * learned.semanticMul),
entityMul: round6(base.entityMul * learned.entityMul),
recencyMul: round6(base.recencyMul * learned.recencyMul),
});
}
/** Human/agent-readable summary of the non-neutral learned multipliers. */
export function learnedWeightsReason(w: WeightProfile): string {
const parts: string[] = [];
if (w.keywordMul !== 1) parts.push(`kw=${w.keywordMul.toFixed(3)}`);
if (w.semanticMul !== 1) parts.push(`sem=${w.semanticMul.toFixed(3)}`);
if (w.entityMul !== 1) parts.push(`ent=${w.entityMul.toFixed(3)}`);
if (w.recencyMul !== 1) parts.push(`rec=${w.recencyMul.toFixed(3)}`);
return `learned_weights: ${parts.join(" ")}`;
}
/**
* How deep the judged query is re-run before the verdict is scored.
* Hoisted so the depth is named where it is decided rather than inline.
*/
const FEEDBACK_RERUN_LIMIT = 50;
export interface CaptureRecallFeedbackInput {
readonly query: string;
readonly resultPath: string;
readonly verdict: "up" | "down";
/** Injected clock for deterministic tests. Defaults to Date.now(). */
readonly nowMs?: number;
/**
* How far this caller reached, minted by the transport
* (`src/core/graph/transport-reach.ts`).
*
* Load-bearing rather than decorative: {@link
* CaptureRecallFeedbackOutcome.resultFound} reports whether the judged
* path came back, so a re-run that saw a reserved page would answer
* "yes, it exists" to a caller the page is reserved against. Omitted
* resolves to the narrowest.
*/
readonly transportReach?: TransportReach;
}
export interface CaptureRecallFeedbackOutcome {
readonly file: string;
readonly event: RecallFeedbackEvent;
readonly learned: LearnedWeights;
/** False when the judged path was not in the re-ran result set. */
readonly resultFound: boolean;
/**
* Why the re-run narrowed, as the trail's codes; empty when nothing did.
* The re-run is gated like any search (a remote caller's unpriced query
* embed is refused), so the contributions it recorded describe the
* ranking this caller's own search produces, and this says when that
* ranking was keyword-only.
*/
readonly degraded: ReadonlyArray<RetrievalDegradationCode>;
}
/**
* Shared CLI/MCP capture path: re-run the query, read the judged
* result's per-layer contributions at retrieval time, and record the
* event. When the path is no longer in the result set the event is
* still recorded — with zero contributions, which the fold skips for
* layer signal but keeps in the audit trail. `search.ts` is imported
* lazily because it imports this module for ranking integration (the
* same lazy-import seam search.ts itself uses for the indexer).
*/
export async function captureRecallFeedback(
config: ResolvedSearchConfig,
input: CaptureRecallFeedbackInput,
): Promise<CaptureRecallFeedbackOutcome> {
const { search } = await import("./search.ts");
const outcome = await search(config, {
query: input.query,
limit: FEEDBACK_RERUN_LIMIT,
...(input.transportReach !== undefined ? { transportReach: input.transportReach } : {}),
});
const hit = outcome.results.find((r) => r.path === input.resultPath);
const degraded = Object.freeze((outcome.retrievalTrail?.degraded ?? []).map((d) => d.code));
// A re-run the semantic lane never reached (the spend gate, or any other
// stop under hybrid recall) scored the hit on a keyword-only pool, so its
// layer shares describe the degradation, not the result. The event keeps
// its audit row with zero contributions, which the fold skips, so the
// vault-wide weights never drift toward keyword while the gate holds.
const laneMissing = semanticLaneMissing(degraded);
const contributions: LayerContributions =
hit && !laneMissing
? contributionsFromResult(hit)
: Object.freeze({ keyword: 0, semantic: 0, entity: 0, recency: 0 });
const normalized = input.query.trim().replace(/\s+/gu, " ").toLowerCase();
const event: RecallFeedbackEvent = Object.freeze({
ts: input.nowMs ?? Date.now(),
queryHash: fnv1aHex(normalized),
resultPath: input.resultPath,
verdict: input.verdict,
contributions,
});
const file = recordRecallFeedback(config.vault, event);
const learned = readLearnedWeights(config.vault) ?? NEUTRAL_LEARNED_WEIGHTS;
return Object.freeze({ file, event, learned, resultFound: hit !== undefined, degraded });
}