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
/**
* `brain_dream` (task 3.19): the dream pass and its dry-run preview,
* with the gate overrides, the reach-scoped rows and the change list the
* answer renders. Runs at local reach only. Split from
* `feedback-tools.ts`; registration happens through that module's
* registry, which preserves the public FEEDBACK_TOOLS surface.
*/
import { resolveAgentName, resolveNearDuplicateRetireSiblingsEnabled } from "../../core/config.ts";
import { dream, type DreamGateOverrides } from "../../core/brain/dream.ts";
import {
decideBudgetWithin,
prepareTopicVerdicts,
type PrepareTopicVerdictsOptions,
} from "../../core/topics/decide-auto.ts";
import type { ProgressSink } from "../../core/brain/progress.ts";
import {
DREAM_GATE_NAMES,
DreamGateOverrideError,
validateDreamGateOverrides,
} from "../../core/brain/dream-gates.ts";
import { DreamStepNotRunnableError, runDreamStep } from "../../core/brain/dream-step.ts";
import {
applyDreamBundle,
discardDreamBundle,
DreamRetriageError,
listDreamBundles,
retriageDreamBundle,
stageDream,
validateDreamBundle,
type DreamRetriageEntry,
} from "../../core/brain/dream-stage.ts";
import { gatedOwnerScopeView, type OwnerScopeView } from "../../core/brain/owner-scope-view.ts";
import { brainArtifactSlug } from "../../core/brain/wikilink.ts";
import { normalizeAgentArgument } from "../../core/agent-identity.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import { contextVault, type ServerContext } from "../tool-contract.ts";
import { coerceStr, coerceBool, coerceIsoDate, unknownOperationError } from "../coerce.ts";
import { enforceCountGuard, readCountGuardArgs, toolSafeguard } from "./shared.ts";
import { toolPath } from "./device-path.ts";
import { OPERATION } from "../../core/brain/safeguard.ts";
import { readableAtContextReach, readableAtContextReachOrUndefined } from "./reach-readable.ts";
// ----- brain_dream ---------------------------------------------------------
/** The set of preference ids a dream summary would create/confirm/retire/move. */
export function dreamChangeList(summary: {
readonly new_unconfirmed: ReadonlyArray<string>;
readonly confirmed: ReadonlyArray<string>;
readonly retired: ReadonlyArray<{ readonly id: string }>;
readonly moved_to_processed: ReadonlyArray<string>;
}): string[] {
return [
...summary.new_unconfirmed,
...summary.confirmed,
...summary.retired.map((r) => r.id),
...summary.moved_to_processed,
];
}
/**
* Read the optional `gates` argument (no-dead-ends, Unit E - operator
* surface). JSON-RPC carries real objects and booleans, so the MCP form
* is the override record itself rather than the CLI's `name=value`
* strings; both go through the same validator in `dream-gates.ts`, so
* the accepted gate names cannot diverge between the two surfaces.
*/
export function readDreamGates(args: Record<string, unknown>): DreamGateOverrides | undefined {
const raw = args["gates"];
if (raw === undefined || raw === null) return undefined;
if (typeof raw !== "object" || Array.isArray(raw)) {
throw new MCPError(
INVALID_PARAMS,
`brain_dream: gates must be an object of <gate>: <boolean>; known gates: ${DREAM_GATE_NAMES.join(", ")}`,
);
}
try {
return validateDreamGateOverrides(raw as Record<string, unknown>);
} catch (exc) {
if (exc instanceof DreamGateOverrideError) {
throw new MCPError(INVALID_PARAMS, `brain_dream: ${exc.message}`);
}
throw exc;
}
}
/**
* The rows of a dream plan or run summary the caller may see
* (a-label-is-not-a-boundary, U3).
*
* Every list here names a preference or a signal by id, and the pass
* that produced them is vault-wide by construction: consolidation reads
* every topic, and clustering only half a vault would produce different
* preferences for every caller. So the PASS stays unscoped and the
* REPORT is filtered - a caller is told what it did to the artifacts
* that caller may see, and nothing about the rest.
*
* `contradictions`, `quarantined` and `intent_reviews` are absent from
* the fold on purpose: their subject is a TOPIC over inbox signals, and
* a signal carries no `owner:` anywhere in this product, so there is no
* ownership claim on disk to read.
*/
export function scopedDreamRows<R extends string>(
view: OwnerScopeView,
plan: {
readonly new_unconfirmed: ReadonlyArray<string>;
readonly confirmed: ReadonlyArray<string>;
readonly retired: ReadonlyArray<{ readonly id: string; readonly reason: R }>;
readonly moved_to_processed: ReadonlyArray<string>;
readonly suppressed: ReadonlyArray<string>;
},
): {
new_unconfirmed: ReadonlyArray<string>;
confirmed: ReadonlyArray<string>;
retired: ReadonlyArray<{ id: string; reason: R }>;
moved_to_processed: ReadonlyArray<string>;
suppressed: ReadonlyArray<string>;
} {
const ids = (list: ReadonlyArray<string>): ReadonlyArray<string> => view.keep(list, (id) => [id]);
return {
new_unconfirmed: ids(plan.new_unconfirmed),
confirmed: ids(plan.confirmed),
// A retire names the preference by BOTH spellings across the move:
// `ret-<slug>` after the pass, `pref-<slug>` before it.
retired: view
.keep(plan.retired, (r) => [r.id, `pref-${brainArtifactSlug(r.id)}`])
.map((r) => ({ id: r.id, reason: r.reason })),
moved_to_processed: ids(plan.moved_to_processed),
suppressed: ids(plan.suppressed),
};
}
/** The one answer a caller below local reach gets for anything but a dry run. */
export const DREAM_LOCAL_REACH_ONLY =
"brain_dream: below local reach only action=run with dry_run is served; a real pass, a step and the staged lifecycle run at local reach only";
export async function toolBrainDream(
ctx: ServerContext,
args: Record<string, unknown>,
onProgress?: ProgressSink,
): Promise<Record<string, unknown>> {
// `null` on a server with no vault: the inline pass runs over the store
// alone (D14); a step and the staged lifecycle read `ctx.vault`, which
// refuses with `vault_required` there.
const vault = contextVault(ctx);
const action = args["action"] ?? "run";
if (
action !== "run" &&
action !== "stage" &&
action !== "validate" &&
action !== "apply" &&
action !== "retriage" &&
action !== "discard" &&
action !== "list"
) {
throw unknownOperationError(
"brain_dream: action must be run|stage|validate|apply|retriage|discard|list",
);
}
const dryRun = coerceBool(args, "dry_run");
const nowDate = coerceIsoDate(args, "now");
const agentArg = coerceStr(args, "agent", false);
const agent = normalizeAgentArgument(agentArg) ?? resolveAgentName(ctx.configPath ?? undefined);
const gates = readDreamGates(args);
const stepArg = coerceStr(args, "step", false);
// One view for the whole call: every branch below reports preference
// and signal ids, and the staged lifecycle reports them twice.
const dreamView = gatedOwnerScopeView(vault, ctx.agentName);
// The rollup step's link candidates leave out a page the caller may not
// read at its reach, exactly as an absent page.
const readable = readableAtContextReach(ctx);
// Below local reach only a dry run is served, planned over the records
// the caller may read as if the others were absent. A real pass, a
// single step and the staged lifecycle move, rewrite or report records
// the caller may not read, so they are refused with one fixed answer
// before anything is read or written, whatever the vault holds.
const previewReadable = readableAtContextReachOrUndefined(ctx);
if (previewReadable !== undefined && (action !== "run" || !dryRun || stepArg)) {
throw new MCPError(INVALID_PARAMS, DREAM_LOCAL_REACH_ONLY);
}
const previewScope = previewReadable !== undefined ? { previewReadable } : {};
// Single-step requests (no-dead-ends, Unit E - operator surface).
// Deliberately checked before any environment work: a step the pass
// cannot honour is refused by name, carrying the specific reason and
// the runnable set, and nothing is read or written on that path.
if (stepArg) {
if (action !== "run") {
throw new MCPError(
INVALID_PARAMS,
`brain_dream: step applies to action=run; action=${action} drives the staged lifecycle, which has no single step`,
);
}
const conflicting = dryRun
? "dry_run"
: gates !== undefined
? "gates"
: "expect" in args || "strict" in args
? "expect/strict"
: null;
if (conflicting !== null) {
throw new MCPError(
INVALID_PARAMS,
`brain_dream: step cannot be combined with ${conflicting} - a single step has no preview path, reads no gate, and produces none of the preference counters the guard asserts over`,
);
}
try {
// Bounded and observed on the same terms as every sibling branch.
// This one had neither: it was the row `docs/mcp.md` marked
// **none**, and `dream()` being synchronous is exactly why that
// mattered - an unbounded step holds the server's event loop for
// its whole duration and the client cannot even time out and
// reissue. The budget is `dream`'s, because a step IS part of a
// dream pass; the sink is the caller's, dropped here until now.
return {
...runDreamStep(ctx.vault, stepArg, {
safeguard: toolSafeguard(ctx, OPERATION.dream),
...(onProgress ? { onProgress } : {}),
}),
};
} catch (exc) {
if (exc instanceof DreamStepNotRunnableError) {
throw new MCPError(INVALID_PARAMS, exc.message);
}
throw exc;
}
}
if (action !== "run") {
if (gates !== undefined) {
throw new MCPError(
INVALID_PARAMS,
`brain_dream: gates apply to action=run; action=${action} drives the staged lifecycle, whose bundle records the gates its own run resolved`,
);
}
// Staged lifecycle (t_ae8a8ec0): stage -> validate -> apply over a
// persisted bundle; dream() stays the only promotion engine.
const runIdArg = coerceStr(args, "run_id", false);
if (action !== "list" && action !== "stage" && !runIdArg) {
throw new MCPError(INVALID_PARAMS, `brain_dream action=${action}: run_id is required`);
}
const now = nowDate ?? new Date();
// The staged lifecycle runs the same consolidation pass `action=run`
// does - `stage` previews it, `apply` promotes from it - so it is
// bounded and reported on the same terms. Without the sink a client
// that sent a progressToken for `action: "stage"` would be told
// nothing and see nothing for the whole pass.
const stageOpts = {
now,
safeguard: toolSafeguard(ctx, OPERATION.dream),
readable,
...(agent ? { agentName: agent } : {}),
...(onProgress ? { onProgress } : {}),
};
switch (action) {
case "stage": {
const bundle = stageDream(ctx.vault, stageOpts);
return {
action,
run_id: bundle.runId,
plan: { ...bundle.plan, ...scopedDreamRows(dreamView, bundle.plan) },
sources: bundle.sources.length,
dir: `Brain/dream/staged/${bundle.runId}`,
};
}
case "validate": {
const verdict = validateDreamBundle(ctx.vault, runIdArg!, stageOpts);
return { action, run_id: runIdArg, valid: verdict.valid, drift: [...verdict.drift] };
}
case "apply": {
const outcome = applyDreamBundle(ctx.vault, runIdArg!, stageOpts);
return {
action,
run_id: runIdArg,
applied: outcome.applied,
drift: [...outcome.validation.drift],
...(outcome.summary !== undefined
? { changed: outcome.summary.changed, ...scopedDreamRows(dreamView, outcome.summary) }
: {}),
};
}
case "retriage": {
// Read-only: it re-runs the salience gate against the current
// threshold and reports what would move. The bundle is not
// rewritten, so a caller that likes the new partition re-stages.
let outcome;
try {
outcome = retriageDreamBundle(ctx.vault, runIdArg!, stageOpts);
} catch (exc) {
if (exc instanceof DreamRetriageError) {
throw new MCPError(INVALID_PARAMS, `brain_dream: ${exc.message}`);
}
throw exc;
}
const scopedDelta = (
entries: ReadonlyArray<DreamRetriageEntry>,
): Array<Record<string, unknown>> =>
dreamView
.keep(entries, (entry) => [entry.pref_id, entry.path])
.map((entry) => ({
pref_id: entry.pref_id,
path: entry.path,
score: entry.score,
staged_score: entry.staged_score,
}));
return {
action,
run_id: runIdArg,
staged_threshold: outcome.stagedThreshold,
current_threshold: outcome.currentThreshold,
changed: outcome.changed,
considered: outcome.considered,
admitted: outcome.admitted,
// Counts before the owner filter, names after it: a scoped
// caller is still told HOW MANY facts moved, and only the
// identities it may not see are withheld.
newly_admitted_count: outcome.newlyAdmitted.length,
newly_excluded_count: outcome.newlyExcluded.length,
newly_admitted: scopedDelta(outcome.newlyAdmitted),
newly_excluded: scopedDelta(outcome.newlyExcluded),
notes: [...outcome.notes],
};
}
case "discard": {
return { action, run_id: runIdArg, removed: discardDreamBundle(ctx.vault, runIdArg!) };
}
default: {
return {
action,
bundles: listDreamBundles(ctx.vault).map((b) => ({
run_id: b.runId,
status: b.status,
staged_at: b.stagedAt,
proposals: b.proposals,
sources: b.sources,
})),
};
}
}
}
const { expect, strict } = readCountGuardArgs(args);
// One deadline for the whole tool call, not one per pass. `dream()` is
// synchronous, so an unbounded call blocks the server's event loop for
// its entire duration and the client cannot even time out and reissue;
// what has to be bounded is therefore the call, and a guarded run is
// two passes over the same tree. Sharing the guard means a slow preview
// spends the run's budget - which is the honest reading of a budget the
// operator set for this operation.
const safeguard = toolSafeguard(ctx, OPERATION.dream);
const startedAt = Date.now();
// The retire-siblings key honours the server's own config file, as
// `brain_review_candidates` does.
const retireSiblingsEnabled = resolveNearDuplicateRetireSiblingsEnabled(
ctx.configPath ?? undefined,
);
// Only pay for a preview pass when a guard is actually requested; otherwise
// the run is byte-identical to before.
if (expect !== null || strict) {
const preview = dream(vault, {
dryRun: true,
safeguard,
readable,
retireSiblingsEnabled,
...previewScope,
...(nowDate ? { now: nowDate } : {}),
...(agent ? { agentName: agent } : {}),
// Preview the run being guarded, overrides and all.
...(gates !== undefined ? { gates } : {}),
});
const previewList = dreamChangeList(preview);
enforceCountGuard({
matched: previewList.length,
expect,
strict,
willMutate: !dryRun,
matchList: previewList,
});
}
// The count-guard preview above is deliberately NOT reported on: it is
// a dry run whose only purpose is to decide whether the run below may
// happen at all, and a client that saw the same five stages twice
// would read the second pass as a restart. Progress describes the run
// the caller asked for.
// The model verdicts are decided before the pass (design D10, D20):
// only a live pass decides; a dry run gets the deterministic result.
// The same config and run date the pass below plans with.
// The pass spends the call's one deadline too: it gets what is left,
// so the dream pass after it is not already out of time.
const deadlineMs = decideBudgetWithin(safeguard.timeoutMs, Date.now() - startedAt);
const decideOptions: PrepareTopicVerdictsOptions = {
...(ctx.configPath ? { configPath: ctx.configPath } : {}),
...(nowDate ? { runAt: nowDate } : {}),
...(deadlineMs !== undefined ? { deadlineMs } : {}),
};
const topicVerdicts =
dryRun || deadlineMs === 0 ? undefined : await prepareTopicVerdicts(decideOptions);
const summary = dream(vault, {
dryRun,
safeguard,
readable,
retireSiblingsEnabled,
...previewScope,
...(nowDate ? { now: nowDate } : {}),
...(topicVerdicts !== undefined ? { topicVerdicts } : {}),
...(agent ? { agentName: agent } : {}),
...(gates !== undefined ? { gates } : {}),
...(onProgress ? { onProgress } : {}),
...(ctx.configPath ? { configPath: ctx.configPath } : {}),
});
const changeList = dreamChangeList(summary);
// A retire-sibling pair names two preferences; it is kept only when the
// caller may see both, each in both spellings (`ret-<slug>` after the
// pass, `pref-<slug>` before it).
const bothSpellings = (id: string): ReadonlyArray<string> => {
const slug = brainArtifactSlug(id);
return [`pref-${slug}`, `ret-${slug}`];
};
const retireSiblings = dreamView.keep(summary.retire_siblings ?? [], (p) => [
...bothSpellings(p.retiring_id),
...bothSpellings(p.sibling_id),
]);
// The summary is already a Plain Old Frozen Object — JSON-serialise
// verbatim. We surface `snapshot_path` / `log_path` as vault-relative
// for caller convenience while preserving the absolute path as well.
return {
run_id: summary.run_id,
changed: summary.changed,
// Honest matched-vs-changed: `matched` is what the pass would touch;
// `changed_count` is what it actually wrote (0 on a dry run).
matched: changeList.length,
changed_count: dryRun ? 0 : changeList.length,
dry_run: dryRun,
...scopedDreamRows(dreamView, summary),
...(retireSiblings.length > 0
? {
retire_siblings: retireSiblings.map((p) => ({
retiring_id: p.retiring_id,
sibling_id: p.sibling_id,
score: p.score,
method: p.method,
})),
}
: {}),
// Inbox archive (issue #195): a count, not the ids. A first pass over a
// long-lived vault archives thousands of signals; the run's log event
// names every one of them.
archived_signals_count: summary.archived_signals?.length ?? 0,
contradictions: [...summary.contradictions],
warnings: summary.warnings.map((w) => ({
code: w.code,
message: w.message,
})),
uncertain: summary.uncertain.map((u) => ({
code: u.code,
...(u.topic !== undefined ? { topic: u.topic } : {}),
message: u.message,
})),
quarantined: summary.quarantined.map((q) => ({
topic: q.topic,
signal_count: q.signal_count,
distinct_agents: q.distinct_agents,
age_days: q.age_days,
failed_gates: [...q.failed_gates],
})),
// The salience gate over the rollup fold set. `threshold: null` says
// the gate was absent, and the two counts are reported before the
// owner filter so a scoped caller still learns how many facts were
// held back even where it may not see their names.
salience_gate: {
threshold: summary.salience_gate.threshold,
considered: summary.salience_gate.considered,
admitted: summary.salience_gate.admitted,
excluded_count: summary.salience_gate.excluded.length,
excluded: dreamView
.keep(summary.salience_gate.excluded, (entry) => [entry.pref_id, entry.path])
.map((entry) => ({
pref_id: entry.pref_id,
path: entry.path,
score: entry.score,
mass: entry.mass,
confidence: entry.confidence,
reuse: entry.reuse,
})),
},
snapshot_path: summary.snapshot_path ? toolPath(ctx, summary.snapshot_path) : null,
log_path: summary.log_path ? toolPath(ctx, summary.log_path) : null,
};
}