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
/**
* `o2b brain dream` under observation, and under a Ctrl-C.
*
* Two properties that only exist at the CLI boundary:
*
* 1. `--progress` writes newline-delimited records to STDERR while the
* pass runs, and stdout stays exactly what it was. A progress line
* on stdout would corrupt the payload `--json` callers parse, which
* is the whole reason the rail exists.
* 2. The staged lifecycle carries the same stream: staging IS a dream
* pass, so `o2b brain dream stage --progress` reports the same five
* stages under the same operation name rather than nothing at all.
* 3. This verb does NOT advertise a cooperative interrupt. `dreamRun`
* is synchronous end to end, so a signal handler cannot run while it
* does; Ctrl-C keeps its default meaning and kills the process.
*/
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { EXIT_INTERRUPTED, interruptIsObservable } from "../../src/cli/interrupt.ts";
import { PROGRESS_KIND } from "../../src/core/brain/progress.ts";
import { OPERATION } from "../../src/core/brain/safeguard.ts";
import { writeSignal } from "../../src/core/brain/signal.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
import { runCli } from "../helpers/run-cli.ts";
import { progressRecords } from "../helpers/progress-records.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";
// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);
let vault: string;
let configHome: string;
let configPath: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-cli-dream-progress-"));
configHome = mkdtempSync(join(tmpdir(), "o2b-cli-dream-progress-cfg-"));
configPath = join(configHome, "config.yaml");
atomicWriteFileSync(configPath, `vault: ${vault}\n`);
bootstrapBrain(vault, { configPath });
for (const [i, date] of ["2026-05-20", "2026-05-21", "2026-05-22"].entries()) {
writeSignal(vault, {
topic: "cli-progress",
signal: "positive",
agent: "claude",
principle: "Prefer the cli-progress approach",
created_at: `${date}T10:00:00Z`,
date,
slug: `cli-progress-${i}`,
scope: "writing",
});
}
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
rmSync(configHome, { recursive: true, force: true });
});
const env = (): Record<string, string> => ({ OPEN_SECOND_BRAIN_CONFIG: configPath });
const RUN_ID_MASK = "<run-id>";
/** The `--json` stdout with every occurrence of its own run id masked. */
function withoutRunId(stdout: string): string {
const runId = (JSON.parse(stdout) as Record<string, unknown>)["run_id"];
if (typeof runId !== "string" || runId === "")
throw new Error("dream --json stdout has no run_id");
return stdout.replaceAll(runId, RUN_ID_MASK);
}
describe("o2b brain dream --progress", () => {
test("writes records to stderr and leaves stdout untouched", async () => {
const plain = await runCli(["brain", "dream", "--dry-run", "--json"], { env: env() });
const watched = await runCli(["brain", "dream", "--dry-run", "--json", "--progress"], {
env: env(),
});
expect(plain.returncode).toBe(0);
expect(watched.returncode).toBe(0);
// The payload a caller parses is byte-identical with and without the
// observer. Progress that changed stdout would be a regression, not a
// feature. The run id is minted per second, so two runs that straddle
// a second boundary differ there and nowhere else: it is masked
// wherever it appears (target paths embed it too) before the compare.
expect(withoutRunId(watched.stdout)).toBe(withoutRunId(plain.stdout));
const records = progressRecords(watched.stderr);
expect(records.length).toBeGreaterThan(0);
expect(records.every((r) => r["operation"] === OPERATION.dream)).toBe(true);
expect(records[0]?.["kind"]).toBe(PROGRESS_KIND.started);
expect(records.at(-1)?.["kind"]).toBe(PROGRESS_KIND.finished);
expect(progressRecords(plain.stderr)).toHaveLength(0);
});
test("is observed once, not once per entry point", async () => {
// The staged block and the inline pass each attach the rail, and
// `run` falls THROUGH the staged block to the inline pass. A staged
// attachment that did not exclude `run` would build two observers for
// one pass, and the stream would carry every record twice.
const watched = await runCli(["brain", "dream", "--dry-run", "--progress"], { env: env() });
const records = progressRecords(watched.stderr);
expect(records.length).toBeGreaterThan(0);
// One terminator for one run, and one `started` per distinct stage.
expect(records.filter((r) => r["kind"] === PROGRESS_KIND.finished)).toHaveLength(1);
const opened = records
.filter((r) => r["kind"] === PROGRESS_KIND.started)
.map((r) => r["stage"]);
expect(opened).toEqual([...new Set(opened)]);
});
test("integers and identifiers only - no prose on the structured stream", async () => {
const watched = await runCli(["brain", "dream", "--dry-run", "--progress"], { env: env() });
for (const record of progressRecords(watched.stderr)) {
expect(typeof record["stage"]).toBe("string");
// An identifier, never a sentence: the human line is rendered from
// this at the edge, which is the rule that keeps the advisory rail
// free of caller-supplied prose too.
expect(String(record["stage"])).toMatch(/^[a-z0-9]+([-_][a-z0-9]+)*$/);
expect(Number.isInteger(record["completed"])).toBe(true);
}
});
});
describe("o2b brain dream stage --progress", () => {
test("watches the staged pass, which is a dream pass", async () => {
// `DreamStageOptions.onProgress` was declared and threaded through
// all three staged entry points with no caller able to ask: the verb
// parsed `--progress` for `stage` and ignored it, so an operator
// watching a staged pass saw nothing. This is the producer.
const watched = await runCli(["brain", "dream", "stage", "--json", "--progress"], {
env: env(),
});
expect(watched.returncode).toBe(0);
const records = progressRecords(watched.stderr);
expect(records.length).toBeGreaterThan(0);
// Staging IS a dream call, so the records name `dream` rather than a
// second operation reporting the same five stages under a new name.
expect(records.every((r) => r["operation"] === OPERATION.dream)).toBe(true);
expect(records[0]?.["kind"]).toBe(PROGRESS_KIND.started);
expect(records.at(-1)?.["kind"]).toBe(PROGRESS_KIND.finished);
});
test("stdout is untouched, as it is for the inline pass", async () => {
const plain = await runCli(["brain", "dream", "stage", "--json"], { env: env() });
const watched = await runCli(["brain", "dream", "stage", "--json", "--progress"], {
env: env(),
});
expect(plain.returncode).toBe(0);
expect(watched.returncode).toBe(0);
// Two runs of `stage` mint different run ids, so the comparison is of
// the payload's SHAPE rather than its bytes - the run id is the one
// field that is expected to differ.
expect(Object.keys(JSON.parse(watched.stdout) as object).toSorted()).toEqual(
Object.keys(JSON.parse(plain.stdout) as object).toSorted(),
);
expect(progressRecords(plain.stderr)).toHaveLength(0);
});
});
describe("stopping a dream pass", () => {
test("is not advertised as a cooperative interrupt, because it cannot be one", () => {
// `dreamRun` is synchronous end to end, so a signal handler cannot
// run while it does and `o2b brain dream` opens no handle. The
// keystroke keeps its default meaning - it kills the process - which
// is asserted where it belongs, in `interrupt-observability.test.ts`.
// What is pinned here is that this verb is not claiming otherwise.
expect(interruptIsObservable(OPERATION.dream)).toBe(false);
// And that the code a verb WOULD return is still not a success code,
// for the two verbs that can reach it.
expect(EXIT_INTERRUPTED).toBe(130);
expect(EXIT_INTERRUPTED).not.toBe(0);
});
});