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 CLI verb-handler facade.
*
* # Import convention (load-bearing)
*
* Every file under `src/cli/brain/verbs/` MUST import shared helpers
* through this module β never directly from `../argparse.ts`,
* `../output.ts`, `../coerce.ts`, or `../helpers.ts`. The barrel
* keeps one source of truth for "what is available to a brain verb"
* and lets the helper bodies move between submodules without a
* cross-cutting import sweep.
*
* # Layout
*
* - `./help-text.ts` β `BRAIN_HELP` + per-verb `VERB_HELP`.
* - `./upgrade-render.ts` β `renderUpgradePlanJson` (the row-level
* projection; this barrel wraps it to add
* the plan digest), `printUpgradePlanText`,
* `renderUnifiedDiff`.
* - `./query-render.ts` β text renderers for `brain query`.
* - `./rollback-prompt.ts` β `diffSummary`, `readSingleLine`.
*
* Vault resolution and the `parse` flag-parsing wrapper stay in this
* file because they are tiny and called by every verb.
*/
import {
defaultConfigPath,
resolveAgentName,
resolveTimezone,
resolveVault,
} from "../../core/config.ts";
import { formatLocalTimestamp } from "../../core/brain/present-time.ts";
import { isoSecond } from "../../core/brain/time.ts";
import type { UpgradePlan } from "../../core/brain/upgrade.ts";
import { CliError, parseFlags, type FlagsSchema } from "../argparse.ts";
import {
NO_VAULT_ERROR,
NoVaultConfiguredError,
normalizeFlagString,
resolveOptionalVault,
vaultRequiredMessage,
} from "../helpers.ts";
import { renderUpgradePlanJson as renderUpgradePlanJsonRows } from "./upgrade-render.ts";
// ββ Vault resolution ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
export function resolveBrainVault(flagVal: string | undefined, configPath: string | null): string {
// Mirror `requireVault` in `../helpers.ts`: explicit `--vault ""`
// is a user error, not an excuse to fall through to `resolveVault`.
const explicit = normalizeFlagString(flagVal);
if (flagVal !== undefined && explicit === null) {
throw new CliError(NO_VAULT_ERROR);
}
const vault = explicit ?? resolveVault(configPath ?? undefined);
if (vault === null || vault === undefined) {
throw new CliError(NO_VAULT_ERROR);
}
return vault;
}
// ββ Verb context ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
/** Parsed flags shape every Brain verb receives from {@link parse}. */
export type BrainVerbFlags = Record<string, string | boolean | string[] | undefined>;
export interface BrainVerbContext {
readonly config: string;
readonly vault: string;
}
/**
* The verb context of a verb that also works with no vault (design D14):
* `vault` is `null` when none is configured. A verb that needs one after
* all (a vault-adapter step) asks {@link requireBrainVaultFor}.
*/
export interface OptionalVaultBrainVerbContext {
readonly config: string;
readonly vault: string | null;
}
/** Options of {@link brainVerbContext}. */
export interface BrainVerbContextOptions {
/** `optional`: answer `vault: null` instead of refusing when none is configured. */
readonly vault: "optional";
}
/**
* Resolve the (config, vault) pair every Brain verb needs.
*
* Call it exactly where the verb used to resolve the vault β flag
* validation that must precede vault resolution (and its error
* output) stays ahead of this call, so verb output is unchanged.
* Throws `CliError` for a missing or explicitly empty vault, same as
* {@link resolveBrainVault}.
*/
export function brainVerbContext(flags: BrainVerbFlags): BrainVerbContext;
export function brainVerbContext(
flags: BrainVerbFlags,
options: BrainVerbContextOptions,
): OptionalVaultBrainVerbContext;
export function brainVerbContext(
flags: BrainVerbFlags,
options?: BrainVerbContextOptions,
): BrainVerbContext | OptionalVaultBrainVerbContext {
const config = defaultConfigPath();
const flag = flags["vault"] as string | undefined;
if (options?.vault !== "optional") return { config, vault: resolveBrainVault(flag, config) };
// The shared rule (an explicit empty `--vault` is a user error), with
// the brain dispatcher's error type.
try {
return { config, vault: resolveOptionalVault(flag, config) };
} catch (err) {
if (err instanceof NoVaultConfiguredError) throw new CliError(NO_VAULT_ERROR);
throw err;
}
}
/**
* The vault of an optional-vault context, or a `CliError` that names the
* verb when there is none: `o2b brain <verb>` needs a vault here. The
* brain dispatcher (`handleBrainSubcommand`) answers every `CliError` with
* exit 1, the code the no-vault error always had inside `o2b brain`; it is
* not the exit-2 usage error of the top-level commands.
*/
export function requireBrainVaultFor(context: OptionalVaultBrainVerbContext, verb: string): string {
if (context.vault === null) throw new CliError(vaultRequiredMessage(`o2b brain ${verb}`));
return context.vault;
}
/** Acting agent name: an explicit `--agent` flag wins over the config. */
export function resolveBrainAgent(flags: BrainVerbFlags, config: string): string {
return (flags["agent"] as string | undefined) ?? resolveAgentName(config);
}
// ββ Flag-parsing wrapper ββββββββββββββββββββββββββββββββββββββββββββββββββββ
export function parse(
argv: ReadonlyArray<string>,
schema: FlagsSchema,
): {
flags: Record<string, string | boolean | string[] | undefined>;
positional: string[];
} {
return parseFlags(argv, schema);
}
// ββ Re-exports (the barrel that verb handlers import from) ββββββββββββββββββ
export { CliError } from "../argparse.ts";
export { describeErrorChain, fail, failWith, info, ok, okJson, writeJson } from "../output.ts";
/**
* Usage / argument error: plain message to stderr, exit code 2. Distinct
* from `fail()` (exit 1), which is reserved for operational/runtime
* failures. Mirrors the exit-2 usage-error contract the brain verbs use
* (e.g. `tune`, `bridges`).
*/
export function usageError(message: string): number {
process.stderr.write(`error: ${message}\n`);
return 2;
}
export { ISO_8601_RE, parseOptionalIsoDate } from "../coerce.ts";
export { NO_VAULT_ERROR, normalizeFlagString, resolveOptionalVault } from "../helpers.ts";
export { BRAIN_HELP, MAINTENANCE_USAGE, VERB_HELP } from "./help-text.ts";
export { printUpgradePlanText, renderUnifiedDiff } from "./upgrade-render.ts";
/**
* The plan JSON an operator reads, with its seal (t_18fda844): the
* digest carried from `--dry-run` to `--apply` via `--approval-digest`
* (`brain upgrade --apply` requires it in non-interactive mode and
* verifies it against the freshly computed plan, exactly as
* import-claude-memory's does), so what lands is what was reviewed.
* Emitted unconditionally - a `planUpgrade` result is always sealed -
* and the row projection stays in `./upgrade-render.ts` (imported above
* under an alias); the barrel is where the seal becomes visible, because
* this is the module every verb imports its renderers through.
*/
export function renderUpgradePlanJson(
plan: UpgradePlan,
): ReturnType<typeof renderUpgradePlanJsonRows> & { digest: string } {
return { ...renderUpgradePlanJsonRows(plan), digest: plan.digest };
}
export {
renderQueryPreferenceText,
renderQueryRuleTopicText,
renderQueryLogText,
} from "./query-render.ts";
export { diffSummary, readSingleLine, type DiffSummary } from "./rollback-prompt.ts";
/**
* Timezone presentation (t_2ccadc6a): additive `timezone` +
* `local_time` fields for JSON envelopes when the operator configured
* an IANA zone; empty object (byte-identical output) otherwise.
*/
export function localTimeFields(configPath: string | null): Record<string, string> {
const tz = resolveTimezone(configPath ?? undefined);
if (tz === null) return {};
return { timezone: tz, local_time: formatLocalTimestamp(isoSecond(new Date()), tz) };
}