Skip to content

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
7.4 KB
Raw Blame
/**
 * Opt-in self-tuning recall (link-recall-intelligence, t_ae973491):
 * a bounded parameter grid (pool multiplier, traversal depth, learned
 * weights, expansion) evaluated deterministically against the recall
 * benchmark; the winner persists to Brain/search/tuning.json and
 * search() consults it ONLY when self-tuning is enabled. Replayable:
 * delete the file and nothing else changes; out-of-bounds values are
 * ignored on read.
 */

import { test, expect, beforeEach, afterEach, describe } from "bun:test";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { defaultTuningGrid, tuneRecall } from "../../../src/core/search/tuning.ts";
import {
  applyTunedParameters,
  loadTunedParameters,
  resetTuning,
} from "../../../src/core/search/tuning-store.ts";
import { parseRecallBenchmarkDataset } from "../../../src/core/search/benchmark.ts";
import { indexVault } from "../../../src/core/search/indexer.ts";
import { search } from "../../../src/core/search/search.ts";
import { makeConfig } from "../../helpers/search-fixtures.ts";
import type { ResolvedSearchConfig } from "../../../src/core/search/types.ts";

const NOW = new Date("2026-06-05T12:00:00Z");

let vault: string;
let config: ResolvedSearchConfig;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-tuning-"));
  mkdirSync(join(vault, "Brain"), { recursive: true });
  config = makeConfig({ vault, dbPath: join(vault, "index.sqlite") });
});

afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
});

const DATASET = parseRecallBenchmarkDataset({
  queries: [
    { id: "canary", query: "canary rollout", expected: ["canary.md"] },
    { id: "stopword", query: "the nightly backup", expected: ["backup.md"] },
  ],
});

// "the" is deliberately seeded into 2 of the 3 notes (canary, other) but
// NOT into backup.md. It is therefore corpus-common (>= 50% document
// frequency) and dropped from the implicit-AND lex lane by the
// language-agnostic, DF-driven common-token filter - which is what lets
// the "the nightly backup" query reach backup.md only WITH expansion.
function writeNotes(): void {
  writeFileSync(
    join(vault, "canary.md"),
    "# Canary rollout\n\nShip the first instance, observe, then expand the rollout gradually.\n",
  );
  writeFileSync(
    join(vault, "backup.md"),
    "# Nightly backup\n\nSnapshot databases every night, verify checksums offsite.\n",
  );
  writeFileSync(
    join(vault, "other.md"),
    "# Other\n\nNothing in the list here is relevant to the task.\n",
  );
}

describe("grid + apply", () => {
  test("the default grid is bounded, stable, and starts at the defaults", () => {
    const grid = defaultTuningGrid();
    expect(grid).toHaveLength(24);
    expect(grid[0]).toEqual({
      poolMultiplier: 3,
      traversalDepth: 1,
      learnedWeights: false,
      expansion: false,
    });
    expect(defaultTuningGrid()).toEqual(grid);
  });

  test("applyTunedParameters overrides recall knobs and disarms recursion", () => {
    const tuned = applyTunedParameters(config, {
      poolMultiplier: 5,
      traversalDepth: 2,
      learnedWeights: true,
      expansion: false,
    });
    expect(tuned.recall.poolMultiplier).toBe(5);
    expect(tuned.recall.maxHops).toBe(2);
    expect(tuned.recall.learnedWeightsEnabled).toBe(true);
    expect(tuned.recall.selfTuningEnabled).toBe(false);
    // The base config is untouched.
    expect(config.recall.poolMultiplier).toBe(3);
  });
});

describe("tuneRecall", () => {
  test("evaluates the grid, persists the winner, and is deterministic", async () => {
    writeNotes();
    await indexVault(config);
    const grid = [
      { poolMultiplier: 3, traversalDepth: 1, learnedWeights: false, expansion: false },
      { poolMultiplier: 3, traversalDepth: 1, learnedWeights: false, expansion: true },
    ];
    const first = await tuneRecall(config, DATASET, { grid, now: NOW });
    // The stopword query only hits with expansion - it must win.
    expect(first.chosen.expansion).toBe(true);
    expect(first.evaluated).toHaveLength(2);

    const raw = JSON.parse(readFileSync(join(vault, "Brain", "search", "tuning.json"), "utf8")) as {
      schema: string;
      chosen: { expansion: boolean };
      dataset_hash: string;
    };
    expect(raw.schema).toBe("o2b.tuning.v1");
    expect(raw.chosen.expansion).toBe(true);

    const second = await tuneRecall(config, DATASET, { grid, now: NOW });
    expect(second.chosen).toEqual(first.chosen);
    expect(second.evaluated).toEqual(first.evaluated);
  });

  test("loadTunedParameters round-trips and rejects out-of-bounds values", async () => {
    writeNotes();
    await indexVault(config);
    const grid = [
      { poolMultiplier: 4, traversalDepth: 2, learnedWeights: false, expansion: false },
    ];
    await tuneRecall(config, DATASET, { grid, now: NOW });
    expect(loadTunedParameters(vault)).toEqual(grid[0]!);

    const path = join(vault, "Brain", "search", "tuning.json");
    const tampered = JSON.parse(readFileSync(path, "utf8")) as {
      chosen: { poolMultiplier: number };
    };
    tampered.chosen.poolMultiplier = 99;
    writeFileSync(path, JSON.stringify(tampered));
    expect(loadTunedParameters(vault)).toBeNull();

    writeFileSync(path, "{not json");
    expect(loadTunedParameters(vault)).toBeNull();
  });

  test("resetTuning removes the persisted state", async () => {
    writeNotes();
    await indexVault(config);
    await tuneRecall(config, DATASET, {
      grid: [{ poolMultiplier: 3, traversalDepth: 1, learnedWeights: false, expansion: false }],
      now: NOW,
    });
    expect(resetTuning(vault)).toBe(true);
    expect(existsSync(join(vault, "Brain", "search", "tuning.json"))).toBe(false);
    expect(loadTunedParameters(vault)).toBeNull();
    expect(resetTuning(vault)).toBe(false);
  });
});

describe("search() under self-tuning", () => {
  test("opt-out ignores a persisted tuning file entirely", async () => {
    writeNotes();
    await indexVault(config);
    mkdirSync(join(vault, "Brain", "search"), { recursive: true });
    writeFileSync(
      join(vault, "Brain", "search", "tuning.json"),
      JSON.stringify({
        schema: "o2b.tuning.v1",
        chosen: { poolMultiplier: 5, traversalDepth: 2, learnedWeights: false, expansion: true },
      }),
    );
    // selfTuningEnabled is false in the default test config.
    const outcome = await search(config, { query: "the nightly backup" });
    expect(outcome.results).toHaveLength(0);
  });

  test("opt-in applies the tuned expansion to a bare query", async () => {
    writeNotes();
    await indexVault(config);
    mkdirSync(join(vault, "Brain", "search"), { recursive: true });
    writeFileSync(
      join(vault, "Brain", "search", "tuning.json"),
      JSON.stringify({
        schema: "o2b.tuning.v1",
        chosen: { poolMultiplier: 3, traversalDepth: 1, learnedWeights: false, expansion: true },
      }),
    );
    const tunedConfig = makeConfig({
      vault,
      dbPath: join(vault, "index.sqlite"),
      selfTuningEnabled: true,
    });
    const outcome = await search(tunedConfig, { query: "the nightly backup" });
    expect(outcome.results.some((r) => r.path === "backup.md")).toBe(true);

    // An explicit expand: false wins over the tuned default.
    const explicit = await search(tunedConfig, { query: "the nightly backup", expand: false });
    expect(explicit.results).toHaveLength(0);
  });
});