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 decision <action>` - decision-record note family CLI
* (Belief lifecycle suite, Track B anchor, t_ac03214d; open-decision
* vault actions added by the write-side-trust wave, Task 10).
*
* Actions:
* - `record --title <t> --chosen <c> --assumption <a> --review-date <d>
* [--premortem <p>] [--notes <n>]`
* - `outcome <slug> --outcome <text>` backfill the hindsight outcome
* - `show <slug>`
* - `list`
* - `similar --title <t> [--chosen <c>]` historically similar decisions
* - `recall --prompt <t> [--turn <n>] [--count <n>] [--last-turn <n>]
* [--surfaced-ids <id> ...]` resurface a rated decision,
* threading the per-session cap and spacing state
* - `open --title <t> --question <q> --option <o> [--option <o>...]
* [--context <c>]` park a question with options
* - `list_open [--status <s>]` parked questions by status
* - `show_open <id>` one parked question
* - `resolve <id> --choice <c> [--rationale <r>]`
* choose an option; mints the real decision page
* - `discard <id> --reason <r>` close without deciding
*
* CLI mirror of the `brain_decision` MCP tool; both delegate to the core
* decision module so the on-disk shape cannot drift.
*/
import { defaultConfigPath } from "../../../core/config.ts";
import {
backfillOutcome,
compareDecisions,
findSimilarDecisions,
listDecisions,
listRatedDecisions,
recordDecision,
showDecision,
updateRating,
} from "../../../core/brain/decisions/record.ts";
import type { BrainCommitmentTier } from "../../../core/brain/types.ts";
import {
discardOpenDecision,
isOpenDecisionStatus,
listOpenDecisions,
OPEN_DECISION_STATUSES,
openDecision,
resolveOpenDecision,
showOpenDecision,
} from "../../../core/brain/decisions/open-store.ts";
import { queryDecisionChangeHistory } from "../../../core/brain/decisions/receipts.ts";
import { recallRatedDecisions } from "../../../core/brain/decisions/recall.ts";
import { normalizeFlagString, ok, okJson, parse, resolveBrainVault } from "../helpers.ts";
const USAGE_ERROR_EXIT = 2;
function usageError(message: string): number {
process.stderr.write(`error: ${message}\n`);
return USAGE_ERROR_EXIT;
}
export async function cmdBrainDecision(argv: string[]): Promise<number> {
const { flags, positional } = parse(argv, {
vault: { type: "string" },
config: { type: "string" },
agent: { type: "string" },
title: { type: "string" },
chosen: { type: "string" },
assumption: { type: "string" },
"review-date": { type: "string" },
premortem: { type: "string" },
notes: { type: "string" },
outcome: { type: "string" },
rating: { type: "string" },
rationale: { type: "string" },
commitment: { type: "string" },
rated: { type: "boolean" },
subject: { type: "string" },
cursor: { type: "string" },
limit: { type: "string" },
prompt: { type: "string" },
turn: { type: "string" },
count: { type: "string" },
"last-turn": { type: "string" },
"surfaced-ids": { type: "string-array" },
question: { type: "string" },
option: { type: "string-array" },
context: { type: "string" },
status: { type: "string" },
choice: { type: "string" },
reason: { type: "string" },
json: { type: "boolean" },
});
const action = positional[0];
if (action === undefined) {
return usageError(
"brain decision requires an action: record | outcome | rate | show | list | compare | similar | history | recall | open | list_open | show_open | resolve | discard",
);
}
const config = (flags["config"] as string | undefined) ?? defaultConfigPath();
const vault = resolveBrainVault(flags["vault"] as string | undefined, config);
const explicitAgent = normalizeFlagString(flags["agent"]);
const wantsJson = flags["json"] === true;
try {
switch (action) {
case "record": {
const title = normalizeFlagString(flags["title"]);
const chosen = normalizeFlagString(flags["chosen"]);
const assumption = normalizeFlagString(flags["assumption"]);
const reviewDate = normalizeFlagString(flags["review-date"]);
if (!title || !chosen || !assumption || !reviewDate) {
return usageError(
"brain decision record requires --title, --chosen, --assumption, --review-date",
);
}
const premortem = normalizeFlagString(flags["premortem"]);
const notes = normalizeFlagString(flags["notes"]);
const ratingRaw = normalizeFlagString(flags["rating"]);
const rating = ratingRaw === null ? undefined : Number(ratingRaw);
if (rating !== undefined && !Number.isFinite(rating)) {
return usageError("brain decision record --rating must be a number");
}
const rationale = normalizeFlagString(flags["rationale"]);
const commitment = normalizeFlagString(flags["commitment"]);
const res = recordDecision(vault, {
title,
chosen,
assumption,
reviewDate,
...(premortem ? { premortem } : {}),
...(notes ? { notes } : {}),
...(rating !== undefined ? { rating } : {}),
...(rationale ? { rationale } : {}),
...(commitment ? { commitment: commitment as BrainCommitmentTier } : {}),
agent: explicitAgent ?? "",
configPath: config,
});
if (wantsJson) {
okJson({
id: res.record.id,
slug: res.record.slug,
review_date: res.record.reviewDate,
review_obligation: res.reviewObligationSlug,
obligation_created: res.obligationCreated,
});
} else {
ok(`recorded ${res.record.id} (review obligation: ${res.reviewObligationSlug})`);
}
return 0;
}
case "outcome": {
const slug = positional[1];
const outcome = normalizeFlagString(flags["outcome"]);
if (slug === undefined || !outcome) {
return usageError("brain decision outcome requires <slug> --outcome <text>");
}
const res = backfillOutcome(vault, {
slug,
outcome,
...(explicitAgent ? { agent: explicitAgent } : {}),
configPath: config,
});
if (wantsJson) {
okJson({ id: res.id, slug: res.slug, outcome: res.outcome });
} else {
ok(`outcome recorded for ${res.id}`);
}
return 0;
}
case "rate": {
const slug = positional[1];
const ratingRaw = normalizeFlagString(flags["rating"]);
if (slug === undefined || ratingRaw === null) {
return usageError("brain decision rate requires <slug> --rating <n>");
}
const rating = Number(ratingRaw);
if (!Number.isFinite(rating)) {
return usageError("brain decision rate --rating must be a number");
}
const rationale = normalizeFlagString(flags["rationale"]);
const res = updateRating(vault, {
slug,
rating,
...(rationale ? { rationale } : {}),
...(explicitAgent ? { agent: explicitAgent } : {}),
configPath: config,
});
if (wantsJson) {
okJson({ id: res.id, slug: res.slug, rating: res.rating, rationale: res.rationale });
} else {
ok(`rated ${res.id}: ${res.rating}`);
}
return 0;
}
case "compare": {
const slugs = positional.slice(1);
if (slugs.length === 0) {
return usageError("brain decision compare requires one or more slugs");
}
const rows = compareDecisions(vault, slugs);
if (wantsJson) {
okJson({
decisions: rows.map((d) => ({
id: d.id,
slug: d.slug,
title: d.title,
chosen: d.chosen,
rating: d.rating,
rationale: d.rationale,
outcome: d.outcome,
})),
});
} else if (rows.length === 0) {
ok("no matching decisions");
} else {
for (const d of rows) {
ok(`${d.id}: ${d.chosen} (rating ${d.rating ?? "none"})`);
}
}
return 0;
}
case "show": {
const slug = positional[1];
if (slug === undefined) return usageError("brain decision show requires a slug");
const res = showDecision(vault, slug);
if (res === null) {
process.stderr.write(`error: no decision: ${slug}\n`);
return 1;
}
if (wantsJson) {
okJson({
id: res.id,
slug: res.slug,
title: res.title,
chosen: res.chosen,
assumption: res.assumption,
review_date: res.reviewDate,
outcome: res.outcome,
premortem: res.premortem,
rating: res.rating,
rationale: res.rationale,
// Commitment tier (B3): emitted only when set so an unset
// decision stays byte-identical to a pre-B3 response.
...(res.commitment !== null ? { commitment: res.commitment } : {}),
});
} else {
ok(`${res.id}: chose "${res.chosen}" (review ${res.reviewDate ?? "none"})`);
}
return 0;
}
case "list": {
const ratedOnly = flags["rated"] === true;
const all = ratedOnly ? listRatedDecisions(vault) : listDecisions(vault);
if (wantsJson) {
okJson({
decisions: all.map((d) => ({
id: d.id,
slug: d.slug,
title: d.title,
chosen: d.chosen,
rating: d.rating,
review_date: d.reviewDate,
outcome: d.outcome,
...(d.commitment !== null ? { commitment: d.commitment } : {}),
})),
});
} else if (all.length === 0) {
ok(ratedOnly ? "no rated decisions" : "no decisions");
} else {
for (const d of all) {
const rt = d.rating !== null ? ` [${d.rating}]` : "";
ok(`${d.id}${rt}: ${d.chosen}${d.outcome ? ` -> ${d.outcome}` : ""}`);
}
}
return 0;
}
case "similar": {
const title = normalizeFlagString(flags["title"]);
if (!title) return usageError("brain decision similar requires --title <text>");
const chosen = normalizeFlagString(flags["chosen"]);
const hits = findSimilarDecisions(vault, {
title,
...(chosen ? { chosen } : {}),
});
if (wantsJson) {
okJson({
similar: hits.map((h) => ({
id: h.id,
slug: h.slug,
title: h.title,
outcome: h.outcome,
jaccard: h.jaccard,
})),
});
} else if (hits.length === 0) {
ok("no similar decisions");
} else {
for (const h of hits) {
ok(`${h.id} (${h.jaccard.toFixed(2)})${h.outcome ? ` -> ${h.outcome}` : ""}`);
}
}
return 0;
}
case "history": {
const subject = normalizeFlagString(flags["subject"]);
const cursor = normalizeFlagString(flags["cursor"]);
const limitRaw = normalizeFlagString(flags["limit"]);
const limit = limitRaw === null ? undefined : Number(limitRaw);
if (limit !== undefined && (!Number.isInteger(limit) || limit <= 0)) {
return usageError("brain decision history --limit must be a positive integer");
}
const page = queryDecisionChangeHistory(vault, {
...(subject ? { subject } : {}),
...(cursor ? { cursor } : {}),
...(limit !== undefined ? { limit } : {}),
});
if (wantsJson) {
okJson({
total: page.total,
next_cursor: page.nextCursor,
receipts: page.receipts.map((r) => ({
ts: r.ts,
subject: r.subject,
before: r.before,
after: r.after,
confidence_delta: r.confidence_delta,
reason_code: r.reason_code,
actor: r.actor,
idempotency_key: r.idempotency_key,
})),
});
} else if (page.receipts.length === 0) {
ok("no decision-change receipts");
} else {
for (const r of page.receipts) {
ok(`${r.ts} ${r.subject}: ${r.before} -> ${r.after} (${r.reason_code})`);
}
if (page.nextCursor) ok(`-- more: --cursor ${page.nextCursor}`);
}
return 0;
}
case "recall": {
const prompt = normalizeFlagString(flags["prompt"]);
if (!prompt) return usageError("brain decision recall requires --prompt <text>");
const turnRaw = normalizeFlagString(flags["turn"]);
const turn = turnRaw === null ? 0 : Number(turnRaw);
if (!Number.isInteger(turn) || turn < 0) {
return usageError("brain decision recall --turn must be a non-negative integer");
}
// Governor state passthrough (B5): let the CLI exercise the same
// per-session cap and spacing the MCP recall action accepts.
const countRaw = normalizeFlagString(flags["count"]);
const count = countRaw === null ? 0 : Number(countRaw);
if (!Number.isInteger(count) || count < 0) {
return usageError("brain decision recall --count must be a non-negative integer");
}
const lastTurnRaw = normalizeFlagString(flags["last-turn"]);
let lastTurn: number | null = null;
if (lastTurnRaw !== null) {
lastTurn = Number(lastTurnRaw);
if (!Number.isInteger(lastTurn) || lastTurn < 0) {
return usageError("brain decision recall --last-turn must be a non-negative integer");
}
}
const surfacedIds = Array.isArray(flags["surfaced-ids"])
? (flags["surfaced-ids"] as string[])
: [];
const res = recallRatedDecisions(vault, {
prompt,
turn,
state: {
surfacedIds,
lastTurn,
count: count || surfacedIds.length,
},
configPath: config,
});
if (wantsJson) {
okJson({
enabled: res.enabled,
surfaced: res.surfaced
? { id: res.surfaced.id, slug: res.surfaced.slug, rating: res.surfaced.rating }
: null,
text: res.text,
state: {
surfaced_ids: res.state.surfacedIds,
last_turn: res.state.lastTurn,
count: res.state.count,
},
});
} else if (!res.enabled) {
ok("decision recall not configured");
} else if (res.surfaced === null) {
ok("no decision recalled");
} else {
ok(res.text);
}
return 0;
}
case "open": {
const title = normalizeFlagString(flags["title"]);
const question = normalizeFlagString(flags["question"]);
const options = Array.isArray(flags["option"]) ? (flags["option"] as string[]) : [];
if (!title || !question || options.length === 0) {
return usageError("brain decision open requires --title, --question, --option");
}
const context = normalizeFlagString(flags["context"]);
const rec = openDecision(vault, {
title,
question,
options,
...(context ? { context } : {}),
...(explicitAgent ? { agent: explicitAgent } : {}),
configPath: config,
});
if (wantsJson) {
okJson({ id: rec.id, slug: rec.slug, status: rec.status, options: options.length });
} else {
ok(`opened ${rec.id} (${options.length} options)`);
}
return 0;
}
case "list_open": {
const statusRaw = normalizeFlagString(flags["status"]);
if (statusRaw !== null && !isOpenDecisionStatus(statusRaw)) {
return usageError(
`brain decision list_open --status must be one of ${OPEN_DECISION_STATUSES.join(", ")}`,
);
}
const listed = listOpenDecisions(vault, statusRaw !== null ? { status: statusRaw } : {});
if (wantsJson) {
okJson({
open_decisions: listed.records.map((r) => ({
id: r.id,
slug: r.slug,
title: r.title,
question: r.question,
status: r.status,
options: [...r.options],
created_at: r.createdAt,
})),
unreadable: listed.unreadable,
});
} else if (listed.records.length === 0 && listed.unreadable.length === 0) {
ok("no open decisions");
} else {
for (const r of listed.records) {
ok(`${r.id} [${r.status}]: ${r.question} (${r.options.length} options)`);
}
for (const u of listed.unreadable) {
process.stdout.write(`unreadable: ${u.reason}\n`);
}
}
return 0;
}
case "show_open": {
const id = positional[1];
if (id === undefined) return usageError("brain decision show_open requires an id");
const res = showOpenDecision(vault, id);
if (res === null) {
process.stderr.write(`error: no open decision: ${id}\n`);
return 1;
}
if (wantsJson) {
okJson({
id: res.id,
slug: res.slug,
title: res.title,
question: res.question,
options: [...res.options],
context: res.context,
status: res.status,
created_at: res.createdAt,
resolved_at: res.resolvedAt,
discarded_at: res.discardedAt,
choice: res.choice,
decision: res.decision,
discard_reason: res.discardReason,
});
} else {
ok(`${res.id} [${res.status}]: ${res.question}`);
for (const option of res.options) ok(` - ${option}`);
if (res.choice !== null) ok(` choice: ${res.choice}`);
if (res.decision !== null) ok(` decision: ${res.decision}`);
if (res.discardReason !== null) ok(` reason: ${res.discardReason}`);
}
return 0;
}
case "resolve": {
const id = positional[1];
const choice = normalizeFlagString(flags["choice"]);
if (id === undefined || !choice) {
return usageError("brain decision resolve requires <id> --choice <option>");
}
const rationale = normalizeFlagString(flags["rationale"]);
const res = resolveOpenDecision(vault, id, {
choice,
...(rationale ? { rationale } : {}),
...(explicitAgent ? { actor: explicitAgent } : {}),
configPath: config,
});
if (wantsJson) {
okJson({ id, decision: res.decision });
} else {
ok(`resolved ${id} -> ${res.decision}`);
}
return 0;
}
case "discard": {
const id = positional[1];
const reason = normalizeFlagString(flags["reason"]);
if (id === undefined || !reason) {
return usageError("brain decision discard requires <id> --reason <text>");
}
discardOpenDecision(vault, id, {
reason,
...(explicitAgent ? { actor: explicitAgent } : {}),
configPath: config,
});
if (wantsJson) {
okJson({ id, status: "discarded" });
} else {
ok(`discarded ${id}`);
}
return 0;
}
default:
return usageError(`unknown decision action: ${action}`);
}
} catch (exc) {
process.stderr.write(`error: ${(exc as Error).message ?? String(exc)}\n`);
return 1;
}
}