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
/**
* B1: the four operations with the largest unprotected blast radius.
*
* The defects, one per section below.
*
* 1. `restoreSnapshot` deletes every live top-level entry under
* `Brain/` and takes no recovery point of what it discards. An
* operator who rolls back to the wrong run id has no way back at
* all - the confirmation ladder in front of it is the strongest in
* the codebase, which makes the missing recovery point the one weak
* link in an otherwise careful verb.
* 2. The dream pass calls `createSnapshot` inline. The gate's own
* header names that as the anti-pattern it exists to prevent: a
* second path that has to be kept correct by hand.
* 3. `pruneSnapshots` destroys recovery points on every snapshot and
* every dream, with no gate, no confirmation and no report. Its own
* comment calls it "the most destructive operation in the module",
* and a configured retention of zero silently removed every archive
* in the vault.
* 4. `deleteBySource --include-originals` reported a `snapshotRunId`
* and a `snapshotPath` for a deletion the archive does not cover:
* an original is only ever returned when it lies OUTSIDE `Brain/`,
* and the archive holds `Brain/` and nothing else.
*
* What this file deliberately does NOT cover:
*
* - the confirmation ladder in front of any of them. Whether
* `rollback` demands `--yes`, and whether `deleteBySource` is
* dry-run by default, are `rollback.test.ts`'s and
* `source-cleanup.test.ts`'s questions and are unchanged here.
* - archive CONTENT. That the tar round-trips is
* `brain.snapshot.test.ts`'s subject; this file asks only whether a
* recovery point EXISTS at the moment the bytes go.
* - dream's planning. The byte-identity measurement below covers the
* whole tree precisely so it does not have to enumerate what dream
* writes.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
readdirSync,
rmSync,
writeFileSync,
} from "node:fs";
import { createHash } from "node:crypto";
import { tmpdir } from "node:os";
import { dirname, join, relative, sep } from "node:path";
import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { dream } from "../../../src/core/brain/dream.ts";
import {
createSnapshot,
listSnapshots,
pruneSnapshots,
restoreSnapshot,
SNAPSHOT_PRUNE_REFUSAL,
SNAPSHOT_RETENTION_FLOOR,
} from "../../../src/core/brain/snapshot.ts";
import { restoreSnapshotWithRecoveryPoint } from "../../../src/core/brain/snapshot-gate.ts";
import { deleteBySource } from "../../../src/core/brain/source-cleanup.ts";
import { ingestSource } from "../../../src/core/brain/ingest/ingest.ts";
import {
RECOVERABILITY_BLOCKER,
RECOVERABILITY_STATE,
RECOVERY_COVERAGE,
} from "../../../src/core/brain/gates/recoverability.ts";
import { brainDirs, dreamWorkrunPath } from "../../../src/core/brain/paths.ts";
import { BRAIN_SNAPSHOT_REASON } from "../../../src/core/brain/types.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
import { maskLogChainDigests } from "../../helpers/vault-digest.ts";
import { useUnshardedLegacyLog } from "../../helpers/device-id.ts";
// The legacy day log and ledgers are read under their un-sharded names.
useUnshardedLegacyLog();
const NOW = new Date("2026-06-01T00:00:00Z");
let vault: string;
let configHome: string;
let configPath: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-b1-vault-"));
configHome = mkdtempSync(join(tmpdir(), "o2b-b1-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 });
});
/**
* One digest over everything a dream pass wrote under `Brain/`, with the
* five values that were never byte-reproducible in ANY release taken
* out. Each exclusion is a measured fact, not a convenience - three
* whole files first:
*
* - `.snapshots/` holds compressed tar archives whose bytes carry the
* mtimes of every file in them.
* - `vault-id.json` is minted per bootstrap, and its bytes ride into
* the daily log's filename shard - so the shard is normalised out of
* the PATH too, or two runs would differ by a filename alone.
* - `log/dream-runs/` is the workrun journal, whose `at` fields are
* wall clock by contract. Its phase ORDER is asserted separately,
* because that is the part a crashed pass is reconstructed from.
*
* And two values inside the content: `vault_name`, which is the vault
* directory's own basename and so differs for every temp fixture, and
* the `size_bytes` of the archive the pass took, which moves with the
* vault id above.
*
* This is `tests/helpers/vault-digest.ts` with those five holes in it.
* Everything else - every preference, every log line, every move - is
* compared byte for byte.
*/
function dreamOutputDigest(brainRoot: string): string {
return createHash("sha256").update(dreamOutputRows(brainRoot).join("\n")).digest("hex");
}
function dreamOutputRows(brainRoot: string): string[] {
const rows: string[] = [];
const walk = (dir: string): void => {
for (const entry of readdirSync(dir, { withFileTypes: true }).toSorted((a, b) =>
a.name.localeCompare(b.name),
)) {
const abs = join(dir, entry.name);
if (entry.isDirectory()) {
walk(abs);
continue;
}
if (!entry.isFile()) continue;
const rel = relative(brainRoot, abs).split(sep).join("/");
if (rel.startsWith(".snapshots/") || rel.startsWith("log/dream-runs/")) continue;
if (rel === "vault-id.json") continue;
// `_brain.yaml` is bootstrap output, not dream output - the pass
// reads it and nothing writes the decision back (`dream.ts:194`).
// It was inside this digest until a release that added commented
// config keys moved the number without touching a single byte the
// pass authored, which is a false alarm on a guard whose whole
// value is that it never fires falsely. Verified before excluding:
// with the config file out, main and this branch produce identical
// rows for every other file.
if (rel === "_brain.yaml") continue;
const path = rel.replace(/^log\/(\d{4}-\d{2}-\d{2})\.[0-9a-f]{8}\./, "log/$1.");
// The chain hash over each JSONL row covers `size_bytes`, so the
// one value normalised above propagates into every row's `h` and
// into the `prev` that follows it - see `maskLogChainDigests`.
const text = maskLogChainDigests(
readFileSync(abs, "utf8")
.replace(/^vault_name: .*$/gm, "vault_name: <name>")
.replace(/^- size_bytes: \d+$/gm, "- size_bytes: <n>")
.replace(/"size_bytes":"\d+"/g, String.raw`"size_bytes":"<n>"`),
);
rows.push(`${path}\t${createHash("sha256").update(text).digest("hex")}`);
}
};
walk(brainRoot);
return rows.toSorted();
}
/** A signal in the inbox, which is what gives a dream pass work to do. */
function seedSignal(slug: string): void {
writeFileSync(
join(brainDirs(vault).inbox, `sig-2026-05-14-${slug}.md`),
`---\nkind: brain-signal\nid: sig-2026-05-14-${slug}\ntopic: ${slug}\nsignal: positive\n` +
`principle: keep ${slug} tidy\ncreated_at: 2026-05-14T00:00:00Z\nagent: tester\n` +
`---\n\n## Raw\n\nseed\n`,
"utf8",
);
}
// ----- 1. restoreSnapshot ---------------------------------------------------
describe("a rollback keeps what it discards", () => {
test("the live tree is archived before it is deleted, and survives the restore", () => {
createSnapshot(vault, "manual-baseline", { reason: BRAIN_SNAPSHOT_REASON.manual, now: NOW });
// Diverge the live tree from the archive. This file exists ONLY in
// the live tree, so it is exactly what a rollback destroys.
const doomed = join(brainDirs(vault).inbox, "sig-2026-05-20-only-live.md");
writeFileSync(doomed, "---\nkind: brain-signal\n---\n\n## Raw\n\nlive only\n", "utf8");
const out = restoreSnapshotWithRecoveryPoint(vault, "manual-baseline", { now: NOW });
expect(existsSync(doomed)).toBe(false);
expect(out.recoverability.state).toBe(RECOVERABILITY_STATE.covered);
expect(out.recoverability.coverage).toEqual([RECOVERY_COVERAGE.brainTopLevel]);
// The producerless reason gets its first producer, and the archive
// it minted is still on disk: `.snapshots/` is excluded from the
// restore's deletion, which is what makes this recoverable at all.
expect(out.recoveryPoint.runId.startsWith(BRAIN_SNAPSHOT_REASON.manual)).toBe(true);
expect(existsSync(out.recoveryPoint.path)).toBe(true);
expect(listSnapshots(vault).snapshots.map((s) => s.run_id)).toContain(out.recoveryPoint.runId);
});
test("the recovery point is taken after extraction, so a corrupt archive mints nothing", () => {
// Ordering matters: a rollback that cannot read its target must not
// leave an archive of a tree it never touched.
const before = listSnapshots(vault).snapshots.length;
expect(() => restoreSnapshotWithRecoveryPoint(vault, "manual-absent", { now: NOW })).toThrow();
expect(listSnapshots(vault).snapshots.length).toBe(before);
});
test("a direct restore says it proved nothing rather than staying silent", () => {
createSnapshot(vault, "manual-direct", { reason: BRAIN_SNAPSHOT_REASON.manual, now: NOW });
const result = restoreSnapshot(vault, "manual-direct");
expect(result.recoverability.state).toBe(RECOVERABILITY_STATE.unproven);
expect(result.recoverability.blockers).toContain(RECOVERABILITY_BLOCKER.noRecoveryPoint);
});
});
// ----- 2. The dream pass ----------------------------------------------------
describe("the dream pass runs behind the gate, not beside it", () => {
test("dream output over the fixture vault is the digest the previous release produced", () => {
// MEASURED, not asserted. The literal below was computed by running
// this exact fixture against the tree WITHOUT this unit and pasted
// here; it then had to keep matching with the unit applied. A
// recomputed expectation would prove nothing at all.
//
// Re-measured once, in nothing-runs-unwatched, when `_brain.yaml`
// left the row set: the digest had moved because a commented config
// key made the bootstrapped template longer, which is not a byte the
// pass authored. The replacement literal was taken from `main` with
// the same exclusion applied, and this branch reproduces it - so it
// is still a number from a tree without the units it guards, not a
// number this branch invented about itself.
//
// Re-measured a second time, in nothing-writes-silently, and for a
// byte the pass DOES author: every log event and every signal now
// carries an `origin_channel` stamp, the server-derived channel of
// the writing process (Unit C). The digest below is the tree with
// that unit and WITHOUT the snapshot gate this file guards, taken
// the same way as the two before it, so what it still proves is the
// same claim: the gate authors none of these bytes.
//
// Re-measured a THIRD time, in who-wrote-what, and again for bytes
// the pass does author: every JSONL log row now carries `prev` and
// `h`, the per-shard hash chain (Task E). Unlike the two before it
// this literal was taken on the branch that adds the chain rather
// than on a tree without the unit, because the chain is computed
// inside the appender the pass calls and there is no build of it to
// measure the pass against. What the number still guards is that it
// does not move again without a named reason - and the masking in
// `dreamOutputRows` is what keeps it a guard rather than a coin
// flip: `size_bytes` is inside the hashed payload, so without the
// mask this digest would differ on every run.
//
// Re-measured a FOURTH time, for the inbox archive (issue #195), and
// for two named reasons only: the fixture's signal is 18 days old at
// NOW, outside the 14-day contradiction window, so the pass now moves
// it to `inbox/archived/` and lists it in the dream event; and the
// bootstrapped `_BRAIN.md` names the new directory. Verified before
// updating: with `dream.archive_stale_signals: false` and the previous
// manual template this branch reproduces the previous literal exactly.
//
// Re-measured a FIFTH time, for one named reason: the bootstrapped
// `_BRAIN.md` carries a `template_revision:` line in its frontmatter,
// so a release never rewrites a manual a newer release wrote. Verified
// before updating: with that one template line removed, this branch
// reproduces the previous literal exactly.
seedSignal("tidy");
dream(vault, { now: NOW, agentName: "tester" });
expect(dreamOutputDigest(join(vault, "Brain"))).toBe(
"044a18bcd0538c768e0c5d98e071125683805ceb6579f2acbadc96916a126210",
);
});
test("the workrun phase sequence is unchanged, which is the part with meaning", () => {
// The workrun journal is excluded from the digest above because its
// timestamps are wall clock. Its ORDER is not: it is the record a
// crashed pass is reconstructed from, and moving the snapshot onto
// the gate moved the point at which the journal opens.
seedSignal("tidy");
const summary = dream(vault, { now: NOW, agentName: "tester" });
const journal = readFileSync(dreamWorkrunPath(vault, summary.run_id), "utf8")
.split("\n")
.filter((line) => line.trim().length > 0)
.map((line) => (JSON.parse(line) as { phase: string }).phase);
expect(journal).toEqual([
"started",
"cluster_complete",
"close_complete",
"promote_complete",
"synthesize_complete",
"retire_complete",
"heal_complete",
"reconcile_complete",
"finalized",
]);
});
test("the archive still carries the dream run id, not a second id of its own", () => {
seedSignal("tidy");
const summary = dream(vault, { now: NOW, agentName: "tester" });
const ids = listSnapshots(vault).snapshots.map((s) => s.run_id);
expect(ids).toContain(summary.run_id);
// Exactly one archive per run. A gate that minted its own id beside
// dream's would leave two, and the workrun would name neither.
expect(ids.filter((id) => id.startsWith(BRAIN_SNAPSHOT_REASON.dream)).length).toBe(1);
});
test("a run id already taken by a workrun is laddered past, as it was before", () => {
// The dream run id has to be free in the snapshot directory AND the
// workrun directory; the gate's collision ladder is now the only one.
seedSignal("tidy");
const taken = dreamWorkrunPath(vault, `${BRAIN_SNAPSHOT_REASON.dream}-2026-06-01-000000`);
mkdirSync(dirname(taken), { recursive: true });
writeFileSync(taken, "", "utf8");
const summary = dream(vault, { now: NOW, agentName: "tester" });
expect(summary.run_id).toBe(`${BRAIN_SNAPSHOT_REASON.dream}-2026-06-01-000000-2`);
});
test("a dry run still takes no snapshot at all", () => {
seedSignal("tidy");
dream(vault, { now: NOW, dryRun: true, agentName: "tester" });
expect(listSnapshots(vault).snapshots).toEqual([]);
});
});
// ----- 3. pruneSnapshots ----------------------------------------------------
describe("the prune has a floor and says what it did", () => {
function seedArchives(count: number): void {
for (let i = 1; i <= count; i++) {
createSnapshot(vault, `manual-seed-${i}`, {
reason: BRAIN_SNAPSHOT_REASON.manual,
now: new Date(NOW.getTime() + i * 1000),
});
}
}
test("a retention below the floor is refused by name, not obeyed", () => {
seedArchives(3);
const result = pruneSnapshots(vault, 0);
expect(result.refusal).toBe(SNAPSHOT_PRUNE_REFUSAL.belowRetentionFloor);
expect(result.deleted).toEqual([]);
// The whole point: the archives are still there.
expect(listSnapshots(vault).snapshots.length).toBe(3);
});
test("the floor is the smallest retention that keeps a way back", () => {
expect(SNAPSHOT_RETENTION_FLOOR).toBe(1);
seedArchives(3);
const result = pruneSnapshots(vault, SNAPSHOT_RETENTION_FLOOR);
expect(result.refusal).toBeNull();
expect(result.deleted.length).toBe(2);
expect(result.retained).toBe(1);
});
test("what it removed is reported rather than trimmed in silence", () => {
seedArchives(3);
const result = pruneSnapshots(vault, 2);
expect(result.deleted.length).toBe(1);
expect(result.retained).toBe(2);
expect(result.failed).toEqual([]);
});
test("a prune with nothing to do reports nothing removed and no refusal", () => {
seedArchives(2);
const result = pruneSnapshots(vault, 10);
expect(result).toEqual({ deleted: [], failed: [], retained: 2, refusal: null });
});
});
// ----- 4. deleteBySource --include-originals --------------------------------
describe("delete-by-source stops overclaiming its recovery point", () => {
function seedSource(): void {
mkdirSync(join(vault, "imports"), { recursive: true });
writeFileSync(join(vault, "imports", "benchmark.md"), "benchmark rows\n", "utf8");
ingestSource(
vault,
{
sourcePath: "imports/benchmark.md",
summary: "Benchmark import summary.",
extraction: { entities: [{ category: "concept", name: "BenchWidget" }] },
},
{ agent: "tester", now: NOW },
);
}
test("without --include-originals the archive really does cover the deletion", () => {
seedSource();
const plan = deleteBySource(vault, "imports/benchmark.md", { confirm: true, now: NOW });
expect(plan.recoverability.state).toBe(RECOVERABILITY_STATE.covered);
expect(plan.recoverability.blockers).toEqual([]);
expect(existsSync(join(vault, "imports", "benchmark.md"))).toBe(true);
});
test("with --include-originals it names the bytes no archive holds", () => {
seedSource();
const plan = deleteBySource(vault, "imports/benchmark.md", {
confirm: true,
includeOriginals: true,
now: NOW,
});
// The original is gone and it was never in an archive.
expect(existsSync(join(vault, "imports", "benchmark.md"))).toBe(false);
expect(plan.recoverability.state).toBe(RECOVERABILITY_STATE.partial);
expect(plan.recoverability.coverage).toEqual([RECOVERY_COVERAGE.brainTopLevel]);
expect(plan.recoverability.blockers).toEqual([RECOVERABILITY_BLOCKER.outsideBrainRoot]);
// The recovery point is still reported: the verdict qualifies it
// rather than replacing it.
expect(plan.snapshotRunId).not.toBeNull();
});
test("a dry run promises nothing, because it destroys nothing", () => {
seedSource();
const plan = deleteBySource(vault, "imports/benchmark.md", { includeOriginals: true });
expect(plan.recoverability.state).toBe(RECOVERABILITY_STATE.nothingAtRisk);
expect(plan.snapshotRunId).toBeNull();
});
test("a confirmed run with no work reports nothing at risk, not a lost archive", () => {
const plan = deleteBySource(vault, "imports/absent.md", { confirm: true, now: NOW });
expect(plan.recoverability.state).toBe(RECOVERABILITY_STATE.nothingAtRisk);
expect(readdirSync(join(brainDirs(vault).brain, ".snapshots")).length).toBe(0);
});
});