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
/**
* Self-tuning reinforce ledger (Search & Recall Quality Suite): an
* explicit, opt-in signal that a memory proved useful. Events land one
* file per signal under Brain/search/reinforce/; the fold yields a
* bounded per-path strength that lifts named memories before the top_k
* cut. Surfaced-only frequency is never recorded, so it never boosts.
*/
import { join } from "node:path";
import { test, expect, beforeEach, afterEach, describe } from "bun:test";
import { existsSync, mkdirSync } from "node:fs";
import {
REINFORCE_BOOST_CAP,
applyReinforceBoost,
loadReinforceStrengths,
recordReinforce,
reinforceDir,
resetReinforce,
} from "../../../src/core/search/reinforce.ts";
import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";
import { indexVault } from "../../../src/core/search/indexer.ts";
import { search } from "../../../src/core/search/search.ts";
import type { BrainSearchResult } from "../../../src/core/search/types.ts";
let vault: string;
let cleanup: () => void;
beforeEach(() => {
({ vault, cleanup } = createTempVault("reinforce"));
// A legacy Brain/ tree: an unswitched machine (a vault without one is store-only).
mkdirSync(join(vault, "Brain"), { recursive: true });
});
afterEach(() => cleanup());
function result(path: string, score: number): BrainSearchResult {
return Object.freeze({
documentId: 1,
chunkId: 1,
path,
title: path,
content: "body",
startLine: 1,
endLine: 1,
score,
keywordScore: score,
semanticScore: 0,
linkBoost: 0,
recencyBoost: 0,
searchType: "keyword",
reasons: Object.freeze([]),
}) as BrainSearchResult;
}
describe("ledger", () => {
test("recording grows a path's strength; reset clears the derived state", () => {
expect(loadReinforceStrengths(vault).size).toBe(0);
recordReinforce(vault, ["a.md"], { nowMs: 1 });
recordReinforce(vault, ["a.md", "b.md"], { nowMs: 2 });
const strengths = loadReinforceStrengths(vault);
expect(strengths.get("a.md")).toBeGreaterThan(strengths.get("b.md")!);
expect(existsSync(reinforceDir(vault))).toBe(true);
resetReinforce(vault);
expect(loadReinforceStrengths(vault).size).toBe(0);
});
test("strength is bounded to [0,1] regardless of count", () => {
for (let i = 0; i < 50; i++) recordReinforce(vault, ["hot.md"], { nowMs: i + 1 });
expect(loadReinforceStrengths(vault).get("hot.md")).toBeLessThanOrEqual(1);
});
test("recording the identical event twice is idempotent", () => {
recordReinforce(vault, ["a.md"], { nowMs: 5 });
recordReinforce(vault, ["a.md"], { nowMs: 5 });
// One distinct event file -> the fold counts it once.
const a1 = loadReinforceStrengths(vault).get("a.md");
recordReinforce(vault, ["a.md"], { nowMs: 6 });
expect(loadReinforceStrengths(vault).get("a.md")).toBeGreaterThan(a1!);
});
});
describe("applyReinforceBoost", () => {
test("lifts a reinforced path above an unreinforced higher-scored one", () => {
const results = [result("top.md", 0.6), result("reinforced.md", 0.58)];
const boosted = applyReinforceBoost(results, new Map([["reinforced.md", 1]]));
expect(boosted[0]!.path).toBe("reinforced.md");
expect(
boosted
.find((r) => r.path === "reinforced.md")!
.reasons.some((x) => x.startsWith("reinforce:")),
).toBe(true);
});
test("boost is bounded by the cap and clamped to 1", () => {
const boosted = applyReinforceBoost([result("x.md", 0.99)], new Map([["x.md", 1]]));
expect(boosted[0]!.score).toBeLessThanOrEqual(1);
expect(boosted[0]!.score - 0.99).toBeLessThanOrEqual(REINFORCE_BOOST_CAP + 1e-9);
});
test("no reinforced paths -> input order and scores unchanged", () => {
const results = [result("a.md", 0.6), result("b.md", 0.4)];
const out = applyReinforceBoost(results, new Map());
expect(out.map((r) => r.path)).toEqual(["a.md", "b.md"]);
expect(out.map((r) => r.score)).toEqual([0.6, 0.4]);
});
});
describe("search integration", () => {
test("absent reinforce leaves the ranking byte-identical even with a populated ledger", async () => {
writeMd(vault, "a.md", "# A\n\nfox fox fox quick brown fox");
writeMd(vault, "b.md", "# B\n\na single fox mention among cats");
const cfg = makeConfig({ vault, dbPath: `${vault}/.idx.sqlite` });
await indexVault(cfg);
recordReinforce(vault, ["b.md"], { nowMs: 1 });
const base = await search(cfg, { query: "fox", limit: 10 });
// No reinforce key -> the ledger must not touch the result.
for (const r of base.results)
expect(r.reasons.some((x) => x.startsWith("reinforce:"))).toBe(false);
});
test("opt-in reinforce lifts a ledger-strong path with a reinforce reason", async () => {
writeMd(vault, "a.md", "# A\n\nfox fox fox quick brown fox");
writeMd(vault, "b.md", "# B\n\na single fox mention among cats");
const cfg = makeConfig({ vault, dbPath: `${vault}/.idx.sqlite` });
await indexVault(cfg);
for (let i = 0; i < 5; i++) recordReinforce(vault, ["b.md"], { nowMs: i + 1 });
const out = await search(cfg, { query: "fox", limit: 10, reinforce: [] });
const b = out.results.find((r) => r.path === "b.md");
expect(b).toBeDefined();
expect(b!.reasons.some((x) => x.startsWith("reinforce:"))).toBe(true);
});
});