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
/**
* The two shipped dream capabilities reach an operator (no-dead-ends,
* phase 3, item 1).
*
* `runDreamStep` and the per-run gate override both landed as TypeScript
* arguments with no flag, no MCP argument and no way to reach them from a
* shell. The kanban unit they implement asked for exactly the operator
* capability - run a targeted pass "without the stateful, error-prone
* dance of toggling phase gates and remembering to revert them" - so a
* TypeScript-only argument does not deliver it.
*
* What is asserted here:
* - both runnable steps run from `o2b brain dream --step <name>`;
* - every other token is REFUSED BY NAME, carrying the specific reason
* and the runnable set, on both the human and the `--json` stream;
* - `--gate <name>=<true|false>` steers one run and leaves
* `Brain/_brain.yaml` byte-identical;
* - the same two capabilities exist on MCP `brain_dream`;
* - with neither flag present the verb is byte-identical to today;
* - a CONFIGURED salience threshold is named on the human stream -
* admitted of considered, and the threshold - so an exclusion is not
* invisible to an operator who never passes `--json`. An open gate
* adds nothing, which is what keeps the byte-identical claim above
* true.
*/
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, spyOn, test } from "bun:test";
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { writePreference } from "../../src/core/brain/preference.ts";
import { writeSignal } from "../../src/core/brain/signal.ts";
import { BRAIN_PREFERENCE_STATUS } from "../../src/core/brain/types.ts";
import { DREAM_PHASE } from "../../src/core/brain/dream-phases.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
import { TRANSPORT_REACH } from "../../src/core/graph/transport-reach.ts";
import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
import { cmdBrainDream } from "../../src/cli/brain/verbs/dream.ts";
import { runCli } from "../helpers/run-cli.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 tmp: string;
let vault: string;
let configPath: string;
const savedEnv: Record<string, string | undefined> = {};
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-dream-operator-"));
vault = join(tmp, "vault");
configPath = join(tmp, "config.yaml");
for (const key of [
"VAULT_AGENT_NAME",
"VAULT_TIMEZONE",
"VAULT_DIR",
"OPEN_SECOND_BRAIN_CONFIG",
]) {
savedEnv[key] = process.env[key];
delete process.env[key];
}
writeFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
bootstrapBrain(vault, { configPath });
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
for (const [key, value] of Object.entries(savedEnv)) {
if (value === undefined) delete process.env[key];
else process.env[key] = value;
}
});
const brainConfigPath = (): string => join(vault, "Brain", "_brain.yaml");
/** Three same-sign signals: enough that a full pass promotes them. */
function seedPromotion(topic = "operator-surface"): 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 operated approach",
created_at: `${date}T10:00:00Z`,
date,
slug: `op${i}`,
scope: "writing",
});
}
}
/**
* Two user pages where one mentions the other's exact title, so the
* heal enrichment has something deterministic to rewrite.
*/
function makeLinkableNotes(): string {
const notes = join(vault, "Notes");
mkdirSync(notes, { recursive: true });
writeFileSync(join(notes, "target.md"), "---\ntitle: Widget Registry\n---\n\nBody.\n", "utf8");
const refPath = join(notes, "ref.md");
writeFileSync(
refPath,
"---\ntitle: Reference Page\n---\n\nSee the Widget Registry for details.\n",
"utf8",
);
return refPath;
}
async function makeServer(): Promise<MCPServer> {
// A real dream pass and a single step run at local reach only.
const server = new MCPServer({ vault, configPath }, { reach: TRANSPORT_REACH.local });
await server.handleRequest({
jsonrpc: JSONRPC_VERSION,
id: 1,
method: "initialize",
params: {
protocolVersion: PROTOCOL_VERSION,
capabilities: {},
clientInfo: { name: "dream-operator-test", version: "0" },
},
});
await server.handleRequest({ jsonrpc: JSONRPC_VERSION, method: "notifications/initialized" });
return server;
}
let callId = 100;
async function callDream(
server: MCPServer,
args: Record<string, unknown>,
): Promise<{ structured?: Record<string, unknown>; errorCode?: number; errorMessage?: string }> {
callId += 1;
const r = (await server.handleRequest({
jsonrpc: JSONRPC_VERSION,
id: callId,
method: "tools/call",
params: { name: "brain_dream", arguments: args },
})) as {
result?: { structuredContent?: Record<string, unknown> };
error?: { code: number; message: string };
};
if (r.error) return { errorCode: r.error.code, errorMessage: r.error.message };
return { structured: r.result?.structuredContent };
}
describe("o2b brain dream --step", () => {
test("runs the scan step and reports only what the scan observed", async () => {
seedPromotion();
const r = await runCli(["brain", "dream", "--step", "scan", "--vault", vault, "--json"]);
expect(r.returncode).toBe(0);
const payload = JSON.parse(r.stdout);
expect(payload.step).toBe("scan");
expect(payload.partial).toBe(true);
expect(payload.active_signals).toBe(3);
expect(payload.preferences).toBe(0);
// A partial result must not assert the fields a full pass owns.
expect(payload).not.toHaveProperty("run_id");
expect(payload).not.toHaveProperty("changed");
// A pure read promotes nothing.
const after = await runCli(["brain", "dream", "--step", "scan", "--vault", vault, "--json"]);
expect(JSON.parse(after.stdout).preferences).toBe(0);
});
test("runs the heal-enrich step even with the config gate off", async () => {
const refPath = makeLinkableNotes();
const before = readFileSync(brainConfigPath(), "utf8");
const r = await runCli(["brain", "dream", "--step", "heal-enrich", "--vault", vault, "--json"]);
expect(r.returncode).toBe(0);
const payload = JSON.parse(r.stdout);
expect(payload.step).toBe("heal-enrich");
expect(payload.partial).toBe(true);
expect(payload.enriched).toBe(1);
expect(readFileSync(refPath, "utf8")).toContain("[[Widget Registry]]");
// Asking for the step IS the opt-in; it never writes the config back.
expect(readFileSync(brainConfigPath(), "utf8")).toBe(before);
});
test("human output names the step and its counters", async () => {
seedPromotion();
const r = await runCli(["brain", "dream", "--step", "scan", "--vault", vault]);
expect(r.returncode).toBe(0);
expect(r.stdout).toContain("step: scan\n");
expect(r.stdout).toContain("active_signals: 3\n");
});
test("refuses a reporting phase by name and prints the runnable set", async () => {
const r = await runCli(["brain", "dream", "--step", DREAM_PHASE.synthesize, "--vault", vault]);
expect(r.returncode).toBe(2);
expect(r.stdout).toBe("");
expect(r.stderr).toContain(`dream step '${DREAM_PHASE.synthesize}' is not independently`);
// The SPECIFIC reason, not a generic "unsupported".
expect(r.stderr).toContain("planRefresh and planAutoRetires mutate each other's accumulators");
expect(r.stderr).toContain("Independently runnable steps: scan, heal-enrich");
});
test("refuses a token that is not even a reporting phase", async () => {
const r = await runCli(["brain", "dream", "--step", "hibernate", "--vault", vault]);
expect(r.returncode).toBe(2);
expect(r.stderr).toContain(
"it is neither a runnable dream step nor one of the dream reporting phases",
);
expect(r.stderr).toContain("Independently runnable steps: scan, heal-enrich");
});
test("every non-runnable phase is refused, each with its own reason", async () => {
const reasons = new Set<string>();
for (const phase of Object.values(DREAM_PHASE)) {
// oxlint-disable-next-line no-await-in-loop -- runCli patches process.stdout in-process, so concurrent invocations would interleave each other's captured output
const r = await runCli(["brain", "dream", "--step", phase, "--vault", vault]);
expect(`${phase} exit: ${r.returncode}`).toBe(`${phase} exit: 2`);
reasons.add(r.stderr);
}
expect(reasons.size).toBe(Object.values(DREAM_PHASE).length);
});
test("the refusal is a clean JSON payload under --json", async () => {
const r = await runCli([
"brain",
"dream",
"--step",
DREAM_PHASE.log,
"--vault",
vault,
"--json",
]);
expect(r.returncode).toBe(2);
const payload = JSON.parse(r.stdout);
expect(payload.ok).toBe(false);
expect(payload.step).toBe(DREAM_PHASE.log);
expect(payload.runnable).toEqual(["scan", "heal-enrich"]);
expect(typeof payload.reason).toBe("string");
expect(payload.reason.length).toBeGreaterThan(0);
});
test("refuses --step combined with the flags a full pass owns", async () => {
for (const extra of [["--dry-run"], ["--strict"], ["--expect", "0"]]) {
// oxlint-disable-next-line no-await-in-loop -- runCli patches process.stdout in-process, so concurrent invocations would interleave each other's captured output
const r = await runCli(["brain", "dream", "--step", "scan", ...extra, "--vault", vault]);
expect(`${extra[0]} exit: ${r.returncode}`).toBe(`${extra[0]} exit: 2`);
expect(r.stderr).toContain(extra[0]!);
}
});
test("refuses --step on an action other than run", async () => {
const r = await runCli(["brain", "dream", "list", "--step", "scan", "--vault", vault]);
expect(r.returncode).toBe(2);
expect(r.stderr).toContain("--step");
expect(r.stderr).toContain("list");
});
});
describe("o2b brain dream --gate", () => {
test("turns the heal gate on for one run and leaves the config byte-identical", async () => {
seedPromotion();
const refPath = makeLinkableNotes();
const before = readFileSync(brainConfigPath(), "utf8");
const r = await runCli([
"brain",
"dream",
"--gate",
"heal_enrich=true",
"--now",
"2026-05-30T10:00:00Z",
"--vault",
vault,
"--json",
]);
expect(r.returncode).toBe(0);
expect(JSON.parse(r.stdout).changed).toBe(true);
expect(readFileSync(refPath, "utf8")).toContain("[[Widget Registry]]");
expect(readFileSync(brainConfigPath(), "utf8")).toBe(before);
});
test("turns the heal gate off for one run on a vault whose config enables it", async () => {
seedPromotion();
const refPath = makeLinkableNotes();
writeFileSync(
brainConfigPath(),
"schema_version: 1\ndream:\n heal_enrich_enabled: true\n",
"utf8",
);
const before = readFileSync(brainConfigPath(), "utf8");
const r = await runCli([
"brain",
"dream",
"--gate",
"heal_enrich=false",
"--now",
"2026-05-30T10:00:00Z",
"--vault",
vault,
"--json",
]);
expect(r.returncode).toBe(0);
expect(readFileSync(refPath, "utf8")).not.toContain("[[Widget Registry]]");
expect(readFileSync(brainConfigPath(), "utf8")).toBe(before);
});
test("refuses an unknown gate name, listing the known ones", async () => {
const r = await runCli(["brain", "dream", "--gate", "retire_floor=true", "--vault", vault]);
expect(r.returncode).toBe(2);
expect(r.stderr).toContain("retire_floor");
expect(r.stderr).toContain("heal_enrich");
});
test("refuses a value that is not a boolean token", async () => {
const r = await runCli(["brain", "dream", "--gate", "heal_enrich=maybe", "--vault", vault]);
expect(r.returncode).toBe(2);
expect(r.stderr).toContain("maybe");
expect(r.stderr).toContain("true");
expect(r.stderr).toContain("false");
});
test("refuses an entry with no value at all", async () => {
const r = await runCli(["brain", "dream", "--gate", "heal_enrich", "--vault", vault]);
expect(r.returncode).toBe(2);
expect(r.stderr).toContain("heal_enrich");
});
test("refuses two contradictory overrides of the same gate", async () => {
const r = await runCli([
"brain",
"dream",
"--gate",
"heal_enrich=true",
"--gate",
"heal_enrich=false",
"--vault",
vault,
]);
expect(r.returncode).toBe(2);
expect(r.stderr).toContain("heal_enrich");
});
test("refuses --gate together with --step", async () => {
const r = await runCli([
"brain",
"dream",
"--step",
"heal-enrich",
"--gate",
"heal_enrich=true",
"--vault",
vault,
]);
expect(r.returncode).toBe(2);
expect(r.stderr).toContain("--gate");
});
});
describe("byte-identical when absent", () => {
test("a run with neither flag prints exactly what it printed before", async () => {
const r = await runCli([
"brain",
"dream",
"--dry-run",
"--now",
"2026-05-30T10:00:00Z",
"--vault",
vault,
]);
expect(r.returncode).toBe(0);
expect(r.stdout).toBe("run_id: dream-2026-05-30-100000\nchanged: false\n");
expect(r.stderr).toBe("");
});
test("the JSON run payload gains no step or gate key", async () => {
const r = await runCli([
"brain",
"dream",
"--dry-run",
"--now",
"2026-05-30T10:00:00Z",
"--vault",
vault,
"--json",
]);
const payload = JSON.parse(r.stdout);
expect(payload).not.toHaveProperty("step");
expect(payload).not.toHaveProperty("gates");
expect(payload).toHaveProperty("run_id");
});
});
describe("the salience gate on the human stream", () => {
test("a configured threshold is reported; --json is unchanged", async () => {
writePreference(vault, {
slug: "quiet",
topic: "quiet",
principle: "Nothing has ever applied this.",
created_at: "2026-01-01T00:00:00Z",
unconfirmed_until: "2026-01-08T00:00:00Z",
confirmed_at: "2026-01-08T00:00:00Z",
status: BRAIN_PREFERENCE_STATUS.confirmed,
evidenced_by: [],
last_evidence_at: "2026-05-29T00:00:00Z",
});
atomicWriteFileSync(
brainConfigPath(),
"schema_version: 1\ndream:\n salience_threshold: 0.2\n",
);
const human = await runCli([
"brain",
"dream",
"--dry-run",
"--now",
"2026-05-30T10:00:00Z",
"--vault",
vault,
]);
expect(human.returncode).toBe(0);
// Without this line an exclusion is invisible on this stream: the
// ladder simply folds fewer facts and never says why.
expect(human.stdout).toContain("salience_gate: 0 of 1 fact(s) admitted (threshold 0.2)");
const asJson = await runCli([
"brain",
"dream",
"--dry-run",
"--now",
"2026-05-30T10:00:00Z",
"--vault",
vault,
"--json",
]);
const payload = JSON.parse(asJson.stdout) as { salience_gate: { threshold: number } };
// The machine stream carried the gate all along and is untouched.
expect(payload.salience_gate.threshold).toBe(0.2);
});
});
describe("the manifest advertises both flags", () => {
test("help --json models --step and --gate on brain dream", async () => {
const r = await runCli(["help", "--json"]);
const parsed = JSON.parse(r.stdout);
const brain = parsed.commands.find((c: { name: string }) => c.name === "brain");
const dream = brain.commands.find((c: { name: string }) => c.name === "dream");
expect(dream.flags).toContainEqual({ name: "step", type: "string" });
expect(dream.flags).toContainEqual({ name: "gate", type: "string-array" });
});
test("completions advertise the new flags", async () => {
const r = await runCli(["completions", "bash"]);
expect(r.stdout).toContain("--step");
expect(r.stdout).toContain("--gate");
});
});
describe("MCP brain_dream carries the same two capabilities", () => {
test("step=scan returns the partial scan result", async () => {
seedPromotion();
const server = await makeServer();
const r = await callDream(server, { step: "scan" });
expect(r.errorCode).toBeUndefined();
expect(r.structured!["step"]).toBe("scan");
expect(r.structured!["partial"]).toBe(true);
expect(r.structured!["active_signals"]).toBe(3);
});
test("step=heal-enrich runs the enrichment with the config gate off", async () => {
const refPath = makeLinkableNotes();
const server = await makeServer();
const r = await callDream(server, { step: "heal-enrich" });
expect(r.errorCode).toBeUndefined();
expect(r.structured!["enriched"]).toBe(1);
expect(readFileSync(refPath, "utf8")).toContain("[[Widget Registry]]");
});
test("a non-runnable step is INVALID_PARAMS carrying the specific reason", async () => {
const server = await makeServer();
const r = await callDream(server, { step: DREAM_PHASE.heal });
expect(r.errorCode).toBe(-32602);
expect(r.errorMessage).toContain("planAutoRetires deletes from refresh.updated");
expect(r.errorMessage).toContain("Independently runnable steps: scan, heal-enrich");
});
test("gates override the vault config for one run and write nothing back", async () => {
seedPromotion();
const refPath = makeLinkableNotes();
const before = readFileSync(brainConfigPath(), "utf8");
const server = await makeServer();
const r = await callDream(server, {
gates: { heal_enrich: true },
now: "2026-05-30T10:00:00Z",
});
expect(r.errorCode).toBeUndefined();
expect(r.structured!["changed"]).toBe(true);
expect(readFileSync(refPath, "utf8")).toContain("[[Widget Registry]]");
expect(readFileSync(brainConfigPath(), "utf8")).toBe(before);
});
test("an unknown gate is INVALID_PARAMS naming the known gates", async () => {
const server = await makeServer();
const r = await callDream(server, { gates: { retire_floor: true } });
expect(r.errorCode).toBe(-32602);
expect(r.errorMessage).toContain("retire_floor");
expect(r.errorMessage).toContain("heal_enrich");
});
test("a non-boolean gate value is INVALID_PARAMS", async () => {
const server = await makeServer();
const r = await callDream(server, { gates: { heal_enrich: "yes" } });
expect(r.errorCode).toBe(-32602);
});
test("the tool advertises both arguments", async () => {
const server = await makeServer();
const listed = (await server.handleRequest({
jsonrpc: JSONRPC_VERSION,
id: 900,
method: "tools/list",
})) as { result: { tools: Array<{ name: string; inputSchema: { properties: object } }> } };
const tool = listed.result.tools.find((t) => t.name === "brain_dream")!;
expect(Object.keys(tool.inputSchema.properties)).toContain("step");
expect(Object.keys(tool.inputSchema.properties)).toContain("gates");
});
});
describe("a step that runs out of budget says so on the JSON stream", () => {
/**
* `--step` is driven IN PROCESS here rather than through `runCli`,
* because a deadline cannot be forced from outside: the config ladder
* accepts only non-negative whole seconds and reads `0` as "disabled",
* so no value a subprocess could be given makes a scan trip. A clock
* whose every reading is a day past the previous one does it instead -
* `createSafeguard` reads `Date.now`, which is exactly the path the
* verb takes - and it is the same technique `long-running-tools.test.ts`
* uses on the MCP side of the same contract.
*/
async function stepJson(step: string): Promise<Record<string, unknown>> {
const written: string[] = [];
const realWrite = process.stdout.write.bind(process.stdout);
process.stdout.write = ((chunk: unknown) => {
written.push(String(chunk));
return true;
}) as typeof process.stdout.write;
let tick = 0;
const clock = spyOn(Date, "now").mockImplementation(() => {
tick += 1;
return tick * 86_400_000;
});
process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
try {
const code = await cmdBrainDream(["--step", step, "--vault", vault, "--json"]);
expect(code).toBe(1);
} finally {
clock.mockRestore();
process.stdout.write = realWrite;
delete process.env["OPEN_SECOND_BRAIN_CONFIG"];
}
return JSON.parse(written.join("")) as Record<string, unknown>;
}
test("the scan step marks a tripped deadline as timed_out", async () => {
seedPromotion();
const payload = await stepJson("scan");
expect(payload["ok"]).toBe(false);
expect(payload["step"]).toBe("scan");
// The contract `docs/cli-reference.md` states for every long-running
// operation: a machine caller must be able to tell a budget it can
// raise from a defect it cannot. Both other dream catches emit it.
expect(payload["timed_out"]).toBe(true);
expect(String(payload["message"])).toContain("safeguard timeout");
});
test("the heal-enrich step marks it the same way", async () => {
makeLinkableNotes();
const payload = await stepJson("heal-enrich");
expect(payload["ok"]).toBe(false);
expect(payload["step"]).toBe("heal-enrich");
expect(payload["timed_out"]).toBe(true);
});
test("a refusal is not a timeout: no marker on a step that cannot run", async () => {
const r = await runCli(["brain", "dream", "--step", "log", "--vault", vault, "--json"]);
expect(r.returncode).toBe(2);
expect(JSON.parse(r.stdout)["timed_out"]).toBeUndefined();
});
});