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 { join } from "node:path";
import { resolveSearchConfig } from "../../../core/search/index.ts";
import { runDoctor } from "../../../core/brain/doctor.ts";
import {
reportSweptFailure,
SWEEP_ORIGIN,
type SweptPath,
} from "../../../core/brain/doctor/unreadable-path.ts";
import { BRAIN_ARCHIVES_REL } from "../../../core/brain/path-constants.ts";
import {
auditArchiveStamps,
type ArchiveStampAudit,
} from "../../../core/brain/hygiene/detectors/capture-scope.ts";
import {
sourceArchiveStats,
type ArchiveStats,
} from "../../../core/brain/provenance/source-archive.ts";
import { annotateEntityAliasIssues } from "../../../core/brain/doctor/entity-alias-verdicts.ts";
import { verdictFields, verdictLine } from "../../../core/decision-model/pair-verdict.ts";
import {
applyRepair,
type RepairConsent,
type RepairOutcome,
} from "../../../core/brain/diagnostics.ts";
import {
applyRemediation,
collectDriftedSlugs,
collectWidePermissions,
planRemediation,
} from "../../../core/brain/health/remediation.ts";
import { loadBrainConfigDetailed, resolveHealth } from "../../../core/brain/policy.ts";
import { nextCommandField } from "../../../core/brain/next-step.ts";
import { NO_EXIT_KEY, noExitReasons } from "../../../core/brain/doctor-exits.ts";
import type { DoctorIssue } from "../../../core/brain/types.ts";
import { advisoryIsLegal, emitNextSteps, type AdvisoryStream } from "../../advisory-rail.ts";
import {
brainVerbContext,
fail,
info,
ok,
parse,
readSingleLine,
resolveBrainAgent,
usageError,
requireBrainVaultFor,
} from "../helpers.ts";
/**
* One reported issue, machine-readable: the record the doctor produced
* plus the structural next command when its code is registered.
*
* The key is spread LAST so the pre-existing field order is untouched
* and an unregistered code produces byte-identical JSON. The builder is
* shared with the `brain_doctor` MCP tool through `nextCommandField`, so
* the two surfaces cannot disagree on the spelling or on which codes
* resolve.
*/
function withNextCommand<T extends Pick<DoctorIssue, "code">>(issue: T): Record<string, unknown> {
return { ...issue, ...nextCommandField(issue.code) };
}
/**
* One reported issue, human-readable. `label` carries its own trailing
* padding because the three streams have never been column-aligned and
* this task does not change a byte of what they print; the renderer
* exists so the three call sites stop repeating the same template.
*/
function renderIssueLine(
label: string,
issue: Pick<DoctorIssue, "code" | "message"> & { readonly path?: string },
): string {
return `${label} ${issue.code}: ${issue.message}${issue.path ? ` (${issue.path})` : ""}\n`;
}
/**
* The other half of the rail's answer: why a reported code named no
* command.
*
* `emitNextSteps` prints one line per exit and nothing for a code with
* none, which left two different situations looking identical - a class
* no single command resolves, and a class nobody has registered yet.
* `doctor-exits.ts` publishes the first as a written reason, and this
* prints it once per code, after the exits.
*
* It follows the rail's own stream discipline rather than deciding for
* itself: on a machine stream the reasons ride in the payload instead.
* The limit, stated: only codes the table publishes produce a line, so a
* code forwarded into `uncertain` from another module's vocabulary stays
* as quiet as it was - those are classified in `applier-capability.ts`.
*/
function explainMissingExits(codes: Iterable<string>, stream: AdvisoryStream): void {
if (!advisoryIsLegal(stream)) return;
for (const [code, reason] of noExitReasons(codes)) info(`no exit: ${code} - ${reason}`);
}
/**
* One archive section: the counts, or the named unavailability when the
* store itself could not be read.
*/
type ArchiveSection = (ArchiveStats & ArchiveStampAudit) | { readonly unavailable: true };
/**
* The informational archive section (answer trust): counts only - how many
* entries the durable source archive holds, their combined size, how many
* stamped pages lost their entry or disagree with it, and how many entries
* no page cites anymore. No fix verb: an archive is evidence, so pruning
* and recapture are operator calls, and the named findings live on the
* hygiene scan. Count-only also keeps this section from becoming a second
* finding surface the scans would have to agree with.
*
* Fail-soft: the section runs AFTER the fail-soft check pass, and an
* unreadable `Brain/.archives` used to throw past it - in `--json` mode
* printing nothing at all. An informational section's failure is
* uncertainty, not a failed run: the read is wrapped, the skip is named in
* the pass's `uncertain` stream exactly as the doctor's own sweeps name
* one, and the JSON answers `archives: { unavailable: true }`.
*/
function archiveSection(vault: string, swept: SweptPath): ArchiveSection {
try {
return { ...sourceArchiveStats(vault), ...auditArchiveStamps(vault) };
} catch (err) {
reportSweptFailure(
join(vault, BRAIN_ARCHIVES_REL),
"directory listing failed",
err,
swept,
SWEEP_ORIGIN.root,
);
return { unavailable: true };
}
}
/** The archive section of a machine with no vault: no source archive, so nothing in it. */
const EMPTY_ARCHIVE_SECTION: ArchiveSection = Object.freeze({
entries: 0,
totalBytes: 0,
missing: 0,
mismatched: 0,
uncited: 0,
});
export async function cmdBrainDoctor(argv: string[]): Promise<number> {
const { flags } = parse(argv, {
vault: { type: "string" },
strict: { type: "boolean" },
json: { type: "boolean" },
remediate: { type: "boolean" },
repair: { type: "boolean" },
apply: { type: "boolean" },
// t_b6bcd984: explicit consent for `--repair --apply` in a
// non-interactive run (the canonical upgrade ladder).
yes: { type: "boolean" },
agent: { type: "string" },
"dry-run": { type: "boolean" },
});
// With no vault configured (`null`) the pass runs the store-side checks
// (design D14); the repair and remediation modes rewrite the legacy tree
// and still need a vault.
const verbContext = brainVerbContext(flags, { vault: "optional" });
const { config, vault: configured } = verbContext;
const treeVerb = flags["repair"]
? "doctor --repair"
: flags["remediate"]
? "doctor --remediate"
: null;
if (treeVerb !== null) requireBrainVaultFor(verbContext, treeVerb);
const vault = configured;
// `--apply` is a modifier of `--repair`; on its own it would silently
// fall through to a read-only doctor run, so reject it up front.
if (flags["apply"] && !flags["repair"]) {
return usageError("--apply requires --repair");
}
// Guarded repair mode (O2). Opt-in and dry-run by default; `--apply`
// performs the fixes. `--strict` stays read-only, so it can never be
// combined with an applying repair. Plain / `--strict` doctor below is
// untouched and byte-identical when `--repair` is absent.
if (flags["repair"]) {
if (flags["strict"] && flags["apply"]) {
return usageError("cannot combine --strict (read-only) with --repair --apply");
}
const dryRun = !flags["apply"];
// t_b6bcd984: fail-closed consent above the write, the canonical
// `brain upgrade --apply` ladder. Without --yes, a --json or
// non-TTY apply refuses before writing and logs no event; a TTY
// run sees the dry-run preview (now with the per-file diffs) and is
// asked once. A dry run never prompts and never gates.
//
// M6: the preview, the prompt and the apply all sit inside the try -
// a preview-side failure (an unclassified repair code, a fixer that
// cannot derive its target) is a `repair failed:` answer, not an
// uncaught error. The apply is pinned to the approved preview: only
// the targets the preview showed may be written, so a finding that
// appears while the prompt waits stays for the next run instead of
// being written behind an approval it was never shown in.
try {
let consent: RepairConsent | undefined;
let approvedTargets: ReadonlyArray<string> | undefined;
if (!dryRun) {
if (flags["yes"]) {
consent = "yes-flag";
} else if (flags["json"] || !process.stdin.isTTY) {
// M4: the refusal carries its verdict in a JSON envelope under
// --json, on the payload stream a headless consumer parses -
// the reserved `headless-refused` verdict, nothing written.
if (flags["json"]) {
process.stdout.write(
JSON.stringify(
{
consent: "headless-refused",
written: false,
error:
"brain doctor --repair --apply requires --yes in non-interactive mode " +
"(--json or non-TTY stdin); nothing was written",
},
null,
2,
) + "\n",
);
return 1;
}
return fail(
"brain doctor --repair --apply requires --yes in non-interactive mode " +
"(--json or non-TTY stdin); nothing was written",
);
} else {
const preview = applyRepair(requireBrainVaultFor(verbContext, "doctor --repair"), {
dryRun: true,
agent: resolveBrainAgent(flags, config),
configPath: config,
dbPath: resolveSearchConfig({ vault, configPath: config ?? undefined }).dbPath,
});
// M6: nothing to fix, nothing to approve - a prompt over an
// empty preview asks consent for a no-op. Skip straight to the
// apply, which reports the needs-review and unfixable classes
// honestly and records `unchanged` as the verdict.
if (preview.applied.length === 0) {
consent = "unchanged";
} else {
renderRepair(preview, false);
process.stderr.write("Proceed? [y/N] ");
const ans = await readSingleLine();
if (ans.toLowerCase() !== "y" && ans.toLowerCase() !== "yes") {
ok("repair cancelled");
return 0;
}
consent = "interactive-yes";
approvedTargets = preview.applied.map((f) => f.target);
}
}
}
const outcome = applyRepair(requireBrainVaultFor(verbContext, "doctor --repair"), {
dryRun,
agent: resolveBrainAgent(flags, config),
configPath: config,
dbPath: resolveSearchConfig({ vault, configPath: config ?? undefined }).dbPath,
...(consent === undefined ? {} : { consent }),
...(approvedTargets === undefined ? {} : { approvedTargets }),
});
return renderRepair(outcome, Boolean(flags["json"]));
} catch (exc) {
return fail(`repair failed: ${(exc as Error).message ?? exc}`);
}
}
let result;
try {
result = runDoctor(vault, {
strict: Boolean(flags["strict"]),
dbPath: resolveSearchConfig({ vault, configPath: config ?? undefined }).dbPath,
// Checks that read a config gate (the recall-channel coverage check reads
// whether prompt-side recall injection is enabled) must read the SAME
// config this invocation was pointed at. Letting them fall through to
// default discovery would make `--config other.yaml` diagnose one file
// and report on another.
...(config !== null ? { configPath: config } : {}),
});
} catch (exc) {
return fail(`doctor failed: ${(exc as Error).message ?? exc}`);
}
// Where an advisory line may legally go. `brain` renders its own JSON,
// so under `--json` the rail suppresses every line and the pointer
// travels as a payload field instead. The verb never decides this for
// itself - see `advisory-rail.ts`.
const stream: AdvisoryStream = {
command: "brain",
argv,
jsonRequested: Boolean(flags["json"]),
};
if (flags["remediate"]) {
// Never auto-repair a vault that has structural errors - those need
// an operator, and remediation assumes a parseable tree.
if (result.errors.length > 0) {
for (const e of result.errors) process.stdout.write(renderIssueLine("[ERROR]", e));
const errorCodes = result.errors.map((e) => e.code);
emitNextSteps(errorCodes, stream);
explainMissingExits(errorCodes, stream);
return fail("doctor found errors; remediation aborted");
}
try {
return runRemediate(
requireBrainVaultFor(verbContext, "doctor --remediate"),
Boolean(flags["dry-run"]),
Boolean(flags["json"]),
result,
);
} catch (exc) {
return fail(`remediation failed: ${(exc as Error).message ?? exc}`);
}
}
// Unit F. `uncertain` is a third stream beside warnings and errors:
// sub-operations the doctor attempted but cannot claim completed
// cleanly. It is emitted ONLY when non-empty, so a clean vault's
// output - JSON and human alike - is byte-identical to before, and it
// deliberately does not feed the exit code: uncertainty is not a
// failure, and folding it into `--strict` would turn an unreadable
// field into a broken build.
// A mutable copy of the pass's stream: the archive section below appends
// its own skip to it, and `runDoctor` returned the array frozen.
const uncertain = [...(result.uncertain ?? [])];
// The sweep identity the archive section reports its skips under - the
// consequence names the question an unreadable store leaves open.
const swept: SweptPath = {
site: "brain.doctor.archiveSection",
consequence: "the archive counts could not be taken",
uncertain,
};
// The archive section is taken ONCE, before anything is rendered or
// derived from the streams: an unreadable store names its skip in the
// stream above, so the failure feeds the exit census and is visible in
// the same pass instead of one key (or one line) late.
// The source archive is a vault's; with no vault it holds nothing.
const section = vault === null ? EMPTY_ARCHIVE_SECTION : archiveSection(vault, swept);
// Every code the three streams reported, in the order an operator reads
// them. Feeds both the rail and the explanation of what the rail could
// not name, so the two can never disagree about which codes have an exit.
const reportedCodes = [...result.errors, ...result.warnings, ...uncertain].map(
(issue) => issue.code,
);
// Published reasons for the reported codes that resolve to no command.
// Empty - hence the key absent, hence byte-identical output - whenever
// every reported code has an exit, and on a clean vault.
const noExit = noExitReasons(reportedCodes);
// Optional decision-model verdicts on alias-merge candidates (use
// `dedup`); null while off, and both renderings below are unchanged.
const aliasVerdicts =
vault === null
? null
: await annotateEntityAliasIssues(vault, result.warnings, { configPath: config });
const warnings = aliasVerdicts === null ? result.warnings : aliasVerdicts.map((a) => a.item);
const warningExtra = new Map<DoctorIssue, ReturnType<typeof verdictFields>>();
const warningLine = new Map<DoctorIssue, string>();
for (const a of aliasVerdicts ?? []) {
if (a.verdict === null) continue;
warningExtra.set(a.item, verdictFields(a));
warningLine.set(a.item, verdictLine(a));
}
if (flags["json"]) {
process.stdout.write(
JSON.stringify(
{
warnings: warnings.map((w) => ({ ...withNextCommand(w), ...warningExtra.get(w) })),
errors: result.errors.map(withNextCommand),
...(uncertain.length > 0 ? { uncertain: uncertain.map(withNextCommand) } : {}),
// Beside the streams, once per code, rather than repeated on
// every issue record: a reason is about a CLASS, unlike a next
// command, and two hundred malformed timestamps share one.
...(noExit.size > 0 ? { [NO_EXIT_KEY]: Object.fromEntries(noExit) } : {}),
// Count-only informational archive section (answer trust): the
// key is always present, so a caller never infers the section's
// existence from a missing key - and when the store could not be
// read, the key names the unavailability instead of a count.
archives: section,
},
null,
2,
) + "\n",
);
} else {
for (const e of result.errors) process.stdout.write(renderIssueLine("[ERROR]", e));
for (const w of warnings) {
process.stdout.write(renderIssueLine("[WARN] ", w));
const line = warningLine.get(w);
if (line !== undefined) process.stdout.write(` ${line}\n`);
}
for (const u of uncertain) process.stdout.write(renderIssueLine("[UNSURE]", u));
if (result.errors.length === 0 && result.warnings.length === 0 && uncertain.length === 0) {
ok("brain doctor: clean");
}
// One line, and only when there is something to describe: a vault that
// has never archived a source gains no line at all, and an orphaned
// entry - evidence no page cites - is something to describe. An
// unreadable store is already named by its `[UNSURE]` line above, so
// it gains no counts line either.
const archives = "unavailable" in section ? null : section;
if (
archives !== null &&
(archives.entries > 0 ||
archives.missing > 0 ||
archives.mismatched > 0 ||
archives.uncited > 0)
) {
process.stdout.write(
`archives: ${archives.entries} entries, ${archives.totalBytes} bytes, ` +
`${archives.missing} missing, ${archives.mismatched} mismatched, ` +
`${archives.uncited} uncited\n`,
);
}
}
// no-dead-ends, task 4: the exits, after the diagnosis. Errors first,
// then warnings, then the uncertain stream - the order an operator
// reads them in. The rail prints nothing under `--json` (the pointer
// rode out as `next_command` above) and nothing for a code with no
// registered signal.
emitNextSteps(reportedCodes, stream);
// ...and, after them, why the codes that named none have none. Without
// this a finding with no exit and a finding whose exit nobody
// registered read identically.
explainMissingExits(reportedCodes, stream);
if (result.errors.length > 0) return 1;
if (result.warnings.length > 0 && flags["strict"]) return 2;
return 0;
}
/**
* `--remediate [--dry-run]`: build a dependency-ordered plan from the
* doctor's semantic findings plus content-hash drift, then apply the
* auto-safe steps (or preview them under `--dry-run`). Needs-review
* steps are always listed but never applied.
*/
function runRemediate(
vault: string,
dryRun: boolean,
json: boolean,
result: ReturnType<typeof runDoctor>,
): number {
let stepCap = 20;
try {
stepCap = resolveHealth(loadBrainConfigDetailed(vault).config).remediation_step_cap;
} catch {
/* fall back to default cap */
}
const sh = result.semantic_health;
const plan = planRemediation(
{
driftedSlugs: collectDriftedSlugs(vault),
widePermissions: collectWidePermissions(vault),
contradictions: (sh?.contradictions ?? []).map((c) => ({ aId: c.aId, bId: c.bId })),
staleClaims: (sh?.staleClaims ?? []).map((s) => ({ id: s.id })),
conceptGaps: (sh?.conceptGaps ?? []).map((g) => ({ term: g.term })),
},
{ stepCap },
);
const outcome = applyRemediation(vault, plan, { dryRun });
if (json) {
process.stdout.write(JSON.stringify({ plan: plan.steps, outcome }, null, 2) + "\n");
return 0;
}
const verb = dryRun ? "would apply" : "applied";
for (const s of outcome.applied) {
process.stdout.write(`[${verb}] ${s.code}: ${s.detail}\n`);
}
for (const s of outcome.skipped) {
process.stdout.write(`[skip:${s.classification}] ${s.code}: ${s.detail}\n`);
}
ok(
`remediation ${dryRun ? "dry-run" : "complete"}: ` +
`${outcome.applied.length} ${verb}, ${outcome.skipped.length} skipped`,
);
return 0;
}
/**
* Render the guarded repair outcome. Dry-run lists what `--apply` would
* do, with the unified diff of each fixable file under its line
* (t_b6bcd984); apply lists what was done. Needs-review instances and
* unfixable classes always print with their next-command hint (supplied
* by the diagnostics-signal definition, never hardcoded here).
*/
function renderRepair(outcome: RepairOutcome, json: boolean): number {
if (json) {
process.stdout.write(JSON.stringify(outcome, null, 2) + "\n");
return 0;
}
const verb = outcome.dryRun ? "would fix" : "fixed";
for (const f of outcome.applied) {
process.stdout.write(`[${verb}] ${f.code}: ${f.detail}\n`);
if (f.diff) {
for (const d of f.diff.split("\n")) process.stdout.write(` ${d}\n`);
}
}
for (const r of outcome.needsReview) {
process.stdout.write(
`[needs-review] ${r.code}: ${r.detail}${r.reason ? ` (${r.reason})` : ""}\n`,
);
}
for (const u of outcome.unfixable) {
process.stdout.write(`[not auto-repairable] ${u.code} x${u.count}: run \`${u.nextCommand}\`\n`);
}
if (
outcome.applied.length === 0 &&
outcome.needsReview.length === 0 &&
outcome.unfixable.length === 0
) {
ok("brain doctor --repair: nothing to fix");
return 0;
}
ok(
`repair ${outcome.dryRun ? "dry-run" : "complete"}: ` +
`${outcome.applied.length} ${verb}, ${outcome.needsReview.length} needs-review, ` +
`${outcome.unfixable.length} not auto-repairable`,
);
return 0;
}