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
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
chmodSync,
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
rmSync,
symlinkSync,
utimesSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
BrainSnapshotListingError,
BrainSnapshotToolingMissingError,
createSnapshot,
isSnapshotEntrySkipReason,
listSnapshots,
pruneSnapshots,
restoreSnapshot,
SNAPSHOT_ENTRY_SKIP_REASON,
tarPathArg,
} from "../../src/core/brain/snapshot.ts";
import { brainDirs, snapshotPath } from "../../src/core/brain/paths.ts";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
import {
BRAIN_MANIFEST_SCHEMA_VERSION,
manifestSidecarPath,
readManifestSidecar,
} from "../../src/core/brain/manifest.ts";
import { BRAIN_SNAPSHOT_REASON } from "../../src/core/brain/types.ts";
import { extractSnapshotArchive } from "../helpers/snapshot-archive.ts";
import { CHMOD_CANNOT_DENY } from "../helpers/platform.ts";
/**
* The reason every fixture here takes its snapshot for. `createSnapshot`
* requires one, and these cases are about the archive mechanics rather
* than the provenance - which lives in `snapshot-reason.test.ts`.
*/
const DREAM = BRAIN_SNAPSHOT_REASON.dream;
let vault: string;
let configHome: string;
let configPath: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-snap-vault-"));
configHome = mkdtempSync(join(tmpdir(), "o2b-snap-cfg-"));
configPath = join(configHome, "config.yaml");
atomicWriteFileSync(configPath, `vault: ${vault}\n`);
bootstrapBrain(vault, { configPath });
// Seed a minimal but interesting Brain/ tree.
const dirs = brainDirs(vault);
writeFileSync(
join(dirs.inbox, "sig-2026-05-14-foo.md"),
"---\nkind: brain-signal\n---\n\n## Raw\n\nseed\n",
);
writeFileSync(
join(dirs.preferences, "pref-foo.md"),
"---\nkind: brain-preference\n---\n\n## Principle\n\nseed\n",
);
writeFileSync(
join(dirs.log, "2026-05-14.md"),
"---\nkind: brain-log\n---\n\n# Brain log — 2026-05-14\n",
);
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
rmSync(configHome, { recursive: true, force: true });
});
describe("createSnapshot", () => {
test("captures every top-level Brain/ entry except .snapshots/", () => {
const dirs = brainDirs(vault);
// Place a sentinel inside .snapshots/ to confirm it is NOT bundled
// into the new archive.
writeFileSync(join(dirs.snapshots, "sentinel.tar.zst"), "X");
const res = createSnapshot(vault, "dream-2026-05-14-070000", { reason: DREAM });
expect(existsSync(res.path)).toBe(true);
// Extract into a fresh tmp and inspect.
const tmp = mkdtempSync(join(tmpdir(), "o2b-snap-verify-"));
try {
extractSnapshotArchive(res.path, tmp);
const extracted = join(tmp, "Brain");
expect(existsSync(extracted)).toBe(true);
expect(existsSync(join(extracted, "_brain.yaml"))).toBe(true);
expect(existsSync(join(extracted, "_BRAIN.md"))).toBe(true);
expect(existsSync(join(extracted, "inbox", "sig-2026-05-14-foo.md"))).toBe(true);
expect(existsSync(join(extracted, "preferences", "pref-foo.md"))).toBe(true);
// The .snapshots/ directory MUST NOT be inside the archive.
expect(existsSync(join(extracted, ".snapshots"))).toBe(false);
} finally {
rmSync(tmp, { recursive: true, force: true });
}
});
test("writes a restorable archive even when tar has a default archive path", () => {
const oldTape = process.env["TAPE"];
const defaultArchive = join(configHome, "default.tar");
const runId = "dream-explicit-archive";
process.env["TAPE"] = defaultArchive;
try {
const snapshot = createSnapshot(vault, runId, { reason: DREAM });
expect(existsSync(defaultArchive)).toBe(false);
const extracted = join(configHome, "extracted");
mkdirSync(extracted);
extractSnapshotArchive(snapshot.path, extracted);
expect(readFileSync(join(extracted, "Brain", "log", "2026-05-14.md"), "utf8")).toBe(
readFileSync(join(brainDirs(vault).log, "2026-05-14.md"), "utf8"),
);
} finally {
if (oldTape === undefined) delete process.env["TAPE"];
else process.env["TAPE"] = oldTape;
}
});
test("rejects invalid run_id", () => {
expect(() => createSnapshot(vault, "../escape", { reason: DREAM })).toThrow();
});
test("writes sidecar manifest alongside the archive (§22 + §5-tail)", () => {
createSnapshot(vault, "dream-with-manifest", { reason: DREAM });
const sidecar = manifestSidecarPath(vault, "dream-with-manifest");
expect(existsSync(sidecar)).toBe(true);
const m = readManifestSidecar(vault, "dream-with-manifest");
expect(m).not.toBeNull();
expect(m!.schema_version).toBe(BRAIN_MANIFEST_SCHEMA_VERSION);
expect(m!.brain_root).toBe("Brain");
// The seed tree carries _brain.yaml, _BRAIN.md, the seed signal,
// pref, and log entry. All must appear in the manifest.
expect(m!.files["_brain.yaml"]).toBeDefined();
expect(m!.files["_BRAIN.md"]).toBeDefined();
expect(m!.files["inbox/sig-2026-05-14-foo.md"]).toBeDefined();
expect(m!.files["preferences/pref-foo.md"]).toBeDefined();
expect(m!.files["log/2026-05-14.md"]).toBeDefined();
});
});
describe("listSnapshots", () => {
test("returns archives in newest-first order by mtime", () => {
createSnapshot(vault, "dream-2026-05-14-070000", { reason: DREAM });
// Force an older mtime on the first archive so the ordering is
// unambiguous regardless of how fast the test runs.
const a = snapshotPath(vault, "dream-2026-05-14-070000");
const oldT = new Date("2026-05-13T00:00:00Z");
utimesSync(a, oldT, oldT);
createSnapshot(vault, "dream-2026-05-14-080000", { reason: DREAM });
const b = snapshotPath(vault, "dream-2026-05-14-080000");
const midT = new Date("2026-05-14T00:00:00Z");
utimesSync(b, midT, midT);
createSnapshot(vault, "dream-2026-05-14-090000", { reason: DREAM });
const c = snapshotPath(vault, "dream-2026-05-14-090000");
const newT = new Date("2026-05-15T00:00:00Z");
utimesSync(c, newT, newT);
const list = listSnapshots(vault).snapshots;
expect(list).toHaveLength(3);
expect(list[0]!.run_id).toBe("dream-2026-05-14-090000");
expect(list[1]!.run_id).toBe("dream-2026-05-14-080000");
expect(list[2]!.run_id).toBe("dream-2026-05-14-070000");
for (const s of list) {
expect(s.size_bytes).toBeGreaterThan(0);
expect(s.path.endsWith(".tar.zst")).toBe(true);
}
});
test("returns [] when .snapshots/ is empty", () => {
expect(listSnapshots(vault).snapshots).toEqual([]);
});
test("an empty history skips nothing, so the two fields cannot be confused", () => {
expect(listSnapshots(vault)).toEqual({ snapshots: [], skipped: [] });
});
test("an archive that cannot be stat'ed is carried out, not dropped", () => {
// The failure the swallow hid: a populated history in which nothing
// survives both filters used to answer exactly like a vault that had
// never taken a recovery point.
createSnapshot(vault, "dream-readable", { reason: DREAM });
const dir = brainDirs(vault).snapshots;
symlinkSync(join(dir, "nowhere.tar.zst"), join(dir, "dream-dangling.tar.zst"));
const listing = listSnapshots(vault);
expect(listing.snapshots.map((s) => s.run_id)).toEqual(["dream-readable"]);
expect(listing.skipped).toHaveLength(1);
expect(listing.skipped[0]!.name).toBe("dream-dangling.tar.zst");
expect(listing.skipped[0]!.reason).toBe(SNAPSHOT_ENTRY_SKIP_REASON.entryUnreadable);
expect(isSnapshotEntrySkipReason(listing.skipped[0]!.reason)).toBe(true);
expect(listing.skipped[0]!.detail.length).toBeGreaterThan(0);
});
test("an archive whose run id does not validate is carried out under its own reason", () => {
writeFileSync(join(brainDirs(vault).snapshots, "not a run id!.tar.zst"), "x");
const listing = listSnapshots(vault);
expect(listing.snapshots).toEqual([]);
expect(listing.skipped.map((s) => s.reason)).toEqual([
SNAPSHOT_ENTRY_SKIP_REASON.runIdUnparseable,
]);
});
test("a file that is not an archive is skipped silently, because it is not one", () => {
createSnapshot(vault, "dream-readable", { reason: DREAM });
writeFileSync(join(brainDirs(vault).snapshots, "README.txt"), "mine");
// The sidecar manifest createSnapshot just wrote is in this directory
// too, and neither it nor the note is a recovery point that could not
// be read.
expect(listSnapshots(vault).skipped).toEqual([]);
});
// chmod cannot deny access on Windows (read-only attribute only) or to root.
test.skipIf(CHMOD_CANNOT_DENY)(
"a snapshots directory it cannot read throws instead of reading as empty",
() => {
// An empty history and a history nobody could enumerate are
// different answers, and `[]` for both is what let `snapshot log`
// print "no snapshots available" over a directory it never read.
createSnapshot(vault, "dream-unreadable-dir", { reason: DREAM });
const snapshots = brainDirs(vault).snapshots;
chmodSync(snapshots, 0o000);
try {
expect(() => listSnapshots(vault).snapshots).toThrow(BrainSnapshotListingError);
try {
listSnapshots(vault);
} catch (err) {
expect((err as Error).message).toContain(snapshots);
}
} finally {
chmodSync(snapshots, 0o755);
}
// And the same directory, readable again, still lists its archive:
// the throw is about the read, not about the snapshot.
expect(listSnapshots(vault).snapshots).toHaveLength(1);
},
);
test("manifest_path populated when sidecar present, null otherwise", () => {
createSnapshot(vault, "dream-with-sidecar", { reason: DREAM });
// Simulate a legacy snapshot: drop the sidecar that
// createSnapshot just wrote so only the archive remains.
const sidecar = manifestSidecarPath(vault, "dream-with-sidecar");
expect(existsSync(sidecar)).toBe(true);
createSnapshot(vault, "dream-legacy", { reason: DREAM });
rmSync(manifestSidecarPath(vault, "dream-legacy"), { force: true });
const list = listSnapshots(vault).snapshots;
const byId = new Map(list.map((s) => [s.run_id, s]));
expect(byId.get("dream-with-sidecar")!.manifest_path).toBe(sidecar);
expect(byId.get("dream-legacy")!.manifest_path).toBeNull();
});
});
describe("pruneSnapshots", () => {
test("removes oldest archives, keeps the retention_count newest", () => {
const labels = ["a", "b", "c", "d", "e"];
const ts = [
"2026-05-10T00:00:00Z",
"2026-05-11T00:00:00Z",
"2026-05-12T00:00:00Z",
"2026-05-13T00:00:00Z",
"2026-05-14T00:00:00Z",
];
for (let i = 0; i < labels.length; i++) {
const runId = `dream-${labels[i]}-000000`;
createSnapshot(vault, runId, { reason: DREAM });
const p = snapshotPath(vault, runId);
const t = new Date(ts[i]!);
utimesSync(p, t, t);
}
const before = listSnapshots(vault).snapshots;
expect(before).toHaveLength(5);
const res = pruneSnapshots(vault, 3);
expect(res.deleted).toHaveLength(2);
const after = listSnapshots(vault).snapshots;
expect(after).toHaveLength(3);
expect(after.map((s) => s.run_id)).toEqual([
"dream-e-000000",
"dream-d-000000",
"dream-c-000000",
]);
});
test("noop when fewer files than retention_count", () => {
createSnapshot(vault, "dream-only", { reason: DREAM });
const res = pruneSnapshots(vault, 10);
expect(res.deleted).toEqual([]);
expect(listSnapshots(vault).snapshots).toHaveLength(1);
});
test("removes sidecar manifest alongside the archive", () => {
const labels = ["a", "b", "c"];
const ts = ["2026-05-10T00:00:00Z", "2026-05-11T00:00:00Z", "2026-05-12T00:00:00Z"];
for (let i = 0; i < labels.length; i++) {
const runId = `dream-prune-${labels[i]}`;
createSnapshot(vault, runId, { reason: DREAM });
const p = snapshotPath(vault, runId);
const t = new Date(ts[i]!);
utimesSync(p, t, t);
}
// Sanity: all three sidecars present pre-prune.
for (const l of labels) {
expect(existsSync(manifestSidecarPath(vault, `dream-prune-${l}`))).toBe(true);
}
pruneSnapshots(vault, 1);
// 'c' is the newest by mtime, so 'a' and 'b' are deleted along with
// their sidecars; 'c' and its sidecar survive.
expect(existsSync(manifestSidecarPath(vault, "dream-prune-a"))).toBe(false);
expect(existsSync(manifestSidecarPath(vault, "dream-prune-b"))).toBe(false);
expect(existsSync(manifestSidecarPath(vault, "dream-prune-c"))).toBe(true);
});
test("legacy archive without sidecar still prunes cleanly", () => {
createSnapshot(vault, "dream-legacy-prune-old", { reason: DREAM });
rmSync(manifestSidecarPath(vault, "dream-legacy-prune-old"), { force: true });
const old = snapshotPath(vault, "dream-legacy-prune-old");
const t = new Date("2026-05-09T00:00:00Z");
utimesSync(old, t, t);
createSnapshot(vault, "dream-legacy-prune-new", { reason: DREAM });
const res = pruneSnapshots(vault, 1);
expect(res.deleted).toContain(old);
expect(existsSync(old)).toBe(false);
});
});
describe("restoreSnapshot — round-trip integrity", () => {
test("state A → snapshot → mutate to B → restore A → bytes match for key files (excluding .snapshots/)", () => {
const dirs = brainDirs(vault);
const prefPath = join(dirs.preferences, "pref-foo.md");
const sigPath = join(dirs.inbox, "sig-2026-05-14-foo.md");
// Capture state A.
const stateAPref = readFileSync(prefPath, "utf8");
const stateASig = readFileSync(sigPath, "utf8");
const snap = createSnapshot(vault, "dream-stateA", { reason: DREAM });
expect(existsSync(snap.path)).toBe(true);
// Mutate to state B: rewrite a pref, delete a signal, add a new
// file. Also put a *new* snapshot under .snapshots/ that should
// survive the restore (this is the load-bearing invariant).
writeFileSync(prefPath, "MUTATED PREF CONTENT");
rmSync(sigPath);
writeFileSync(join(dirs.inbox, "sig-newer.md"), "newer-content");
// Create another snapshot — restoring stateA must NOT erase it.
const newer = createSnapshot(vault, "dream-stateB", { reason: DREAM });
expect(existsSync(newer.path)).toBe(true);
const res = restoreSnapshot(vault, "dream-stateA");
expect(res.restored_files).toBeGreaterThan(0);
// Key files restored byte-equal.
expect(readFileSync(prefPath, "utf8")).toBe(stateAPref);
expect(readFileSync(sigPath, "utf8")).toBe(stateASig);
// The post-stateA new file should be gone.
expect(existsSync(join(dirs.inbox, "sig-newer.md"))).toBe(false);
// BOTH snapshots must survive — including the one made AFTER the
// restored state, so the operator still has a forward path.
expect(existsSync(snap.path)).toBe(true);
expect(existsSync(newer.path)).toBe(true);
});
});
describe("snapshot tooling absent", () => {
test("createSnapshot throws BrainSnapshotToolingMissingError when tar absent", () => {
// Synthetic vault root that bootstraps fine; then we run with a
// sanitized PATH so neither tar nor compressors are available.
const dirs = brainDirs(vault);
mkdirSync(dirs.snapshots, { recursive: true });
const originalPath = process.env["PATH"];
process.env["PATH"] = "/nonexistent-path-for-test";
try {
expect(() => createSnapshot(vault, "dream-no-tools", { reason: DREAM })).toThrow(
BrainSnapshotToolingMissingError,
);
} finally {
process.env["PATH"] = originalPath;
}
});
});
describe("tarPathArg - one spelling every Windows tar accepts", () => {
// Git for Windows' MSYS GNU tar, first on PATH inside Git Bash and on
// GitHub's Windows runners, cannot extract into a backslashed `-C C:\...`;
// bsdtar and GNU tar both accept forward slashes.
test("a Windows path is handed to tar with forward slashes", () => {
expect(tarPathArg("C:\\Users\\u\\AppData\\Local\\Temp\\o2b-x", "win32")).toBe(
"C:/Users/u/AppData/Local/Temp/o2b-x",
);
});
test("a POSIX path is unchanged, backslashes included", () => {
expect(tarPathArg("/tmp/o2b-x/odd\\name", "linux")).toBe("/tmp/o2b-x/odd\\name");
});
});