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
/**
* A consolidation pass reports while it runs (nothing-runs-unwatched, U1).
*
* Before this, `dream` produced its first observable output after it had
* already finished, so a caller could not tell a slow pass from a hung
* one. The properties pinned here are the ones that make the stream worth
* having: it starts, it advances, it terminates, and a run that changed
* nothing terminates too - an idempotent rerun is the common case, and an
* unterminated stream would make it look like a pass that died in
* planning.
*
* The last test is the load-bearing one for the rest of the release: a
* pass with no sink attached must be byte-identical to the previous
* release. Absence of an observer is not a feature flag.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { cpSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { dream } from "../../../src/core/brain/dream.ts";
import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import {
PROGRESS_KIND,
PROGRESS_REASON,
type ProgressEvent,
} from "../../../src/core/brain/progress.ts";
import {
createSafeguard,
OPERATION,
SafeguardAbortError,
} from "../../../src/core/brain/safeguard.ts";
import { writeSignal } from "../../../src/core/brain/signal.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
import { treeEntries, digestVaultTree } from "../../helpers/vault-digest.ts";
let vault: string;
let configHome: string;
let configPath: string;
const NOW = new Date("2026-05-23T12:00:00Z");
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-dream-progress-"));
configHome = mkdtempSync(join(tmpdir(), "o2b-dream-progress-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 });
});
/** Three same-sign signals on one topic: enough to plan a promotion. */
function seedPromotion(topic = "progress-topic"): void {
for (const [i, date] of ["2026-05-20", "2026-05-21", "2026-05-22"].entries()) {
writeSignal(vault, {
topic,
signal: "positive",
agent: "claude",
principle: `Prefer the ${topic} approach`,
created_at: `${date}T10:00:00Z`,
date,
slug: `${topic}-${i}`,
scope: "writing",
});
}
}
function record(): { events: ProgressEvent[]; sink: (e: ProgressEvent) => void } {
const events: ProgressEvent[] = [];
return { events, sink: (e) => events.push(e) };
}
describe("dream progress", () => {
test("a changing run starts, advances through its stages, and finishes", () => {
seedPromotion();
const { events, sink } = record();
dream(vault, { now: NOW, onProgress: sink });
expect(events.length).toBeGreaterThan(0);
expect(events.every((e) => e.operation === OPERATION.dream)).toBe(true);
expect(events[0]?.kind).toBe(PROGRESS_KIND.started);
expect(events.at(-1)?.kind).toBe(PROGRESS_KIND.finished);
// Every stage the pass declares must actually be entered, in order,
// or the stream is describing a pass that did not happen.
const started = events.filter((e) => e.kind === PROGRESS_KIND.started).map((e) => e.stage);
expect(started).toEqual(["scan", "plan", "apply", "log", "finalize"]);
});
test("a no-op rerun still terminates its stream", () => {
seedPromotion();
dream(vault, { now: NOW });
const { events, sink } = record();
dream(vault, { now: NOW, onProgress: sink });
expect(events.at(-1)?.kind).toBe(PROGRESS_KIND.finished);
});
test("a dry run reports progress and still writes nothing", () => {
seedPromotion();
const before = digestVaultTree(vault);
const { events, sink } = record();
dream(vault, { now: NOW, dryRun: true, onProgress: sink });
expect(events.at(-1)?.kind).toBe(PROGRESS_KIND.finished);
expect(digestVaultTree(vault)).toEqual(before);
});
test("attaching an observer changes nothing the pass writes", () => {
// Compared against a COPY of the same seeded vault rather than a
// second bootstrap: a freshly bootstrapped vault carries its own
// identity and its own root path inside `Brain/vault-id.json` and
// `Brain/_BRAIN.md`, so two independent vaults differ before either
// pass runs. The copy makes the comparison legitimate - identical
// bytes in, so any difference out belongs to the observer.
seedPromotion();
const observed = mkdtempSync(join(tmpdir(), "o2b-dream-progress-b-"));
try {
cpSync(vault, observed, { recursive: true });
const silent = dream(vault, { now: NOW });
const { events, sink } = record();
const watched = dream(observed, { now: NOW, onProgress: sink });
expect(events.length).toBeGreaterThan(0);
expect(watched.changed).toBe(silent.changed);
// Two exclusions, each for a reason that predates this unit and is
// not about the observer:
// - the pre-run archive is a tar, and a tar carries the mtimes of
// the tree it was taken from, which the harness wrote at two
// different instants;
// - the workrun journal stamps `new Date().toISOString()` per
// line even when the caller injected a clock, because it is
// forensic evidence of when the pass really ran.
// Everything else the pass authored is compared.
const EXCLUDED_PREFIXES = ["Brain/.snapshots/", "Brain/log/dream-runs/"];
// The archive's SIZE escapes that first exclusion: the snapshot log
// entry records `size_bytes`, so the tar's mtime nondeterminism is
// republished into a file this assertion does compare, and the two
// trees' mtimes differ whenever the copy straddles a second. The
// field is NORMALISED rather than the day log excluded - excluding
// it would drop the pass's main authored artifact from the
// comparison, which is most of what this test is for. Every other
// member of that entry (run_id, reason, channel) still compares.
const ARCHIVE_SIZE_FIELD = /(size_bytes"?:\s*"?)\d+/g;
const ARCHIVE_SIZE_PLACEHOLDER = "$1<archive-size>";
// The chain hashes carry that size with them, so normalising the
// field alone leaves the nondeterminism in the two places the
// field was taken out of. `h` is computed over the payload
// INCLUDING the real `size_bytes`, and every later line in the day
// log chains off it through `prev`, so one straddled second
// re-keys the whole file - which is this test failing on a loaded
// CI runner and passing on every developer box.
//
// The chain is not what this test is for, and it is not left
// unguarded: the log-integrity suites verify it end to end. What
// this one asserts is that attaching an observer changes nothing
// the pass AUTHORED, and what the pass authored is the payloads.
// `prev: null` is a literal, not a digest, and stays.
const CHAIN_HASH_FIELD = /("(?:h|prev)":")[0-9a-f]{64}"/g;
const CHAIN_HASH_PLACEHOLDER = '$1<chain-hash>"';
const NORMALISED_PREFIX = "Brain/log/";
const authored = (root: string): Map<string, string> => {
const kept = new Map<string, string>();
for (const [path, digest] of treeEntries(root)) {
if (EXCLUDED_PREFIXES.some((prefix) => path.startsWith(prefix))) continue;
// Digest everywhere else; the day log is text, so it is compared
// as normalised text and a mismatch prints the offending line.
kept.set(
path,
path.startsWith(NORMALISED_PREFIX) && digest !== "d"
? readFileSync(join(root, path), "utf8")
.replaceAll(ARCHIVE_SIZE_FIELD, ARCHIVE_SIZE_PLACEHOLDER)
.replaceAll(CHAIN_HASH_FIELD, CHAIN_HASH_PLACEHOLDER)
: digest,
);
}
return kept;
};
expect(authored(observed)).toEqual(authored(vault));
} finally {
rmSync(observed, { recursive: true, force: true });
}
});
test("a pre-aborted signal stops the pass and says so on the stream", () => {
// SafeguardAbortError was unreachable in production before this
// release: the class, the signal field and the abort-beats-deadline
// priority were all written, and no call site passed a signal. This
// is the test that proves the wiring, and it does it without racing a
// real interrupt against a sub-second pass.
seedPromotion();
const controller = new AbortController();
controller.abort();
const { events, sink } = record();
expect(() =>
dream(vault, {
now: NOW,
onProgress: sink,
safeguard: createSafeguard({ operation: OPERATION.dream, signal: controller.signal }),
}),
).toThrow(SafeguardAbortError);
// The stream must end with a stop, not simply end: a caller cannot
// otherwise tell a cancelled pass from a crashed or hung one.
expect(events.at(-1)).toMatchObject({
kind: PROGRESS_KIND.stopped,
reason: PROGRESS_REASON.aborted,
});
});
test("a sink that throws does not fail the pass, and does not vanish either", () => {
seedPromotion();
let calls = 0;
const summary = dream(vault, {
now: NOW,
onProgress: () => {
calls += 1;
throw new Error("stream closed");
},
});
expect(summary.changed).toBe(true);
// Detached after the first failure: a stream that fails on the first
// tick would otherwise fail on every one.
expect(calls).toBe(1);
expect(summary.warnings.map((w) => w.code)).toContain("progress-sink-failed");
});
});