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
/**
* 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"]);
});
});