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
/**
* Every `o2b install --json` payload, pinned.
*
* The human side of this verb was already pinned byte-for-byte: each
* `install/<runtime>.md` carries an expected-output block and
* `tests/docs/install-verify-conformance.test.ts` renders the real
* `verify()` against it. The machine side was pinned by nothing. Four
* modes emit four different payloads, three declared `schema_version: 1`
* and the fourth - apply, the only mode that actually changes the machine -
* declared no version at all, and no test asserted a single field name in
* any of them.
*
* That asymmetry is the defect: a field added to the human table breaks a
* documented block and names the file to edit, while the same field
* forgotten on the JSON twin breaks nothing. This file removes the second
* half of the asymmetry by naming the key set of every payload.
*
* Known wire inconsistency, pinned rather than fixed here: the plan
* payload serialises `InstallPlan` verbatim, so it carries `postNotes` in
* camelCase while every other payload in this family uses snake_case
* (`config_path`, `fix_hint`, `steps_executed`). Renaming it is a wire
* break with no consumer asking for it; pinning it is what makes the
* rename a deliberate act rather than an accident.
*/
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { INSTALL_JSON_SCHEMA_VERSION } from "../../src/cli/install/render.ts";
import { runCli as baseRunCli, type RunCliOptions, type RunResult } from "../helpers/run-cli.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);
// Same reason as `install-verb.test.ts`: the adapters resolve the home
// directory at module-load time, so each call needs a fresh process to
// honour this file's per-case temp HOME.
function runCli(args: ReadonlyArray<string>, opts: RunCliOptions = {}): Promise<RunResult> {
return baseRunCli(args, { ...opts, subprocess: true });
}
let vault: string;
let home: string;
let configPath: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "osb-ijs-v-"));
home = mkdtempSync(join(tmpdir(), "osb-ijs-h-"));
configPath = join(home, "config.yaml");
writeFileSync(configPath, `vault: "${vault}"\nagent_name: "claude-vps"\ntimezone: "UTC"\n`);
});
afterEach(() => {
for (const p of [vault, home]) {
try {
rmSync(p, { recursive: true, force: true });
} catch {}
}
});
function envBase() {
return {
HOME: home,
// The adapter checks XDG_CONFIG_HOME first, so a developer shell or a
// CI runner that exports it would otherwise redirect every config
// path out of the temp HOME. Pin it inside the sandbox instead of
// deleting it: an inherited value could also point the general
// config resolution at real user state.
XDG_CONFIG_HOME: join(home, ".config"),
OPEN_SECOND_BRAIN_CONFIG: configPath,
VAULT_DIR: vault,
VAULT_AGENT_NAME: "claude-vps",
VAULT_TIMEZONE: "UTC",
};
}
async function payloadOf(args: ReadonlyArray<string>): Promise<Record<string, unknown>> {
const r = await runCli(args, { env: envBase() });
expect(`${args.join(" ")} exit ${r.returncode}\n${r.stderr}`).toBe(`${args.join(" ")} exit 0\n`);
return JSON.parse(r.stdout) as Record<string, unknown>;
}
/** Sorted key list, so a failure names the field rather than a count. */
function keys(value: unknown): string {
return Object.keys(value as object)
.toSorted()
.join(",");
}
describe("every install --json payload declares its schema version", () => {
test("detect", async () => {
const payload = await payloadOf(["install", "--json"]);
expect(payload["schema_version"]).toBe(INSTALL_JSON_SCHEMA_VERSION);
});
test("plan", async () => {
const payload = await payloadOf(["install", "--target", "cursor", "--json"]);
expect(payload["schema_version"]).toBe(INSTALL_JSON_SCHEMA_VERSION);
});
test("apply - the one mode that changes the machine, and the one that had none", async () => {
const payload = await payloadOf([
"install",
"--target",
"cursor",
"--apply",
"--yes",
"--json",
]);
expect(payload["schema_version"]).toBe(INSTALL_JSON_SCHEMA_VERSION);
});
test("verify", async () => {
const payload = await payloadOf(["install", "--check", "--json"]);
expect(payload["schema_version"]).toBe(INSTALL_JSON_SCHEMA_VERSION);
});
});
describe("every install --json payload names its fields", () => {
test("detect carries a target row per adapter", async () => {
const payload = await payloadOf(["install", "--json"]);
expect(keys(payload)).toBe("schema_version,targets");
const targets = payload["targets"] as ReadonlyArray<unknown>;
expect(targets.length).toBeGreaterThan(0);
for (const row of targets) expect(keys(row)).toBe("config_path,notes,status,target");
});
test("plan carries the plan verbatim", async () => {
const payload = await payloadOf(["install", "--target", "cursor", "--json"]);
expect(keys(payload)).toBe("plan,schema_version");
expect(keys(payload["plan"])).toBe("postNotes,steps,target");
// `diff` is additive and present only when the file would change;
// a first install into an empty home always changes it.
for (const step of (payload["plan"] as { steps: ReadonlyArray<unknown> }).steps) {
expect(keys(step)).toBe("diff,kind,path,preview");
}
});
test("apply carries the manifest it wrote, at the top level as before", async () => {
const payload = await payloadOf([
"install",
"--target",
"cursor",
"--apply",
"--yes",
"--json",
]);
// `schema_version` is ADDED beside the result's own fields rather than
// nesting the result under a key: an existing consumer reading
// `.manifest` or `.steps_executed` keeps working and gains a version,
// which a re-nesting would have broken for no benefit.
expect(keys(payload)).toContain("manifest");
expect(keys(payload)).toContain("steps_executed");
expect(keys(payload)).toContain("target");
// t_b6bcd984: the consent verdict rides the CLI receipt (not the
// sidecar manifest), additive under schema_version 1.
expect(keys(payload)).toContain("consent");
});
test("verify carries a verify row per adapter", async () => {
const payload = await payloadOf(["install", "--check", "--json"]);
expect(keys(payload)).toBe("schema_version,targets");
const targets = payload["targets"] as ReadonlyArray<unknown>;
expect(targets.length).toBeGreaterThan(0);
for (const row of targets) expect(keys(row)).toBe("details,fix_hint,status,target");
});
});
describe("the opencode V2 config shape in the apply payload", () => {
test("apply to an existing mcp.servers config records the nested owned keys", async () => {
const opencodeConfig = join(home, ".config", "opencode", "opencode.json");
mkdirSync(dirname(opencodeConfig), { recursive: true });
writeFileSync(opencodeConfig, JSON.stringify({ mcp: { servers: {} } }, null, 2) + "\n");
const payload = await payloadOf([
"install",
"--target",
"opencode",
"--apply",
"--yes",
"--json",
]);
const manifest = payload["manifest"] as Record<string, unknown>;
expect(manifest["config_path"]).toBe(opencodeConfig);
expect(manifest["owned_keys"]).toEqual([
"mcp.servers.open-second-brain",
"mcp.servers.open-second-brain-writer",
]);
});
});