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/snapshot-diff.ts` and its renderer.
*
* Fixture-driven: each test builds two on-disk Brain/ subtrees from
* scratch (no real snapshot archive needed — the differ takes any
* two roots), runs `diffBrainTrees`, and asserts on the structured
* payload. Markdown rendering is locked separately to keep parser
* regressions visible without re-deriving the structured shape.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { diffBrainTrees } from "../../src/core/brain/snapshot-diff.ts";
import { renderDiffJson, renderDiffMarkdown } from "../../src/core/brain/snapshot-diff-render.ts";
let scratch: string;
beforeEach(() => {
scratch = mkdtempSync(join(tmpdir(), "o2b-brain-snapdiff-"));
});
afterEach(() => {
rmSync(scratch, { recursive: true, force: true });
});
interface PrefShape {
readonly slug: string;
readonly principle?: string;
readonly status?: "unconfirmed" | "confirmed" | "quarantine";
readonly applied?: number;
readonly violated?: number;
readonly confidence?: "low" | "medium" | "high";
readonly confidence_value?: number | null;
readonly pinned?: boolean;
}
function makeRoot(name: string): string {
const root = join(scratch, name);
for (const sub of ["preferences", "retired", "inbox", "log"]) {
mkdirSync(join(root, sub), { recursive: true });
}
return root;
}
function writePref(root: string, s: PrefShape): void {
const id = `pref-${s.slug}`;
const path = join(root, "preferences", `${id}.md`);
const body = `---
kind: brain-preference
id: ${id}
created_at: 2026-05-01T00:00:00Z
_confirmed_at: ${s.status === "confirmed" ? "2026-05-02T00:00:00Z" : "null"}
unconfirmed_until: 2026-05-30T00:00:00Z
tags: [brain, brain/preference, brain/topic/${s.slug}]
topic: ${s.slug}
_status: ${s.status ?? "unconfirmed"}
principle: ${s.principle ?? `principle for ${s.slug}`}
_evidenced_by: []
_applied_count: ${s.applied ?? 0}
_violated_count: ${s.violated ?? 0}
_last_evidence_at: null
_confidence: ${s.confidence ?? "low"}
_confidence_value: ${
s.confidence_value === undefined ? 0 : s.confidence_value === null ? "null" : s.confidence_value
}
pinned: ${s.pinned ?? false}
---
`;
writeFileSync(path, body, "utf8");
}
function writeSig(root: string, slug: string): void {
const id = `sig-2026-05-01-${slug}`;
const path = join(root, "inbox", `${id}.md`);
writeFileSync(
path,
`---
kind: brain-signal
id: ${id}
created_at: 2026-05-01T00:00:00Z
tags: [brain, brain/signal]
topic: ${slug}
signal: positive
agent: tester
principle: rule
---
`,
"utf8",
);
}
function writeLog(root: string, day: string, body: string): void {
writeFileSync(
join(root, "log", `${day}.md`),
`---\nkind: brain-log\ndate: ${day}\ntags: [brain, brain/log]\n---\n\n${body}\n`,
"utf8",
);
}
describe("diffBrainTrees — adds and removes", () => {
test("preference added in B only", () => {
const a = makeRoot("a");
const b = makeRoot("b");
writePref(a, { slug: "alpha" });
writePref(b, { slug: "alpha" });
writePref(b, { slug: "beta", principle: "Beta principle" });
const d = diffBrainTrees(a, b);
expect(d.removed).toEqual([]);
expect(d.modified).toEqual([]);
expect(d.added).toHaveLength(1);
expect(d.added[0]!.id).toBe("pref-beta");
expect(d.added[0]!.kind).toBe("preference");
expect(d.added[0]!.principle).toBe("Beta principle");
});
test("preference removed in B", () => {
const a = makeRoot("a");
const b = makeRoot("b");
writePref(a, { slug: "gone" });
const d = diffBrainTrees(a, b);
expect(d.added).toEqual([]);
expect(d.modified).toEqual([]);
expect(d.removed).toHaveLength(1);
expect(d.removed[0]!.id).toBe("pref-gone");
});
test("signal added/removed (immutable, no field-diff)", () => {
const a = makeRoot("a");
const b = makeRoot("b");
writeSig(a, "old");
writeSig(b, "new");
const d = diffBrainTrees(a, b);
expect(d.added.map((e) => e.id)).toEqual(["sig-2026-05-01-new"]);
expect(d.removed.map((e) => e.id)).toEqual(["sig-2026-05-01-old"]);
expect(d.modified.find((c) => c.entry.kind === "signal")).toBeUndefined();
});
});
describe("diffBrainTrees — field-level modifications", () => {
test("preference status + applied_count change", () => {
const a = makeRoot("a");
const b = makeRoot("b");
writePref(a, {
slug: "rule",
principle: "Rule",
status: "confirmed",
applied: 4,
violated: 0,
confidence: "medium",
});
writePref(b, {
slug: "rule",
principle: "Rule",
status: "quarantine",
applied: 7,
violated: 3,
confidence: "low",
});
const d = diffBrainTrees(a, b);
expect(d.added).toEqual([]);
expect(d.removed).toEqual([]);
expect(d.modified).toHaveLength(1);
const change = d.modified[0]!;
expect(change.entry.id).toBe("pref-rule");
expect(change.bodyChanged).toBe(false);
const fieldNames = change.fields.map((f) => f.field).toSorted();
expect(fieldNames).toEqual([
"applied_count",
"confidence",
"confirmed_at",
"status",
"violated_count",
]);
});
test("byte-equal preferences produce no change", () => {
const a = makeRoot("a");
const b = makeRoot("b");
writePref(a, { slug: "stable" });
writePref(b, { slug: "stable" });
const d = diffBrainTrees(a, b);
expect(d.added).toEqual([]);
expect(d.removed).toEqual([]);
expect(d.modified).toEqual([]);
});
test("log body change marks bodyChanged=true with no fields", () => {
const a = makeRoot("a");
const b = makeRoot("b");
writeLog(a, "2026-05-14", "## 10:00 — feedback\n- x: 1");
writeLog(b, "2026-05-14", "## 10:00 — feedback\n- x: 2");
const d = diffBrainTrees(a, b);
expect(d.modified).toHaveLength(1);
expect(d.modified[0]!.entry.kind).toBe("log");
expect(d.modified[0]!.fields).toEqual([]);
expect(d.modified[0]!.bodyChanged).toBe(true);
});
test("per-device shards and the JSONL surface classify as log, not other", () => {
// The classifier predated per-device sharding and matched only
// `log/<date>.md`, so on any vault with a `device_id` configured -
// which is every vault where a rollback diff is interesting, since
// sharding exists for multi-device replication - the log surface fell
// through to `other`. The machine-primary `.jsonl` file, the one
// `readLogDay` actually reads, was misclassified on every vault.
const a = makeRoot("a");
const b = makeRoot("b");
const shards: ReadonlyArray<string> = [
"2026-05-14.md",
"2026-05-14.jsonl",
"2026-05-14.laptop-1.md",
"2026-05-14.laptop-1.jsonl",
];
for (const name of shards) {
writeFileSync(join(a, "log", name), "before\n", "utf8");
writeFileSync(join(b, "log", name), "after\n", "utf8");
}
const d = diffBrainTrees(a, b);
expect(d.modified).toHaveLength(shards.length);
expect(d.modified.map((m) => m.entry.kind)).toEqual(shards.map(() => "log"));
});
test("a non-log file under log/ still classifies as other", () => {
// The bucket must widen to the real shard shapes, not to everything
// that happens to live in the directory - the dream workrun JSONL is
// not a log day and must not be grouped with one.
const a = makeRoot("a");
const b = makeRoot("b");
writeFileSync(join(a, "log", "notes.md"), "before\n", "utf8");
writeFileSync(join(b, "log", "notes.md"), "after\n", "utf8");
const d = diffBrainTrees(a, b);
expect(d.modified).toHaveLength(1);
expect(d.modified[0]!.entry.kind).toBe("other");
});
});
describe("diffBrainTrees — ignored regions", () => {
test("entries under .snapshots/ are skipped", () => {
const a = makeRoot("a");
const b = makeRoot("b");
mkdirSync(join(a, ".snapshots"), { recursive: true });
mkdirSync(join(b, ".snapshots"), { recursive: true });
writeFileSync(join(a, ".snapshots", "x.tar.zst"), "old", "utf8");
writeFileSync(join(b, ".snapshots", "y.tar.zst"), "new", "utf8");
const d = diffBrainTrees(a, b);
expect(d.added.find((e) => e.path.includes(".snapshots/"))).toBeUndefined();
expect(d.removed.find((e) => e.path.includes(".snapshots/"))).toBeUndefined();
});
test("symlinks are not followed (defense against malicious snapshot tarballs)", async () => {
const a = makeRoot("a");
const b = makeRoot("b");
// Plant a real file outside the walker root, and a symlink under
// Brain/preferences/ pointing at it. A naive `statSync`-based
// walker would dereference the symlink and surface the target's
// bytes as a "preference" inside the diff.
const secret = join(scratch, "secret.txt");
writeFileSync(secret, "SECRET_TOKEN_DO_NOT_LEAK", "utf8");
const { symlinkSync } = await import("node:fs");
symlinkSync(secret, join(b, "preferences", "pref-trojan.md"));
const d = diffBrainTrees(a, b);
// The symlink must not appear in any diff section.
const allEntries = [...d.added, ...d.removed, ...d.modified.map((c) => c.entry)];
expect(allEntries.find((e) => e.path.includes("pref-trojan"))).toBeUndefined();
});
});
describe("diffBrainTrees — output ordering", () => {
test("entries sort deterministically by kind then path", () => {
const a = makeRoot("a");
const b = makeRoot("b");
writePref(b, { slug: "zeta" });
writePref(b, { slug: "alpha" });
writeSig(b, "later");
writeSig(b, "earlier");
const d = diffBrainTrees(a, b);
const addedKinds = d.added.map((e) => e.kind);
// 'preference' < 'signal' alphabetically — preferences come first.
expect(addedKinds).toEqual(["preference", "preference", "signal", "signal"]);
expect(d.added.map((e) => e.id)).toEqual([
"pref-alpha",
"pref-zeta",
"sig-2026-05-01-earlier",
"sig-2026-05-01-later",
]);
});
});
describe("renderDiffMarkdown / renderDiffJson", () => {
test("markdown body groups by kind and emits A/B labels", () => {
const a = makeRoot("a");
const b = makeRoot("b");
writePref(b, { slug: "added-rule", principle: "Use spaces" });
const md = renderDiffMarkdown(diffBrainTrees(a, b), {
aLabel: "run-x",
bLabel: "live",
});
expect(md).toMatch(/^# Brain snapshot diff$/m);
expect(md).toMatch(/^- A: run-x$/m);
expect(md).toMatch(/^- B: live$/m);
expect(md).toMatch(/^## Preferences$/m);
expect(md).toMatch(/^- \+ \[\[pref-added-rule\|Use spaces\]\] \(added\)$/m);
});
test("modified row lists field deltas", () => {
const a = makeRoot("a");
const b = makeRoot("b");
writePref(a, {
slug: "rule",
principle: "Rule",
applied: 4,
confidence: "medium",
});
writePref(b, {
slug: "rule",
principle: "Rule",
applied: 7,
confidence: "high",
});
const md = renderDiffMarkdown(diffBrainTrees(a, b), {
aLabel: "old",
bLabel: "new",
});
expect(md).toMatch(/^- ~ \[\[pref-rule\|Rule\]\]:$/m);
expect(md).toMatch(/^ {2}- applied_count: 4 → 7$/m);
expect(md).toMatch(/^ {2}- confidence: medium → high$/m);
});
test("section without entries renders '(no changes)'", () => {
const a = makeRoot("a");
const b = makeRoot("b");
const md = renderDiffMarkdown(diffBrainTrees(a, b), {});
expect(md).toMatch(/^## Preferences$/m);
expect(md).toMatch(/^\(no changes\)$/m);
});
test("json renderer returns the diff verbatim", () => {
const a = makeRoot("a");
const b = makeRoot("b");
writePref(b, { slug: "x" });
const diff = diffBrainTrees(a, b);
expect(renderDiffJson(diff)).toBe(diff);
});
});