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 [run] [--dry-run] [--step S] [--gate N=V] | stage |
* validate <run-id> | apply <run-id> | retriage <run-id> | discard
* <run-id> | list` - the learning pass plus the staged lifecycle
* (t_ae8a8ec0). `run` (the default, kept positional-free for back-compat)
* promotes inline; `stage` persists a reviewable proposal bundle;
* `validate` proves the vault has not drifted; `apply` re-validates and
* runs the same engine live; `retriage` re-runs the salience gate against
* the current threshold and reports what would move; `discard` drops the
* bundle.
*
* `--step` and `--gate` (no-dead-ends, Unit E - operator surface) are
* the shell reach for the two capabilities that previously existed only
* as TypeScript arguments: `runDreamStep` and `DreamOptions.gates`.
* Both belong to the default `run` action and both refuse by name -
* `--step` through `DreamStepNotRunnableError`, which carries the
* specific reason and the runnable set, and `--gate` through
* `DreamGateOverrideError`. Neither writes anything back to
* `Brain/_brain.yaml`; with both absent the verb is byte-identical.
*
* Exit codes: 0 on success, 1 on operational failure (including a
* failed validation - scripts gate on it), 2 on usage errors, which is
* where a refused step or gate lands: the request was understood and
* declined, not attempted and broken.
*/
import { resolveAgentName } from "../../../core/config.ts";
import { dream, type DreamGateOverrides } from "../../../core/brain/dream.ts";
import { CountGuardError, assertExpectedCount } from "../../../core/brain/count-guard.ts";
import {
DREAM_GATE_NAMES,
DreamGateOverrideError,
parseDreamGateOverrides,
} from "../../../core/brain/dream-gates.ts";
import {
DREAM_STEP_RUNNABLE,
DreamStepNotRunnableError,
runDreamStep,
type DreamStepResult,
} from "../../../core/brain/dream-step.ts";
import {
applyDreamBundle,
discardDreamBundle,
DreamRetriageError,
listDreamBundles,
retriageDreamBundle,
stageDream,
validateDreamBundle,
type DreamRetriageEntry,
} from "../../../core/brain/dream-stage.ts";
import {
createSafeguard,
OPERATION,
resolveSafeguardTimeoutMs,
SafeguardTimeoutError,
} from "../../../core/brain/safeguard.ts";
import {
prepareTopicVerdicts,
type PrepareTopicVerdictsOptions,
} from "../../../core/topics/decide-auto.ts";
import { nextCommandField } from "../../../core/brain/next-step.ts";
import { emitNextStep } from "../../advisory-rail.ts";
import { attachProgress, reportProgressRefusal } from "../../progress-rail.ts";
import {
brainVerbContext,
describeErrorChain,
fail,
ok,
okJson,
parse,
parseOptionalIsoDate,
requireBrainVaultFor,
} from "../helpers.ts";
// The runnable set is read from the step registry, never retyped: a
// usage line that advertises a step the pass refuses is its own dead end.
const USAGE =
`usage: o2b brain dream [run] [--dry-run] [--step <${DREAM_STEP_RUNNABLE.join("|")}>] ` +
`[--gate <${DREAM_GATE_NAMES.join("|")}>=<true|false>] | ` +
"stage | validate <run-id> | apply <run-id> | retriage <run-id> | discard <run-id> | list " +
"[--now ISO] [--agent A] [--vault <path>] [--json]";
const ACTIONS = new Set(["run", "stage", "validate", "apply", "retriage", "discard", "list"]);
/** Staged actions that name one bundle. */
const RUN_ID_ACTIONS = new Set(["validate", "apply", "retriage", "discard"]);
/**
* Refuse a request this verb understood and declined. Exit 2, with the
* reason on stderr for a human and as a payload for a machine - never a
* stray line on a stream a caller parses.
*/
function refuse(message: string, asJson: boolean, payload: Record<string, unknown> = {}): number {
if (asJson) {
okJson({ ok: false, ...payload, message });
return 2;
}
process.stderr.write(`error: ${message}\n`);
return 2;
}
/** `--json` row for one fact the gate would move. */
function retriageRow(entry: DreamRetriageEntry): Record<string, unknown> {
return {
pref_id: entry.pref_id,
path: entry.path,
score: entry.score,
staged_score: entry.staged_score,
};
}
/** An absent threshold reads as a word, never as a number the operator did not set. */
function describeThreshold(threshold: number | null): string {
return threshold === null ? "absent" : String(threshold);
}
/** Print one side of a retriage delta, naming every fact in it. */
function printRetriageDelta(label: string, entries: ReadonlyArray<DreamRetriageEntry>): void {
ok(`${label}: ${entries.length}`);
for (const entry of entries) {
const staged = entry.staged_score === null ? "not scored" : String(entry.staged_score);
ok(` ${entry.pref_id} ${entry.score} (staged ${staged})`);
}
}
/** Render one partial step result as the verb's human line format. */
function printStepResult(result: DreamStepResult): void {
ok(`step: ${result.step}`);
if (result.step === "scan") {
ok(`active_signals: ${result.active_signals}`);
ok(`processed_signals: ${result.processed_signals}`);
ok(`preferences: ${result.preferences}`);
ok(`retired: ${result.retired}`);
if (result.corrupted.length > 0) ok(`corrupted: ${result.corrupted.join(", ")}`);
return;
}
ok(`scanned: ${result.scanned}`);
ok(`enriched: ${result.enriched}`);
if (result.pages.length > 0) ok(`pages: ${result.pages.join(", ")}`);
}
export async function cmdBrainDream(argv: string[]): Promise<number> {
const { flags, positional } = parse(argv, {
vault: { type: "string" },
"dry-run": { type: "boolean" },
now: { type: "string" },
agent: { type: "string" },
expect: { type: "string" },
strict: { type: "boolean" },
step: { type: "string" },
gate: { type: "string-array" },
progress: { type: "boolean" },
json: { type: "boolean" },
});
const asJson = flags["json"] === true;
const action = positional[0] ?? "run";
if (!ACTIONS.has(action)) {
process.stderr.write(`${USAGE}\n`);
return 2;
}
const needsRunId = RUN_ID_ACTIONS.has(action);
if (needsRunId ? positional.length !== 2 : positional.length > 1) {
process.stderr.write(`${USAGE}\n`);
return 2;
}
// --- Operator-surface argument checks (no-dead-ends, Unit E) --------
// Both live on the default `run` action and each is refused by name
// where it would otherwise be accepted and quietly ignored.
const stepRequest = flags["step"];
const gateEntries = (flags["gate"] as string[] | undefined) ?? [];
const wantsStep = typeof stepRequest === "string";
if ((wantsStep || gateEntries.length > 0) && action !== "run") {
return refuse(
`brain dream: --step and --gate steer the default 'run' action; ` +
`'${action}' drives the staged lifecycle, which has neither a single step nor a gate to override`,
asJson,
{ action },
);
}
if (wantsStep) {
// Every flag below configures work a single step does not do, so
// accepting one alongside --step would silently drop it.
const conflict =
gateEntries.length > 0
? {
flag: "--gate",
reason:
"a gate steers a full pass; the 'heal-enrich' step IS the opt-in and the 'scan' step reads no gate, so an override would have nothing to apply to",
}
: flags["dry-run"] === true
? {
flag: "--dry-run",
reason:
"runDreamStep has no preview path - 'scan' already writes nothing and 'heal-enrich' has no plan-only mode, so a dry run would be either a no-op dressed as a preview or a write",
}
: flags["expect"] !== undefined
? {
flag: "--expect",
reason:
"the count guard asserts over the preferences a full pass creates, confirms, retires or moves, and a single step produces none of those counters",
}
: flags["strict"] === true
? {
flag: "--strict",
reason:
"it demands a count guard over the preferences a full pass changes, and a single step changes none of them",
}
: null;
if (conflict !== null) {
return refuse(
`brain dream: --step cannot be combined with ${conflict.flag}: ${conflict.reason}`,
asJson,
{ step: stepRequest, conflicting_flag: conflict.flag },
);
}
}
let gates: DreamGateOverrides | null = null;
if (gateEntries.length > 0) {
try {
gates = parseDreamGateOverrides(gateEntries);
} catch (exc) {
if (exc instanceof DreamGateOverrideError) {
return refuse(`brain dream: ${exc.message}`, asJson, {
entry: exc.entry,
known_gates: [...exc.known],
});
}
throw exc;
}
}
// With no vault configured (`null`) the inline pass runs over the
// store's folds alone (design D14). A single step and the staged
// lifecycle work on vault files (user notes, the staging lane), so they
// still need a vault and say so.
const verbContext = brainVerbContext(flags, { vault: "optional" });
const { config, vault } = verbContext;
const vaultFor = (what: string): string => requireBrainVaultFor(verbContext, what);
const agentFlag = flags["agent"];
let agent: string;
if (typeof agentFlag === "string") {
const trimmed = agentFlag.trim();
if (trimmed.length === 0) {
return fail("brain dream: --agent must be a non-empty string when provided");
}
agent = trimmed;
} else {
agent = resolveAgentName(config);
}
const { value: now, error: nowErr } = parseOptionalIsoDate(flags, "now");
if (nowErr) return fail(nowErr);
// No signal: `dreamRun` is synchronous end to end, so a signal handler
// cannot run while it does (see `interrupt.ts`). The deadline is the
// only cooperative stop a dream pass has; SIGINT is left with its
// default meaning so the keystroke still kills the process, and every
// artifact a pass writes goes through `atomicWriteFileSync`, so being
// killed leaves no half-written note.
const guard = () =>
createSafeguard({
operation: OPERATION.dream,
timeoutMs: resolveSafeguardTimeoutMs(OPERATION.dream, config ?? undefined),
});
if (wantsStep) {
// A step is a whole run on this surface, so it is guarded and
// watched like one: `scan` walks the Brain tree and `heal-enrich`
// reads and rewrites every user page, and neither had a deadline or
// a sink before. The step itself owns the counter - the two units
// report under their own stage names - so this attaches the rail and
// forwards, exactly as the maintenance lane does over its tasks.
const stepObservation =
flags["progress"] === true
? // The rail is told what was actually dispatched, not a label
// for it: `brain.ts` hands this verb the tail AFTER `dream`, and
// `["dream", "step"]` named a positional this verb has never had
// - `--step` is a flag. The two sibling call sites below pass
// the real action for the same reason.
attachProgress({ command: "brain", argv: ["dream", ...argv], jsonRequested: asJson })
: null;
reportProgressRefusal(stepObservation);
let result: DreamStepResult;
try {
result = runDreamStep(vaultFor("dream --step"), stepRequest, {
safeguard: guard(),
...(stepObservation?.sink !== undefined ? { onProgress: stepObservation.sink } : {}),
});
} catch (exc) {
if (exc instanceof DreamStepNotRunnableError) {
return refuse(exc.message, asJson, {
step: exc.requested,
runnable: [...exc.runnable],
reason: exc.reason,
});
}
const message = `dream step ${stepRequest} failed: ${(exc as Error).message ?? exc}`;
if (asJson) {
// The same marker the staged-action catch and the inline-pass
// catch emit, for the same reason and on the same contract
// (`docs/cli-reference.md`, "Long-running operations"): a machine
// caller has to be able to tell a budget it can raise or retry
// past from a defect it cannot. This branch is the one the step
// deadline was added for, so it was the one place a timeout came
// back indistinguishable from a crash.
okJson({
ok: false,
step: stepRequest,
...(exc instanceof SafeguardTimeoutError ? { timed_out: true } : {}),
message,
});
return 1;
}
return fail(message);
}
if (asJson) {
process.stdout.write(JSON.stringify(result, null, 2) + "\n");
return 0;
}
printStepResult(result);
return 0;
}
// The staged actions that RUN a pass watch the same five stages the
// inline run does. `DreamStageOptions` has declared `onProgress` and
// threaded it through all three of those entry points since U1; this is
// the caller that asks. A stream that reached only one of the two entry
// points would be the half-wired mechanism this release exists to
// remove.
//
// `discard` and `list` are excluded because they run no pass and have
// nothing to report, and `run` because it falls through this block to
// the inline pass below, which attaches its own. Attaching here for
// `run` too would build two observers for one pass and report a refusal
// twice.
const STAGED_PASSES = new Set(["stage", "validate", "apply"]);
const stagedObservation =
flags["progress"] === true && STAGED_PASSES.has(action)
? attachProgress({ command: "brain", argv: ["dream", action], jsonRequested: asJson })
: null;
reportProgressRefusal(stagedObservation);
const stagedProgress =
stagedObservation?.sink !== undefined ? { onProgress: stagedObservation.sink } : {};
try {
if (action === "stage") {
const bundle = stageDream(vaultFor(`dream ${action}`), {
now: now ?? new Date(),
safeguard: guard(),
...stagedProgress,
...(agent ? { agentName: agent } : {}),
});
if (asJson) {
okJson({
run_id: bundle.runId,
plan: bundle.plan,
sources: bundle.sources.length,
dir: `Brain/dream/staged/${bundle.runId}`,
});
} else {
ok(`staged: ${bundle.runId} -> Brain/dream/staged/${bundle.runId}/`);
ok(`planned changes: ${bundle.plan.changed ? "yes" : "none"}`);
}
return 0;
}
if (action === "validate" || action === "apply") {
const runId = positional[1]!;
const stageOpts = {
now: now ?? new Date(),
safeguard: guard(),
...stagedProgress,
...(agent ? { agentName: agent } : {}),
};
if (action === "validate") {
const verdict = validateDreamBundle(vaultFor(`dream ${action}`), runId, stageOpts);
if (asJson) okJson({ run_id: runId, valid: verdict.valid, drift: verdict.drift });
else if (verdict.valid) ok(`validate ${runId}: clean`);
else {
ok(`validate ${runId}: DRIFT`);
for (const line of verdict.drift) ok(` ${line}`);
}
return verdict.valid ? 0 : 1;
}
const outcome = applyDreamBundle(vaultFor(`dream ${action}`), runId, stageOpts);
if (asJson) {
okJson({
run_id: runId,
applied: outcome.applied,
drift: outcome.validation.drift,
...(outcome.summary !== undefined
? {
changed: outcome.summary.changed,
new_unconfirmed: outcome.summary.new_unconfirmed,
confirmed: outcome.summary.confirmed,
}
: {}),
});
} else if (outcome.applied) {
ok(`apply ${runId}: done (changed: ${outcome.summary!.changed})`);
} else {
ok(`apply ${runId}: ABORTED - bundle drifted, re-stage first`);
for (const line of outcome.validation.drift) ok(` ${line}`);
}
return outcome.applied ? 0 : 1;
}
if (action === "retriage") {
const runId = positional[1]!;
const outcome = retriageDreamBundle(vaultFor(`dream ${action}`), runId, {
now: now ?? new Date(),
safeguard: guard(),
...(agent ? { agentName: agent } : {}),
});
if (asJson) {
okJson({
run_id: outcome.runId,
staged_threshold: outcome.stagedThreshold,
current_threshold: outcome.currentThreshold,
changed: outcome.changed,
considered: outcome.considered,
admitted: outcome.admitted,
newly_admitted: outcome.newlyAdmitted.map(retriageRow),
newly_excluded: outcome.newlyExcluded.map(retriageRow),
notes: [...outcome.notes],
});
return 0;
}
ok(
`retriage ${runId}: threshold staged=${describeThreshold(outcome.stagedThreshold)} ` +
`current=${describeThreshold(outcome.currentThreshold)}`,
);
ok(`fold set: ${outcome.admitted} of ${outcome.considered} admitted now`);
printRetriageDelta("newly admitted", outcome.newlyAdmitted);
printRetriageDelta("newly excluded", outcome.newlyExcluded);
for (const note of outcome.notes) ok(`note: ${note}`);
if (outcome.changed) ok("re-stage the bundle to adopt this partition");
return 0;
}
if (action === "discard") {
const runId = positional[1]!;
const removed = discardDreamBundle(vaultFor(`dream ${action}`), runId);
if (asJson) okJson({ run_id: runId, removed });
else ok(removed ? `discarded ${runId}` : `no staged bundle named ${runId}`);
return 0;
}
if (action === "list") {
const bundles = listDreamBundles(vaultFor(`dream ${action}`));
if (asJson) {
okJson({
bundles: bundles.map((b) => ({
run_id: b.runId,
status: b.status,
staged_at: b.stagedAt,
proposals: b.proposals,
sources: b.sources,
})),
...(bundles.length === 0 ? nextCommandField("dream-bundles-absent") : {}),
});
} else if (bundles.length === 0) {
ok("no dream bundles");
// no-dead-ends, phase 3: this pointer was hand-written beside
// the rail. One mechanism, one line format.
emitNextStep("dream-bundles-absent", { command: "brain", argv, jsonRequested: asJson });
} else {
for (const b of bundles) {
ok(`${b.runId} ${b.status} staged ${b.stagedAt} ${b.proposals} proposal(s)`);
}
}
return 0;
}
} catch (exc) {
// A bundle this verb understood and declined is a refusal, not an
// operational failure: exit 2, with the bare reason beside the
// sentence so a machine caller can branch on it.
if (exc instanceof DreamRetriageError) {
return refuse(exc.message, asJson, { action, run_id: exc.runId, reason: exc.reason });
}
const timedOut = exc instanceof SafeguardTimeoutError;
if (asJson) {
okJson({
ok: false,
message: `dream ${action} failed: ${(exc as Error).message ?? exc}`,
...(timedOut ? { timed_out: true } : {}),
});
return 1;
}
return fail(`dream ${action} failed: ${(exc as Error).message ?? exc}`);
}
// action === "run": the legacy inline pass.
const expectRaw = flags["expect"] as string | undefined;
let expect: number | null = null;
if (expectRaw !== undefined) {
const n = Number(expectRaw);
if (!Number.isInteger(n) || n < 0) return fail("--expect must be a non-negative integer");
expect = n;
}
const strict = flags["strict"] === true;
// Only pay for a preview pass when a guard is requested.
if (expect !== null || strict) {
try {
const preview = dream(vault, {
...(now !== null ? { now } : {}),
dryRun: true,
...(agent ? { agentName: agent } : {}),
// The guard must preview the run it is guarding, overrides and
// all, or it asserts a count for a pass that will not happen.
...(gates !== null ? { gates } : {}),
});
const matchList = [
...preview.new_unconfirmed,
...preview.confirmed,
...preview.retired.map((r) => r.id),
...preview.moved_to_processed,
];
assertExpectedCount({
matched: matchList.length,
expect,
strict,
willMutate: !flags["dry-run"],
matchList,
});
} catch (exc) {
if (exc instanceof CountGuardError) return fail(exc.message);
return fail(`dream preview failed: ${(exc as Error).message ?? exc}`);
}
}
// Progress is opt-in: attaching a sink by default would change the
// stderr of every existing invocation, and this CLI's one streaming
// precedent (`o2b search index --verbose`) is opt-in for the same
// reason. The rail decides whether the stream can carry it at all.
const observation =
flags["progress"] === true
? attachProgress({ command: "brain", argv: ["dream"], jsonRequested: asJson })
: null;
reportProgressRefusal(observation);
// The model verdicts are decided before the pass (design D10, D20):
// only a live pass decides; a dry run gets the deterministic result.
const dryRun = Boolean(flags["dry-run"]);
// The same config and run date the pass below plans with.
const decideOptions: PrepareTopicVerdictsOptions = {
...(config !== undefined ? { configPath: config } : {}),
...(now !== null ? { runAt: now } : {}),
};
const topicVerdicts = dryRun ? undefined : await prepareTopicVerdicts(decideOptions);
let summary;
try {
summary = dream(vault, {
...(now !== null ? { now } : {}),
dryRun,
...(topicVerdicts !== undefined ? { topicVerdicts } : {}),
...(agent ? { agentName: agent } : {}),
safeguard: guard(),
...(observation?.sink !== undefined ? { onProgress: observation.sink } : {}),
...(gates !== null ? { gates } : {}),
...(config !== undefined ? { configPath: config } : {}),
});
} catch (exc) {
if (exc instanceof SafeguardTimeoutError && asJson) {
okJson({ ok: false, timed_out: true, message: exc.message });
return 1;
}
return fail(`dream failed: ${describeErrorChain(exc)}`);
}
for (const w of summary.warnings ?? []) {
process.stderr.write(`warning: ${w.code}: ${w.message}\n`);
}
if (asJson) {
process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
return 0;
}
ok(`run_id: ${summary.run_id}`);
ok(`changed: ${summary.changed}`);
// Only when a threshold is configured: with the gate open every fact is
// admitted, and a line saying so on every run would be noise. With it
// closed the exclusions are otherwise invisible on this stream - the
// ladder just folds fewer facts and says nothing about why.
const gate = summary.salience_gate;
if (gate.threshold !== null) {
ok(
`salience_gate: ${gate.admitted} of ${gate.considered} fact(s) admitted ` +
`(threshold ${gate.threshold})`,
);
}
if (summary.new_unconfirmed.length > 0)
ok(`new_unconfirmed: ${summary.new_unconfirmed.join(", ")}`);
if (summary.confirmed.length > 0) ok(`confirmed: ${summary.confirmed.join(", ")}`);
if (summary.retired.length > 0)
ok(`retired: ${summary.retired.map((r) => `${r.id} (${r.reason})`).join(", ")}`);
if (summary.contradictions.length > 0) ok(`contradictions: ${summary.contradictions.join(", ")}`);
if (summary.moved_to_processed.length > 0)
ok(`moved_to_processed: ${summary.moved_to_processed.length}`);
const archived = summary.archived_signals?.length ?? 0;
if (archived > 0) ok(`archived_signals: ${archived}`);
if (summary.view !== undefined) ok(`view: ${summary.view.summary}`);
return 0;
}