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
/**
* CLI tests for `o2b brain explorer`.
*
* Covers the two surfaces (live HTTP + static export) plus the
* documented error paths. The live server is exercised via subprocess
* spawn so the SIGINT shutdown path is verified end-to-end.
*/
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import {
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
rmSync,
symlinkSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { collectExplorerData, renderExportedHtml } from "../../src/core/brain/explorer.ts";
import { moveToRetired, writePreference } from "../../src/core/brain/preference.ts";
import { BRAIN_RETIRED_REASON } from "../../src/core/brain/types.ts";
import { REDACTION_PLACEHOLDER } from "../../src/core/redactor.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";
import { runCli } from "../helpers/run-cli.ts";
import { fakeCredential } from "../helpers/fake-credentials.ts";
// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);
/**
* A vendor-prefixed credential shape, synthesised for this test. Caught by
* shape rather than by a word list, which is why an obviously fake body is
* enough to prove the boundary runs.
*/
const FAKE_VENDOR_TOKEN = fakeCredential("sk-", "live-FAKEEXAMPLE0000111122223333");
let tmp: string;
let vault: string;
let config: string;
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-explorer-cli-"));
vault = join(tmp, "vault");
config = join(tmp, "config.yaml");
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
});
async function bootstrap(): Promise<void> {
const init = await runCli(["init", "--vault", vault, "--name", "Test"], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(init.returncode).toBe(0);
const brainInit = await runCli(["brain", "init", "--vault", vault], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(brainInit.returncode).toBe(0);
}
function seedOnePref(): void {
writePreference(vault, {
slug: "explorer-seed",
topic: "explorer-seed",
principle: "Explorer seed principle",
created_at: "2026-05-01T00:00:00Z",
unconfirmed_until: "2026-05-08T00:00:00Z",
status: "confirmed",
evidenced_by: ["[[sig-2026-05-01-explorer-seed]]"],
confirmed_at: "2026-05-02T00:00:00Z",
applied_count: 2,
violated_count: 0,
last_evidence_at: "2026-05-02T00:00:00Z",
confidence: "high",
confidence_value: 0.8,
pinned: false,
});
}
/** Pick a random high port to dodge collisions on shared build hosts. */
/**
* Read `stream` until `marker` appears or the stream ends (the process
* exited). Returns what was read either way, so a failure can show it.
*/
async function readUntil(
stream: ReadableStream<Uint8Array>,
marker: string,
): Promise<{ readonly found: boolean; readonly text: string }> {
const reader = stream.getReader();
const decoder = new TextDecoder();
let text = "";
try {
while (!text.includes(marker)) {
// Each read waits on the child's next write: there is nothing to batch.
// oxlint-disable-next-line no-await-in-loop
const chunk = await reader.read();
if (chunk.done) return { found: false, text };
text += decoder.decode(chunk.value, { stream: true });
}
return { found: true, text };
} finally {
reader.releaseLock();
}
}
/**
* A port the system has just handed out as free (bound to port 0 and let
* go), not a guess: a fixed or random high port can sit in a range the
* host reserves (Windows excludes whole port blocks) or be taken by
* another job on a shared runner.
*/
function freePort(): number {
const probe = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: () => new Response("") });
const port = probe.port as number;
void probe.stop(true);
return port;
}
/**
* Start the live explorer for the test vault and wait until it listens.
* A port another process took between `freePort` and the bind is retried
* on a new one, a few times; any other failure to start is thrown with
* what the child printed.
*/
async function startExplorer(
configPath: string,
): Promise<{ readonly proc: ReturnType<typeof Bun.spawn>; readonly port: number }> {
for (let attempt = 0; ; attempt++) {
const port = freePort();
const proc = Bun.spawn(
[
"bun",
"run",
"src/cli/main.ts",
"brain",
"explorer",
"--vault",
vault,
"--port",
String(port),
],
{
cwd: process.cwd(),
env: { ...process.env, OPEN_SECOND_BRAIN_CONFIG: configPath },
stdout: "pipe",
stderr: "pipe",
},
);
// Each attempt waits on the child before the next: nothing to batch.
// oxlint-disable-next-line no-await-in-loop
const banner = await readUntil(proc.stdout as ReadableStream<Uint8Array>, "Live explorer at ");
if (banner.found) return { proc, port };
// oxlint-disable-next-line no-await-in-loop
const stderr = await new Response(proc.stderr as ReadableStream<Uint8Array>).text();
// oxlint-disable-next-line no-await-in-loop
await proc.exited;
if (attempt < 4 && /in use/i.test(stderr)) continue;
throw new Error(`explorer exited before listening:\n${banner.text}${stderr}`);
}
}
describe("o2b brain explorer --help", () => {
test("prints both modes", async () => {
const r = await runCli(["brain", "explorer", "--help"]);
expect(r.returncode).toBe(0);
expect(r.stdout).toContain("brain explorer");
expect(r.stdout).toContain("--export");
expect(r.stdout).toContain("--port");
});
});
describe("o2b brain explorer --export", () => {
test("creates the file and prints the node count", async () => {
await bootstrap();
seedOnePref();
const out = join(tmp, "brain.html");
const r = await runCli(["brain", "explorer", "--vault", vault, "--export", out], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(r.returncode).toBe(0);
expect(r.stdout).toContain("exported");
expect(existsSync(out)).toBe(true);
const body = readFileSync(out, "utf8");
expect(body.includes("__GRAPH_JSON__")).toBe(false);
const match = body.match(
/<script type="application\/json" id="brain-data">([\s\S]+?)<\/script>/,
);
const parsed = JSON.parse(match![1]!);
expect(parsed.nodes.length).toBe(1);
expect(parsed.nodes[0].id).toBe("pref-explorer-seed");
// The console sections travel with the template; on a static export
// they state that the live routes are unreachable instead of firing
// fetches that can only fail against a file path.
expect(body).toContain('id="counts-body"');
expect(body).toContain('id="ops-body"');
expect(body).toContain("static export");
});
test("the exported graph goes through the shared egress guard", async () => {
// The eighth egress site. Every other export path scans its bytes;
// this one wrote the preference graph - principles verbatim - to an
// operator-named path with no scan at all.
await bootstrap();
writePreference(vault, {
slug: "secret-leak",
topic: "secret-leak",
principle: `Always deploy with OPENAI_API_KEY=${FAKE_VENDOR_TOKEN} set`,
created_at: "2026-05-01T00:00:00Z",
unconfirmed_until: "2026-05-08T00:00:00Z",
status: "confirmed",
evidenced_by: ["[[sig-2026-05-01-secret-leak]]"],
confirmed_at: "2026-05-02T00:00:00Z",
applied_count: 1,
violated_count: 0,
last_evidence_at: "2026-05-02T00:00:00Z",
confidence: "high",
confidence_value: 0.8,
pinned: false,
});
const out = join(tmp, "brain.html");
const r = await runCli(["brain", "explorer", "--vault", vault, "--export", out], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(r.returncode).toBe(0);
const body = readFileSync(out, "utf8");
expect(body).not.toContain(FAKE_VENDOR_TOKEN);
expect(body).toContain(REDACTION_PLACEHOLDER);
// stdout stays the parseable line it was; the notice goes to stderr.
expect(r.stdout).toContain("exported");
expect(r.stderr).toContain("no longer matches the vault byte for byte");
});
test("a preference that cannot be parsed refuses the export by name", async () => {
// An export that omits a rule reads identically to a vault that never
// had it, so the graph is not written at all.
await bootstrap();
seedOnePref();
writeFileSync(join(vault, "Brain", "preferences", "pref-broken.md"), "no frontmatter here\n");
const out = join(tmp, "brain.html");
const r = await runCli(["brain", "explorer", "--vault", vault, "--export", out], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(r.returncode).toBe(1);
expect(r.stderr).toContain("pref-broken.md");
expect(existsSync(out)).toBe(false);
});
test("refuses to overwrite without --force", async () => {
await bootstrap();
seedOnePref();
const out = join(tmp, "brain.html");
writeFileSync(out, "pre-existing");
const r = await runCli(["brain", "explorer", "--vault", vault, "--export", out], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(r.returncode).toBe(1);
expect(r.stderr).toContain("exists");
expect(readFileSync(out, "utf8")).toBe("pre-existing");
});
test("overwrites with --force", async () => {
await bootstrap();
seedOnePref();
const out = join(tmp, "brain.html");
writeFileSync(out, "pre-existing");
const r = await runCli(["brain", "explorer", "--vault", vault, "--export", out, "--force"], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(r.returncode).toBe(0);
expect(readFileSync(out, "utf8").startsWith("<!doctype html>")).toBe(true);
});
test("invalid --port values exit 1", async () => {
await bootstrap();
for (const port of ["garbage", "123abc"]) {
const r = await runCli(["brain", "explorer", "--vault", vault, "--port", port], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(r.returncode).toBe(1);
expect(r.stderr).toContain("invalid --port");
}
});
});
describe("o2b brain explorer --export privacy denials", () => {
/**
* Hand-add an informal privacy marker the same way an operator does:
* a user-tier frontmatter line on the node's file.
*/
function stampMarker(relPath: string, line: string): void {
const abs = join(vault, relPath);
writeFileSync(abs, readFileSync(abs, "utf8").replace(/^---\n/, `---\n${line}\n`));
}
function seedReservedPref(): void {
writePreference(vault, {
slug: "reserved",
topic: "reserved",
principle: "Reserved principle",
created_at: "2026-05-01T00:00:00Z",
unconfirmed_until: "2026-05-08T00:00:00Z",
status: "confirmed",
evidenced_by: ["[[sig-2026-05-01-reserved]]"],
confirmed_at: "2026-05-02T00:00:00Z",
applied_count: 1,
violated_count: 0,
last_evidence_at: "2026-05-02T00:00:00Z",
confidence: "high",
confidence_value: 0.8,
pinned: false,
});
stampMarker("Brain/preferences/pref-reserved.md", "access: private");
}
test("a reserved preference is absent from the HTML and named on stderr", async () => {
await bootstrap();
seedOnePref();
seedReservedPref();
const out = join(tmp, "brain.html");
const r = await runCli(["brain", "explorer", "--vault", vault, "--export", out], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(r.returncode).toBe(0);
const body = readFileSync(out, "utf8");
expect(body).not.toContain("pref-reserved");
expect(body).not.toContain("Reserved principle");
// The unmarked rule still ships.
expect(body).toContain("pref-explorer-seed");
// The omission is disclosed on stderr, with the key that denied it.
expect(r.stderr).toContain("pref-reserved");
expect(r.stderr).toContain("(access)");
expect(r.stderr).toContain("left out");
// stderr only: the HTML names the omission as absence, not prose.
expect(r.stdout).not.toContain("left out");
// The count answers for what was written: one node exported, one
// named as withheld on stderr.
expect(r.stdout).toContain("exported 1 ");
});
test("a reserved retired entry is absent too", async () => {
await bootstrap();
seedOnePref();
writePreference(vault, {
slug: "old-reserved",
topic: "old-reserved",
principle: "Old reserved principle",
created_at: "2026-05-01T00:00:00Z",
unconfirmed_until: "2026-05-08T00:00:00Z",
status: "confirmed",
evidenced_by: ["[[sig-2026-05-01-old-reserved]]"],
confirmed_at: "2026-05-02T00:00:00Z",
applied_count: 1,
violated_count: 0,
last_evidence_at: "2026-05-02T00:00:00Z",
confidence: "high",
confidence_value: 0.8,
pinned: false,
});
const deadPath = join(vault, "Brain", "preferences", "pref-old-reserved.md");
moveToRetired(vault, deadPath, BRAIN_RETIRED_REASON.staleNoEvidence, {
now: new Date("2026-05-10T00:00:00Z"),
retired_by: "[[Brain/log/2026-05-10]]",
});
stampMarker("Brain/retired/ret-old-reserved.md", "sensitivity: confidential");
const out = join(tmp, "brain.html");
const r = await runCli(["brain", "explorer", "--vault", vault, "--export", out], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(r.returncode).toBe(0);
const body = readFileSync(out, "utf8");
expect(body).not.toContain("ret-old-reserved");
expect(body).not.toContain("Old reserved principle");
expect(r.stderr).toContain("ret-old-reserved");
expect(r.stderr).toContain("(sensitivity)");
});
test("an unmarked vault exports byte-identically to the shared collector's rendering", async () => {
await bootstrap();
seedOnePref();
const out = join(tmp, "brain.html");
const r = await runCli(["brain", "explorer", "--vault", vault, "--export", out], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(r.returncode).toBe(0);
// No reservation held anything back, so the file is exactly what the
// pre-denial pipeline rendered - the denial pass changed no bytes.
const stripTimestamp = (s: string): string =>
s.replace(/"generated_at":"[^"]*"/, '"generated_at":"X"');
expect(stripTimestamp(readFileSync(out, "utf8"))).toBe(
stripTimestamp(renderExportedHtml(collectExplorerData(vault))),
);
expect(r.stderr).not.toContain("left out");
});
});
describe("o2b brain explorer (live) store group", () => {
test("a failed lock probe keeps the errno and drops the host path from the reason", async () => {
await bootstrap();
seedOnePref();
// A lock path that cannot even be stat'd: a symlink loop where the
// lock directory would sit - the throw shape whose fs message
// embeds the full resolved host path.
const { resolveSearchConfig } = await import("../../src/core/search/index.ts");
const lockPath = `${resolveSearchConfig({ vault, configPath: config }).dbPath}.lock`;
mkdirSync(dirname(lockPath), { recursive: true });
symlinkSync(lockPath, lockPath);
const { proc, port } = await startExplorer(config);
try {
const res = await fetch(`http://127.0.0.1:${port}/status.json`);
expect(res.ok).toBe(true);
const status = JSON.parse(await res.text()) as {
store: {
writerLock: string;
writerLockPath: string | null;
writerLockReason: string | null;
};
};
// The path is withheld from the field AND from the reason: the
// browser surface answers below local reach for the whole store
// group, not for one field of it. The errno stays - "could not
// find out, and here is why".
expect(status.store.writerLock).toBe("unknown");
expect(status.store.writerLockPath).toBeNull();
expect(status.store.writerLockReason).toContain("ELOOP");
expect(status.store.writerLockReason).not.toContain(lockPath);
expect(status.store.writerLockReason).not.toContain(tmpdir());
} finally {
proc.kill("SIGINT");
await proc.exited;
}
}, 20000);
});
describe("o2b brain explorer (live)", () => {
test(
"binds to 127.0.0.1, serves all four routes, shuts down on SIGINT",
async () => {
await bootstrap();
seedOnePref();
// Spawned so the test can poll the server and send SIGINT. It waits
// for the CLI to say it is listening, not for a clock: the line is
// printed only once the server is bound, so the first fetch cannot
// race the boot (a fixed poll lost to a cold start on the Windows
// runner, and WSL's mirrored loopback drops a SYN to an unbound port
// instead of refusing it).
const { proc, port } = await startExplorer(config);
try {
const r = await fetch(`http://127.0.0.1:${port}/`);
expect(r.ok).toBe(true);
const mainBody = await r.text();
const d = await fetch(`http://127.0.0.1:${port}/data.json`);
const dataBody = await d.text();
expect(mainBody).toContain("Brain Explorer");
expect(mainBody.includes("__GRAPH_JSON__")).toBe(false);
const parsed = JSON.parse(dataBody);
expect(parsed.nodes.length).toBe(1);
// The counts and ops sections fetch the two console routes
// client-side, in the page's own vanilla JS; the substituted
// graph payload remains the page's single inline JSON block.
expect(mainBody).toContain('id="counts-body"');
expect(mainBody).toContain('id="ops-body"');
expect(mainBody).toContain('fetchJson("/counts.json")');
expect(mainBody).toContain('fetchJson("/status.json")');
expect(mainBody.split('<script type="application/json" id="brain-data">').length).toBe(2);
// The live-counts console routes (session-mining-economy): both
// are loopback JSON re-read from the vault per GET.
const countsRes = await fetch(`http://127.0.0.1:${port}/counts.json`);
expect(countsRes.ok).toBe(true);
const counts = JSON.parse(await countsRes.text()) as {
schema_version: number;
telemetry: { total: number };
written_per_day: ReadonlyArray<unknown>;
report_snapshots: unknown;
};
expect(counts.schema_version).toBe(1);
expect(counts.telemetry.total).toBe(0);
expect(counts.written_per_day.length).toBe(30);
expect(counts.report_snapshots).toEqual({ status: "disabled" });
const statusRes = await fetch(`http://127.0.0.1:${port}/status.json`);
expect(statusRes.ok).toBe(true);
const status = JSON.parse(await statusRes.text()) as {
healthy: boolean;
counts: { preferences: number };
activeProfile: string | null;
store: {
writerLock: string;
writerLockPath: string | null;
writerLockOwner: string | null;
thisCaller: string;
};
};
expect(typeof status.healthy).toBe("boolean");
expect(status.counts.preferences).toBe(1);
// The explorer serves browsers, not the operator's own reach, so
// the lock PATH is withheld the way the MCP surface withholds it
// below local reach (a resolved host path is not a browser
// client's fact) - while the rest of the store group stays. The
// local CLI status keeps the path; that is pinned in status.test.
expect(status.store.writerLockPath).toBeNull();
expect(typeof status.store.writerLock).toBe("string");
expect(status.store.thisCaller).toBe("read-only");
// The verb threads its resolved config path into the server, so
// the operator snapshot sees this run's profile registry.
writeFileSync(
join(dirname(config), "profiles.json"),
JSON.stringify({ active: "test", profiles: { test: { vault } } }),
);
const profiled = await fetch(`http://127.0.0.1:${port}/status.json`);
const profileStatus = JSON.parse(await profiled.text()) as {
activeProfile: string | null;
};
expect(profileStatus.activeProfile).toBe("test");
} finally {
// Always tear the spawned CLI down so a failing assertion does
// not leak the port into the next test on the same worker.
try {
proc.kill("SIGINT");
await proc.exited;
} catch {
// process may have already exited or be in a weird state;
// either way nothing else for us to do here.
}
}
},
CLI_SPAWN_BUDGET_MS,
);
test("port in use exits 1 with a friendly message", async () => {
await bootstrap();
// Hold a port the OS picked from inside the test process so the CLI
// hits EADDRINUSE; a random pick can collide with a port another
// process already holds, and then the blocker itself fails to bind.
const blocker = Bun.serve({
hostname: "127.0.0.1",
port: 0,
fetch: () => new Response("blocker"),
});
const port = blocker.port;
try {
const r = await runCli(["brain", "explorer", "--vault", vault, "--port", String(port)], {
env: { OPEN_SECOND_BRAIN_CONFIG: config },
});
expect(r.returncode).toBe(1);
expect(r.stderr).toMatch(/already in use|in use/);
} finally {
blocker.stop();
}
});
});