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
import {
planUpgrade,
applyUpgrade,
BrainUpgradeError,
BrainUpgradeStoreOnlyError,
upgradeBlockedByStore,
type UpgradePlan,
} from "../../../core/brain/upgrade.ts";
import { basename } from "node:path";
import {
brainVerbContext,
describeErrorChain,
fail,
ok,
okJson,
parse,
printUpgradePlanText,
readSingleLine,
renderUpgradePlanJson,
} from "../helpers.ts";
import { info } from "../../output.ts";
import { runSelfHealUpgrade } from "../../../core/maintenance/self-heal-upgrade.ts";
import {
clearSelfHealUpgradeFailure,
describeSelfHealUpgradeFailure,
readSelfHealUpgradeFailure,
recordSelfHealUpgradeFailure,
type SelfHealUpgradeFailure,
} from "../../../core/maintenance/self-heal-upgrade-state.ts";
/** JSON shape of a recorded automatic-upgrade failure. */
function failureJson(failure: SelfHealUpgradeFailure): Record<string, unknown> {
return {
failed_at: failure.failedAt,
error: failure.error,
consecutive_failures: failure.consecutiveFailures,
pending: failure.pending,
retry_after: failure.retryAfter,
};
}
/** Print the plan, plus the last automatic-upgrade failure when one is recorded. */
function printPlan(plan: UpgradePlan, failure: SelfHealUpgradeFailure | null, json: boolean): void {
if (json) {
okJson({
...renderUpgradePlanJson(plan),
self_heal_failure: failure === null ? null : failureJson(failure),
});
return;
}
printUpgradePlanText(plan);
if (failure !== null) {
info(`last automatic upgrade: ${describeSelfHealUpgradeFailure(failure)}`);
}
}
export async function cmdBrainUpgrade(argv: string[]): Promise<number> {
const { flags } = parse(argv, {
vault: { type: "string" },
"dry-run": { type: "boolean" },
apply: { type: "boolean" },
yes: { type: "boolean" },
check: { type: "boolean" },
json: { type: "boolean" },
// The plan digest a --dry-run printed and an operator approved
// (t_18fda844) - the upgrade twin of import-claude-memory's
// --approval-digest. Verified against the freshly computed plan
// before anything is written.
"approval-digest": { type: "string" },
// The detached worker `ensureVaultCurrent` starts, with the lock claim
// it was handed. Not an operator flag: the worker's outcome is
// recorded, never printed (its streams are ignored).
"self-heal": { type: "string" },
});
const { vault } = brainVerbContext(flags);
const selfHealToken = flags["self-heal"] as string | undefined;
if (selfHealToken !== undefined) {
runSelfHealUpgrade(vault, { lockToken: selfHealToken });
return 0;
}
if (flags["dry-run"] && flags["apply"])
return fail("brain upgrade: --dry-run and --apply are mutually exclusive");
if (flags["check"] && flags["apply"])
return fail("brain upgrade: --check and --apply are mutually exclusive");
// A store-only machine has no managed files to upgrade: say so before
// planning or prompting, and record no failure for it. Asked to apply,
// that is a refusal (exit 1, `ok: false`); asked to look, it is the
// answer (exit 0, `ok: true`), so the exit code and `ok` always agree.
let blocked: boolean;
try {
blocked = upgradeBlockedByStore(vault);
} catch (exc) {
return fail(`upgrade check failed: ${(exc as Error).message ?? exc}`);
}
if (blocked) {
const message = new BrainUpgradeStoreOnlyError().message;
const refused = Boolean(flags["apply"]);
if (flags["json"]) {
okJson(
refused
? { ok: false, store_only: true, error: message }
: { ok: true, store_only: true, note: message },
);
} else process.stderr.write(`${message}\n`);
return refused ? 1 : 0;
}
let plan: UpgradePlan;
try {
plan = planUpgrade(vault);
} catch (exc) {
return fail(`upgrade plan failed: ${(exc as Error).message ?? exc}`);
}
const failure = readSelfHealUpgradeFailure(vault);
if (flags["check"]) {
printPlan(plan, failure, Boolean(flags["json"]));
return plan.pending > 0 || plan.errors > 0 ? 2 : 0;
}
if (!flags["apply"]) {
printPlan(plan, failure, Boolean(flags["json"]));
return 0;
}
if (plan.errors > 0)
return fail(
`upgrade aborted: ${plan.errors} file(s) failed to plan; run with --dry-run to inspect the error.`,
);
if (plan.pending === 0) {
// Nothing left for the automatic upgrade to retry either.
clearSelfHealUpgradeFailure(vault);
if (flags["json"]) {
okJson({ run_id: "", snapshot_path: "", files_updated: [] });
} else {
ok("upgrade: nothing to do; all managed files match the current release.");
}
return 0;
}
if (!flags["yes"]) {
if (flags["json"] || !process.stdin.isTTY)
return fail(
"brain upgrade --apply requires --yes in non-interactive mode (--json or non-TTY stdin)",
);
process.stderr.write(
`About to rewrite ${plan.pending} managed file(s):\n` +
plan.files
.filter((f) => f.status === "update")
.map((f) => ` - ${f.path}\n`)
.join("") +
`A pre-apply snapshot will be taken (rollback via run id).\nProceed? [y/N] `,
);
const ans = await readSingleLine();
if (ans.toLowerCase() !== "y" && ans.toLowerCase() !== "yes") {
ok("upgrade cancelled");
return 0;
}
}
// t_18fda844: a script that applies must apply the plan it approved.
// The digest comes from a prior `--dry-run` (the JSON plan output
// carries it); an interactive operator keeps the human escape hatch,
// exactly as with `--yes`. Verified against the plan this run just
// computed BEFORE anything is written - a plan that moved since the
// approved dry run is re-reviewed, never written over.
const approvalDigest = flags["approval-digest"] as string | undefined;
if (flags["json"] || !process.stdin.isTTY) {
if (approvalDigest === undefined) {
return fail(
"brain upgrade --apply requires --approval-digest in non-interactive mode " +
"(--json or non-TTY stdin); take it from the --dry-run plan output",
);
}
}
if (approvalDigest !== undefined && approvalDigest !== plan.digest) {
return fail(
`upgrade refused: approval digest mismatch: the plan changed since the approved ` +
`dry run (approved ${approvalDigest}, current plan ${plan.digest}); nothing was ` +
"written and no snapshot was taken. Re-run `o2b brain upgrade --dry-run` to review " +
"the current plan, then apply with its digest.",
);
}
let result;
const now = new Date();
try {
// The plan computed (and, interactively, confirmed) above, not a
// re-plan: a file that changed since it was read is refused by name
// instead of overwritten.
result = applyUpgrade(vault, { plan, now });
} catch (exc) {
// Recorded as the automatic path records it, so `o2b doctor` shows
// the latest failure and the automatic retry waits its cooldown.
try {
recordSelfHealUpgradeFailure(
vault,
(exc as Error).message ?? String(exc),
plan.files.filter((f) => f.status === "update").map((f) => f.path),
now,
);
} catch {
// The error below is what the operator acts on.
}
if (exc instanceof BrainUpgradeError) {
if (flags["json"]) {
// `drifted` names each refused file, so a script can tell a drift
// from any other failure without parsing the message.
okJson({ ok: false, error: exc.message, run_id: exc.runId, drifted: [...exc.drifted] });
} else {
process.stderr.write(`error: ${exc.message}\n`);
}
return 1;
}
return fail(`upgrade failed: ${describeErrorChain(exc)}`);
}
clearSelfHealUpgradeFailure(vault);
if (flags["json"]) {
okJson({
run_id: result.run_id,
snapshot_path: result.snapshot_path,
files_updated: result.files_updated,
});
} else {
ok(`run_id: ${result.run_id}`);
// Vault-relative, not the resolved path: the snapshot location is
// machine-derived, and the file name is already pinned by the run id
// printed directly above. The JSON twin keeps `snapshot_path` for
// consumers that need the resolved location.
ok(`snapshot: Brain/.snapshots/${basename(result.snapshot_path)}`);
for (const p of result.files_updated) ok(` updated: ${p}`);
}
return 0;
}