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
/**
* Tests for `src/core/brain/upgrade.ts`.
*
* Two layers:
* 1. `mergeBrainYaml` — pure string transform. Covers missing
* sections, missing nested keys, all-present, malformed input
* handled at planUpgrade caller (not here).
* 2. `planUpgrade` / `applyUpgrade` — end-to-end against fixture
* vaults bootstrapped via `bootstrapBrain`.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { applyUpgrade, mergeBrainYaml, planUpgrade } from "../../../src/core/brain/upgrade.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
import { digestVerifies } from "../../../src/core/integrity/digest.ts";
import { brainConfigPath, brainManualPath } from "../../../src/core/brain/paths.ts";
import { listSnapshots } from "../../../src/core/brain/snapshot.ts";
import { useUnshardedLegacyLog } from "../../helpers/device-id.ts";
// The legacy day log and ledgers are read under their un-sharded names.
useUnshardedLegacyLog();
let vault: string;
let configHome: string;
let configPath: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-upgrade-vault-"));
configHome = mkdtempSync(join(tmpdir(), "o2b-upgrade-cfg-"));
configPath = join(configHome, "config.yaml");
atomicWriteFileSync(configPath, `vault: ${vault}\n`);
bootstrapBrain(vault, { configPath });
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
rmSync(configHome, { recursive: true, force: true });
});
describe("mergeBrainYaml", () => {
const FULL = `schema_version: 1
primary_agent: null
dream:
candidate_threshold: 3
unconfirmed_window_days: 14
contradiction_window_days: 14
retire:
stale_evidence_days: 90
confidence:
low_max_applied: 2
medium_min: 0.40
high_min: 0.75
snapshots:
retention_count: 10
`;
test("identical input → identical output (no merge needed)", () => {
expect(mergeBrainYaml(FULL, FULL)).toBe(FULL);
});
test("missing top-level section is appended at end-of-file", () => {
const minimal = `schema_version: 1
primary_agent: null
dream:
candidate_threshold: 3
unconfirmed_window_days: 14
contradiction_window_days: 14
`;
const merged = mergeBrainYaml(minimal, FULL);
expect(merged).toContain("retire:");
expect(merged).toContain("stale_evidence_days: 90");
expect(merged).toContain("snapshots:");
expect(merged).toContain("retention_count: 10");
// Existing keys must remain at their original spot.
expect(merged.indexOf("schema_version: 1")).toBeLessThan(merged.indexOf("retire:"));
expect(merged.indexOf("dream:")).toBeLessThan(merged.indexOf("retire:"));
});
test("missing nested key is inserted at end of its section", () => {
const live = `schema_version: 1
primary_agent: null
dream:
candidate_threshold: 3
unconfirmed_window_days: 14
contradiction_window_days: 14
retire:
stale_evidence_days: 90
confidence:
low_max_applied: 2
medium_min: 0.40
snapshots:
retention_count: 10
`;
const merged = mergeBrainYaml(live, FULL);
expect(merged).toContain("high_min: 0.75");
// Existing `medium_min` line stays where it is.
const lines = merged.split("\n");
const mediumIdx = lines.findIndex((l) => l.includes("medium_min: 0.40"));
const highIdx = lines.findIndex((l) => l.includes("high_min: 0.75"));
expect(highIdx).toBeGreaterThan(mediumIdx);
});
test("user-customised value is preserved (never rewritten)", () => {
const live = `schema_version: 1
primary_agent: null
dream:
candidate_threshold: 5
unconfirmed_window_days: 14
contradiction_window_days: 14
retire:
stale_evidence_days: 90
confidence:
low_max_applied: 2
medium_min: 0.40
high_min: 0.75
snapshots:
retention_count: 10
`;
const merged = mergeBrainYaml(live, FULL);
// The user-tuned candidate_threshold of 5 must survive.
expect(merged).toContain("candidate_threshold: 5");
expect(merged).not.toContain("candidate_threshold: 3");
});
});
describe("planUpgrade", () => {
test("freshly-bootstrapped vault → all files noop", () => {
const plan = planUpgrade(vault);
expect(plan.pending).toBe(0);
expect(plan.errors).toBe(0);
for (const f of plan.files) {
expect(f.status).toBe("noop");
}
});
test("the plan is sealed: its digest describes exactly its own body (t_18fda844)", () => {
const plan = planUpgrade(vault);
expect(plan.digest).toMatch(/^[0-9a-f]{64}$/);
const { digest: _digest, ...body } = plan;
expect(digestVerifies(body, plan.digest)).toBe(true);
// The seal binds the plan content, not the moment it was planned.
const replan = planUpgrade(vault);
expect(replan.digest).toBe(plan.digest);
});
test("file ordering is _brain.yaml, _BRAIN.md", () => {
const plan = planUpgrade(vault);
expect(plan.files.map((f) => f.path)).toEqual(["Brain/_brain.yaml", "Brain/_BRAIN.md"]);
});
test("missing snapshots section in _brain.yaml → update with appended block", () => {
const yamlPath = brainConfigPath(vault);
const original = readFileSync(yamlPath, "utf8");
// Strip the snapshots block.
const without = original.replace(/\nsnapshots:[\s\S]*$/, "\n");
atomicWriteFileSync(yamlPath, without);
const plan = planUpgrade(vault);
expect(plan.pending).toBe(1);
const yamlPlan = plan.files.find((f) => f.path === "Brain/_brain.yaml")!;
expect(yamlPlan.status).toBe("update");
expect(yamlPlan.before).toBe(without);
expect(yamlPlan.after).toContain("snapshots:");
expect(yamlPlan.after).toContain("retention_count: 10");
});
test("malformed _brain.yaml surfaces as error (apply must refuse)", () => {
atomicWriteFileSync(brainConfigPath(vault), "not: a valid: brain yaml\n");
const plan = planUpgrade(vault);
expect(plan.errors).toBe(1);
const yamlPlan = plan.files.find((f) => f.path === "Brain/_brain.yaml")!;
expect(yamlPlan.status).toBe("error");
expect(yamlPlan.error.length).toBeGreaterThan(0);
});
test("missing _brain.yaml → status: update from absent before (recoverable)", () => {
// ENOENT path: a user (or a bad rsync) deleted _brain.yaml from
// an otherwise-bootstrapped vault. Upgrade must restore it from
// the canonical default rather than refusing every managed-file
// update behind one missing config.
rmSync(brainConfigPath(vault), { force: true });
const plan = planUpgrade(vault);
expect(plan.errors).toBe(0);
const yamlPlan = plan.files.find((f) => f.path === "Brain/_brain.yaml")!;
expect(yamlPlan.status).toBe("update");
expect(yamlPlan.before).toBeNull();
expect(yamlPlan.after).toContain("schema_version: 1");
});
test("hand-edited _BRAIN.md → status update with full diff", () => {
atomicWriteFileSync(brainManualPath(vault), "stale operator copy\n");
const plan = planUpgrade(vault);
const manualPlan = plan.files.find((f) => f.path === "Brain/_BRAIN.md")!;
expect(manualPlan.status).toBe("update");
expect(manualPlan.before).toBe("stale operator copy\n");
expect(manualPlan.after).toContain("Brain");
});
});
describe("applyUpgrade", () => {
test("nothing to do → no snapshot, no log row", () => {
const before = listSnapshots(vault).snapshots.length;
const res = applyUpgrade(vault, { agent: "claude-vps-agent" });
expect(res.files_updated).toEqual([]);
expect(res.run_id).toBe("");
expect(listSnapshots(vault).snapshots.length).toBe(before);
});
test("pending update → snapshot, files rewritten, idempotent re-run", () => {
atomicWriteFileSync(brainManualPath(vault), "stale operator copy\n");
const res = applyUpgrade(vault, { agent: "claude-vps-agent" });
expect(res.run_id.startsWith("upgrade-")).toBe(true);
expect(res.files_updated).toContain("Brain/_BRAIN.md");
// Snapshot exists with the upgrade prefix.
const snaps = listSnapshots(vault).snapshots;
expect(snaps.some((s) => s.run_id === res.run_id)).toBe(true);
// The live file is now the canonical template body.
expect(readFileSync(brainManualPath(vault), "utf8")).not.toBe("stale operator copy\n");
// Idempotent re-run: plan is now empty.
const res2 = applyUpgrade(vault, { agent: "claude-vps-agent" });
expect(res2.files_updated).toEqual([]);
});
test("log row records run id, agent, snapshot, files list", () => {
atomicWriteFileSync(brainManualPath(vault), "stale operator copy\n");
const res = applyUpgrade(vault, {
agent: "claude-vps-agent",
now: new Date("2026-05-18T10:00:00Z"),
});
const logPath = join(vault, "Brain", "log", "2026-05-18.md");
expect(existsSync(logPath)).toBe(true);
const logBody = readFileSync(logPath, "utf8");
expect(logBody).toContain("upgrade");
expect(logBody).toContain(res.run_id);
expect(logBody).toContain("claude-vps-agent");
expect(logBody).toContain("Brain/_BRAIN.md");
});
test("malformed _brain.yaml refuses to apply (no snapshot taken)", () => {
atomicWriteFileSync(brainConfigPath(vault), "not: a valid: brain yaml\n");
const before = listSnapshots(vault).snapshots.length;
expect(() => applyUpgrade(vault, { agent: "claude" })).toThrow(/upgrade aborted/);
expect(listSnapshots(vault).snapshots.length).toBe(before);
});
test("can rollback to upgrade-<ts> snapshot to undo the apply", () => {
atomicWriteFileSync(brainManualPath(vault), "stale operator copy\n");
const beforeBytes = readFileSync(brainManualPath(vault), "utf8");
const res = applyUpgrade(vault, { agent: "claude" });
expect(res.files_updated.length).toBeGreaterThan(0);
// Smoke: snapshot is restorable. We don't run restoreSnapshot
// directly here — that path has its own coverage; we just verify
// the snapshot exists and the upgrade actually changed bytes.
const afterBytes = readFileSync(brainManualPath(vault), "utf8");
expect(afterBytes).not.toBe(beforeBytes);
expect(listSnapshots(vault).snapshots.some((s) => s.run_id === res.run_id)).toBe(true);
});
});
// ── Corrupted preference principle repair (token-diet, t_40eb1de7) ─────────
describe("planUpgrade / applyUpgrade — preference principle repair", () => {
const PREF_DIR = "Brain/preferences";
function writeCorruptedPref(slug: string): string {
const path = join(vault, PREF_DIR, `pref-${slug}.md`);
// Faithful copy of the live-vault corruption shape: six on-disk
// backslashes per quote (three in memory after the parser's single
// unescape - the \\{2,} amplification signature) plus a leaked
// tool-call XML fragment, inside a double-quoted YAML scalar.
const principle =
'When the user describes a rule like \\\\\\\\\\\\"давай так:\\\\\\\\\\\\" wait for approval.</principle>\\\\n<parameter name=\\\\\\\\\\\\"scope\\\\\\\\\\\\">collaboration';
const content = [
"---",
"kind: brain-preference",
`id: pref-${slug}`,
'created_at: "2026-05-17T15:12:12Z"',
'unconfirmed_until: "2026-05-17T15:12:12Z"',
`tags: [brain, brain/preference, brain/topic/${slug}]`,
`topic: ${slug}`,
"_status: confirmed",
`principle: "${principle}"`,
"_applied_count: 0",
"_violated_count: 0",
"_last_evidence_at: null",
"_confidence: low",
"_confidence_value: 0",
"pinned: false",
"---",
"",
"## Origin",
"",
"test fixture",
"",
].join("\n");
atomicWriteFileSync(path, content);
return path;
}
function writeCleanPref(slug: string): string {
const path = join(vault, PREF_DIR, `pref-${slug}.md`);
const content = [
"---",
"kind: brain-preference",
`id: pref-${slug}`,
'created_at: "2026-05-17T15:12:12Z"',
'unconfirmed_until: "2026-05-17T15:12:12Z"',
`tags: [brain, brain/preference, brain/topic/${slug}]`,
`topic: ${slug}`,
"_status: confirmed",
'principle: "Use measured punctuation in docs."',
"_applied_count: 2",
"_violated_count: 0",
"_last_evidence_at: null",
"_confidence: medium",
"_confidence_value: 0.5",
"pinned: false",
"---",
"",
"## Origin",
"",
"test fixture",
"",
].join("\n");
atomicWriteFileSync(path, content);
return path;
}
test("plan flags a corrupted principle and leaves clean preferences alone", () => {
writeCorruptedPref("broken");
writeCleanPref("healthy");
const plan = planUpgrade(vault);
const prefPlans = plan.files.filter((f) => f.path.startsWith(PREF_DIR));
expect(prefPlans.map((f) => f.path)).toEqual([`${PREF_DIR}/pref-broken.md`]);
expect(prefPlans[0]!.status).toBe("update");
expect(prefPlans[0]!.after).not.toContain("</principle>");
expect(prefPlans[0]!.after).not.toContain("<parameter");
});
test("apply rewrites the corrupted file once and is idempotent", () => {
const path = writeCorruptedPref("broken");
const res = applyUpgrade(vault, { agent: "claude-dev-agent" });
expect(res.files_updated).toContain(`${PREF_DIR}/pref-broken.md`);
const bytes = readFileSync(path, "utf8");
expect(bytes).not.toContain("</principle>");
expect(bytes).not.toContain("<parameter");
expect(bytes).not.toContain('\\\\"');
expect(bytes).toContain('\\"давай так:\\"');
// Untouched fields survive verbatim.
expect(bytes).toContain("_status: confirmed");
expect(bytes).toContain("topic: broken");
expect(bytes).toContain("## Origin");
// Second pass: nothing pending.
const plan2 = planUpgrade(vault);
expect(plan2.files.filter((f) => f.path.startsWith(PREF_DIR))).toEqual([]);
const res2 = applyUpgrade(vault, { agent: "claude-dev-agent" });
expect(res2.files_updated).toEqual([]);
});
});