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 architect <project-path>` (Project History Suite,
* t_929da8a2): deterministic architecture notes for a code project,
* generated into the vault through the sentinel-region engine so
* operator edits survive every re-scan.
*
* The scan and the render have emitted through the progress spine and
* accepted a cooperative deadline since U1/U11, and
* `safeguard_timeout_architect_seconds` has resolved through the ladder
* since `OPERATION.architect` was added - but this verb built no
* safeguard and attached no rail, so both were declared surfaces with
* nothing behind them. This is their consumer.
*/
import { generateArchDocs } from "../../../core/brain/architect/generate.ts";
import { MANIFEST_STATUS, oneLine } from "../../../core/brain/architect/manifests.ts";
import type { ManifestReading } from "../../../core/brain/architect/manifests.ts";
import { RegionError } from "../../../core/brain/regions.ts";
import {
createSafeguard,
OPERATION,
resolveSafeguardTimeoutMs,
} from "../../../core/brain/safeguard.ts";
import { attachProgress, reportProgressRefusal } from "../../progress-rail.ts";
import { brainVerbContext, fail, ok, okJson, parse } from "../helpers.ts";
const USAGE = "usage: o2b brain architect <project-path> [--vault V] [--progress] [--json]";
/**
* One manifest on the JSON envelope: path, ecosystem, status, and the
* reason only when the status carries one. The parsed fact and the raw
* object stay in the notes; the envelope reports what was read.
*/
function manifestEntry(reading: ManifestReading): Record<string, string> {
return {
path: reading.path,
ecosystem: reading.ecosystem,
status: reading.status,
...(reading.detail === undefined ? {} : { detail: reading.detail }),
};
}
/** The text-mode line naming every manifest that was not read, or `null` when all were. */
function notReadLine(manifests: ReadonlyArray<ManifestReading>): string | null {
const notRead = manifests.filter((reading) => reading.status !== MANIFEST_STATUS.read);
if (notRead.length === 0) return null;
// A path is text from the scanned tree: folded to one line, so no control
// character reaches the terminal.
const named = notRead.map((reading) => `${oneLine(reading.path)} (${reading.status})`).join(", ");
return `manifests not read: ${named}`;
}
export async function cmdBrainArchitect(argv: string[]): Promise<number> {
const { flags, positional } = parse(argv, {
vault: { type: "string" },
progress: { type: "boolean" },
json: { type: "boolean" },
});
const asJson = flags["json"] === true;
const target = positional[0];
if (!target) return fail(USAGE);
// Progress is opt-in: attaching a sink by default would change the
// stderr of every existing invocation. The rail decides whether the
// stream can carry it at all.
const observation =
flags["progress"] === true
? attachProgress({ command: "brain", argv: ["architect"], jsonRequested: asJson })
: null;
// No interrupt handle: `generateRun` is synchronous end to end, so a
// signal handler cannot run while it does (see `interrupt.ts`). Leaving
// SIGINT alone keeps the keystroke lethal, and the plan-then-write
// restructure means a killed scan has written nothing.
try {
const { config, vault } = brainVerbContext(flags);
reportProgressRefusal(observation);
const res = generateArchDocs(vault, target, {
safeguard: createSafeguard({
operation: OPERATION.architect,
timeoutMs: resolveSafeguardTimeoutMs(OPERATION.architect, config ?? undefined),
}),
...(observation?.sink !== undefined ? { onProgress: observation.sink } : {}),
});
if (asJson) {
okJson({
ok: true,
repo_key: res.repoKey,
dir: res.dir,
overview_path: res.overviewPath,
decisions_path: res.decisionsPath,
module_paths: res.modulePaths,
manifests: res.manifests.map(manifestEntry),
created: res.created,
updated: res.updated,
unchanged: res.unchanged,
// Conditional, so a run whose observer never failed - and every
// run with no observer at all - emits exactly the payload it
// emitted before this field had a consumer.
...(res.progressFault !== null ? { progress_fault: res.progressFault } : {}),
});
return 0;
}
ok(
`architecture notes for ${res.repoKey}: ${res.created} created, ` +
`${res.updated} updated, ${res.unchanged} unchanged`,
);
ok(`overview: ${res.overviewPath}`);
// Only when needed: a run where every manifest was read prints the
// two lines it always printed.
const notRead = notReadLine(res.manifests);
if (notRead !== null) ok(notRead);
// The generation succeeded and the caller's stream did not. Carried
// out rather than swallowed: an observer that died mid-run explains
// a stream that stops before the last note.
if (res.progressFault !== null) {
process.stderr.write(`progress: observer failed (${res.progressFault})\n`);
}
return 0;
} catch (err) {
if (err instanceof RegionError) {
return fail(
`${err.message} - repair the sentinel markers (or delete the note to regenerate it)`,
);
}
return fail(err instanceof Error ? err.message : String(err));
}
}