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
10.1 KB
Raw Blame
/**
 * Dashboard-ready metrics sink (link-recall-intelligence, Task 1):
 * one append-only schema-versioned JSONL file per surface under
 * `Brain/metrics/`, the stable on-disk contract a dashboard plugin
 * reads without importing OSB internals. Envelope mirrors the
 * continuity-record discipline: additive-optional fields keep the
 * version, renames/removals bump it.
 */

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

import {
  appendMetric,
  listMetrics,
  METRICS_SCHEMA_VERSION,
  MetricSurfaceError,
  metricsDir,
} from "../../../src/core/brain/metrics.ts";
import { useUnshardedLegacyLog } from "../../helpers/device-id.ts";
import { CLI_SPAWN_BUDGET_MS } from "../../helpers/cli-timeout.ts";

// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

// The legacy day log and ledgers are read under their un-sharded names.
useUnshardedLegacyLog();

const NOW = "2026-06-05T10:00:00Z";

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-metrics-"));
  // A legacy Brain/ tree: an unswitched machine (a vault without one is store-only).
  mkdirSync(join(vault, "Brain"), { recursive: true });
});

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

describe("appendMetric", () => {
  test("waits out a lock another writer briefly holds instead of losing the sample", async () => {
    appendMetric(vault, { surface: "recall_benchmark", runAt: NOW, payload: { n: 1 } });
    const file = join(metricsDir(vault), readdirSync(metricsDir(vault))[0]!);
    const marker = join(vault, "holder-ready");
    const go = join(vault, "parent-appending");
    const child = join(vault, "holder.ts");
    // The holder keeps the lock until the parent says it is about to
    // append, and only then lets go after a short hold - so the append
    // always starts against a held lock, however slowly either side runs.
    writeFileSync(
      child,
      [
        `import { acquireLockSync } from ${JSON.stringify(join(import.meta.dir, "../../../src/core/brain/sync-lockfile.ts"))};`,
        `const { existsSync, writeFileSync } = require("node:fs");`,
        "const [target, marker, go] = process.argv.slice(2);",
        "const h = acquireLockSync(target);",
        `writeFileSync(marker, "held");`,
        "while (!existsSync(go)) Bun.sleepSync(5);",
        "Bun.sleepSync(250);",
        "h.release();",
      ].join("\n"),
      "utf8",
    );
    const proc = Bun.spawn(["bun", child, file, marker, go], { stdout: "pipe", stderr: "pipe" });
    try {
      const until = Date.now() + 20_000;
      while (!existsSync(marker)) {
        if (Date.now() > until) throw new Error("the holder never took the lock");
        // oxlint-disable-next-line no-await-in-loop -- polling the child's progress
        await Bun.sleep(5);
      }
      writeFileSync(go, "now");
      appendMetric(vault, { surface: "recall_benchmark", runAt: NOW, payload: { n: 2 } });
      expect(listMetrics(vault, { surface: "recall_benchmark" })).toHaveLength(2);
    } finally {
      // Never leave the holder waiting on a marker an early failure skipped.
      if (!existsSync(go)) writeFileSync(go, "abort");
      await proc.exited;
    }
  });

  test("writes one schema-stamped line per call into the surface file", () => {
    appendMetric(vault, { surface: "recall_benchmark", runAt: NOW, payload: { mrr: 0.91 } });
    appendMetric(vault, {
      surface: "recall_benchmark",
      runAt: "2026-06-05T11:00:00Z",
      payload: { mrr: 0.93 },
    });
    const raw = readFileSync(join(vault, "Brain", "metrics", "recall_benchmark.jsonl"), "utf8");
    const lines = raw.split("\n").filter((l) => l.trim().length > 0);
    expect(lines).toHaveLength(2);
    expect(JSON.parse(lines[0]!)).toEqual({
      schema: METRICS_SCHEMA_VERSION,
      surface: "recall_benchmark",
      run_at: NOW,
      payload: { mrr: 0.91 },
    });
  });

  test("surfaces are isolated files", () => {
    appendMetric(vault, { surface: "index", runAt: NOW, payload: { files: 3 } });
    appendMetric(vault, { surface: "communities", runAt: NOW, payload: { count: 2 } });
    expect(readFileSync(join(vault, "Brain", "metrics", "index.jsonl"), "utf8")).toContain(
      '"files":3',
    );
    expect(readFileSync(join(vault, "Brain", "metrics", "communities.jsonl"), "utf8")).toContain(
      '"count":2',
    );
  });

  test("rejects surface names outside [a-z][a-z0-9_]*", () => {
    for (const bad of ["", "Index", "9lives", "a-b", "a b", "a/../b", "x".repeat(65)]) {
      expect(() => appendMetric(vault, { surface: bad, runAt: NOW, payload: {} })).toThrow(
        MetricSurfaceError,
      );
    }
  });

  test("rejects a runAt that is not an ISO timestamp", () => {
    expect(() =>
      appendMetric(vault, { surface: "index", runAt: "yesterday", payload: {} }),
    ).toThrow(/run_at/);
  });
});

describe("listMetrics", () => {
  test("missing dir or file reads as empty", () => {
    expect(listMetrics(vault)).toEqual([]);
    expect(listMetrics(vault, { surface: "index" })).toEqual([]);
  });

  test("newest-first per surface with since and limit filters", () => {
    appendMetric(vault, { surface: "index", runAt: "2026-06-01T00:00:00Z", payload: { n: 1 } });
    appendMetric(vault, { surface: "index", runAt: "2026-06-03T00:00:00Z", payload: { n: 2 } });
    appendMetric(vault, { surface: "index", runAt: "2026-06-05T00:00:00Z", payload: { n: 3 } });
    const all = listMetrics(vault, { surface: "index" });
    expect(all.map((r) => r.payload["n"])).toEqual([3, 2, 1]);
    const since = listMetrics(vault, { surface: "index", since: "2026-06-02T00:00:00Z" });
    expect(since.map((r) => r.payload["n"])).toEqual([3, 2]);
    const limited = listMetrics(vault, { surface: "index", limit: 1 });
    expect(limited.map((r) => r.payload["n"])).toEqual([3]);
  });

  test("without a surface filter, merges every surface newest-first", () => {
    appendMetric(vault, { surface: "index", runAt: "2026-06-01T00:00:00Z", payload: { n: 1 } });
    appendMetric(vault, {
      surface: "bridge_discovery",
      runAt: "2026-06-04T00:00:00Z",
      payload: { n: 2 },
    });
    appendMetric(vault, { surface: "index", runAt: "2026-06-05T00:00:00Z", payload: { n: 3 } });
    const all = listMetrics(vault);
    expect(all.map((r) => r.payload["n"])).toEqual([3, 2, 1]);
    expect(all.map((r) => r.surface)).toEqual(["index", "bridge_discovery", "index"]);
  });

  test("a torn or malformed line never breaks the read", () => {
    appendMetric(vault, { surface: "index", runAt: NOW, payload: { n: 1 } });
    const path = join(vault, "Brain", "metrics", "index.jsonl");
    writeFileSync(path, readFileSync(path, "utf8") + "{not json\n[]\n");
    const records = listMetrics(vault, { surface: "index" });
    expect(records).toHaveLength(1);
    expect(records[0]!.payload["n"]).toBe(1);
  });

  test("ignores non-jsonl files in the metrics dir", () => {
    mkdirSync(join(vault, "Brain", "metrics"), { recursive: true });
    writeFileSync(join(vault, "Brain", "metrics", "README.md"), "# not a metric\n");
    appendMetric(vault, { surface: "index", runAt: NOW, payload: { n: 1 } });
    expect(listMetrics(vault)).toHaveLength(1);
  });
});

/**
 * Per-device shards (who-wrote-what, Task B / t_1814b9bf). Two machines
 * running the same instrumented pass must not append to one surface file.
 */
describe("metrics per-device shards", () => {
  const savedEnv: Record<string, string | undefined> = {};
  let configHome: string;

  function metricsPath(name: string): string {
    return join(vault, "Brain", "metrics", name);
  }

  beforeEach(() => {
    configHome = mkdtempSync(join(tmpdir(), "o2b-metrics-cfg-"));
    const configPath = join(configHome, "config.yaml");
    savedEnv["OPEN_SECOND_BRAIN_CONFIG"] = process.env["OPEN_SECOND_BRAIN_CONFIG"];
    savedEnv["O2B_DEVICE_ID"] = process.env["O2B_DEVICE_ID"];
    process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
    delete process.env["O2B_DEVICE_ID"];
    writeFileSync(configPath, `vault: ${vault}\ndevice_id: "testdev1"\n`, "utf8");
  });

  afterEach(() => {
    rmSync(configHome, { recursive: true, force: true });
    for (const key of ["OPEN_SECOND_BRAIN_CONFIG", "O2B_DEVICE_ID"]) {
      const value = savedEnv[key];
      if (value === undefined) delete process.env[key];
      else process.env[key] = value;
    }
  });

  function line(runAt: string, n: number): string {
    return `${JSON.stringify({ schema: METRICS_SCHEMA_VERSION, surface: "index", run_at: runAt, payload: { n } })}\n`;
  }

  test("a device with an id writes its own shard and never the bare file", () => {
    appendMetric(vault, { surface: "index", runAt: NOW, payload: { n: 1 } });
    expect(existsSync(metricsPath("index.testdev1.jsonl"))).toBe(true);
    expect(existsSync(metricsPath("index.jsonl"))).toBe(false);
  });

  test("the reader merges the bare file and every device shard, newest first", () => {
    mkdirSync(join(vault, "Brain", "metrics"), { recursive: true });
    writeFileSync(metricsPath("index.jsonl"), line("2026-06-05T10:00:00Z", 1));
    writeFileSync(metricsPath("index.devb.jsonl"), line("2026-06-05T10:00:02Z", 3));
    writeFileSync(metricsPath("index.testdev1.jsonl"), line("2026-06-05T10:00:01Z", 2));
    expect(listMetrics(vault, { surface: "index" }).map((r) => r.payload["n"])).toEqual([3, 2, 1]);
  });

  test("a sync-conflict copy is not a shard and is never merged", () => {
    mkdirSync(join(vault, "Brain", "metrics"), { recursive: true });
    writeFileSync(metricsPath("index.testdev1.jsonl"), line("2026-06-05T10:00:01Z", 2));
    writeFileSync(
      metricsPath("index.sync-conflict-20260605-120000-ABCDEFG.jsonl"),
      line("2026-06-05T10:00:00Z", 99),
    );
    expect(listMetrics(vault, { surface: "index" }).map((r) => r.payload["n"])).toEqual([2]);
  });

  test("an unfiltered listing discovers a surface that only has device shards", () => {
    appendMetric(vault, { surface: "bridge_discovery", runAt: NOW, payload: { n: 7 } });
    expect(listMetrics(vault).map((r) => r.surface)).toEqual(["bridge_discovery"]);
  });
});