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 { defaultConfigPath } from "../../../core/config.ts";
import { resolveSearchConfig } from "../../../core/search/index.ts";
import {
applySchemaAdminMutations,
buildSchemaGraph,
buildSchemaLint,
buildSchemaStats,
buildSchemaSyncResult,
explainSchemaToken,
parseSchemaMutationPayloads,
reviewSchemaOrphans,
} from "../../../core/brain/schema-admin.ts";
import {
assessSchemaPackIntegrity,
SCHEMA_PACK_INTEGRITY,
type SchemaPackIntegrity,
} from "../../../core/brain/schema-integrity.ts";
import {
previewSchemaMutations,
SCHEMA_ADOPT_ONLY_UNSWITCHED,
} from "../../../core/brain/schema-mutate.ts";
import { formatStampMismatch } from "../../../core/integrity/stamp.ts";
import {
buildSchemaReport,
type BrainSchemaReport,
type SchemaReportFinding,
} from "../../../core/brain/schema-report.ts";
import { SCHEMA_VOCAB_CATEGORIES } from "../../../core/brain/schema-vocab.ts";
import { isStoreOnly } from "../../../core/store/store-only.ts";
import { fail, parse, resolveBrainVault } from "../helpers.ts";
export async function cmdBrainSchema(argv: string[]): Promise<number> {
const subcommands = new Set([
"report",
"stats",
"lint",
"graph",
"explain",
"orphans",
"apply",
"sync",
]);
const firstArg = argv[0];
let subcommand = "report";
let args = argv;
if (firstArg !== undefined && !firstArg.startsWith("-")) {
if (!subcommands.has(firstArg)) return fail(`schema failed: unknown subcommand ${firstArg}`);
subcommand = firstArg;
args = argv.slice(1);
}
const { flags, positional } = parse(args, {
vault: { type: "string" },
json: { type: "boolean" },
mutation: { type: "string-array" },
actor: { type: "string", default: "cli" },
reason: { type: "string" },
"dry-run": { type: "boolean" },
"adopt-unattested": { type: "boolean" },
"batch-size": { type: "string", default: "100" },
});
const config = defaultConfigPath();
let vault: string;
try {
vault = resolveBrainVault(flags["vault"] as string | undefined, config);
} catch (exc) {
return fail(`schema failed: ${(exc as Error).message ?? exc}`);
}
try {
switch (subcommand) {
case "report": {
const report = buildSchemaReport(vault);
// The report used to describe the ontology without saying whether
// it is still the ontology that was applied. An intact pack, a
// hand-edited one, and one nothing ever sealed rendered the same.
const integrity = assessSchemaPackIntegrity(vault);
if (flags["json"]) return writeJson({ ...report, integrity });
process.stdout.write(renderSchemaReportText(report, integrity));
return 0;
}
case "stats":
return writeResult(buildSchemaStats(vault), Boolean(flags["json"]), renderGenericText);
case "lint":
return writeResult(
buildSchemaLint(vault, {
dbPath: resolveSearchConfig({ vault, configPath: config ?? undefined }).dbPath,
}),
Boolean(flags["json"]),
renderGenericText,
);
case "graph":
return writeResult(buildSchemaGraph(vault), Boolean(flags["json"]), renderGenericText);
case "explain": {
const token = positional[0];
if (!token) throw new Error("schema explain requires a token");
return writeResult(
explainSchemaToken(vault, token),
Boolean(flags["json"]),
renderGenericText,
);
}
case "orphans":
return writeResult(reviewSchemaOrphans(vault), Boolean(flags["json"]), renderGenericText);
case "apply": {
const mutationPayloads = (flags["mutation"] as string[] | undefined) ?? [];
// Judged on the parsed batch, so `--mutation '[]'` is no mutation
// either. Adoption runs on its own too, on a store-only machine: an
// empty batch that changes no entry and records the adopted records
// in its audit row. The lane refuses it on an unswitched machine,
// where an empty apply would rewrite and re-attest `_brain.yaml`.
const mutations = parseSchemaMutationPayloads(mutationPayloads);
if (mutations.length === 0) {
if (!flags["adopt-unattested"]) {
throw new Error("schema apply requires --mutation JSON (or --adopt-unattested alone)");
}
if (!isStoreOnly({ vault, configPath: config })) {
throw new Error(SCHEMA_ADOPT_ONLY_UNSWITCHED);
}
}
// `--dry-run` is parsed for every schema subcommand. Until the
// preview existed, `apply` accepted the flag and wrote anyway - an
// operator asking to look first got a mutated vault schema.
if (flags["dry-run"]) {
return writeResult(
previewSchemaMutations(vault, mutations),
Boolean(flags["json"]),
renderGenericText,
);
}
const reason = flags["reason"] as string | undefined;
const result = await applySchemaAdminMutations(vault, mutations, {
actor: flags["actor"] as string,
...(reason !== undefined ? { reason } : {}),
// The operator's own change (store-only machines write it as a
// human-authority settings record).
authority: "human",
...(flags["adopt-unattested"] ? { adoptUnattested: true } : {}),
});
return writeResult(result, Boolean(flags["json"]), renderGenericText);
}
case "sync": {
const batchSize = Number.parseInt(flags["batch-size"] as string, 10);
if (!Number.isInteger(batchSize) || batchSize <= 0) {
throw new Error("--batch-size must be a positive integer");
}
// Refuses and exits non-zero: see `SchemaSyncUnavailableError`. The
// flags above are still validated so an operator learns about a bad
// `--batch-size` from the same message they always did.
return writeResult(buildSchemaSyncResult(vault), Boolean(flags["json"]), renderGenericText);
}
}
} catch (exc) {
return fail(`schema failed: ${(exc as Error).message ?? exc}`);
}
return fail(`schema failed: unknown subcommand ${subcommand}`);
}
function writeResult<T>(value: T, json: boolean, renderText: (value: T) => string): number {
if (json) return writeJson(value);
process.stdout.write(renderText(value));
return 0;
}
function writeJson(value: unknown): number {
process.stdout.write(JSON.stringify(value, null, 2) + "\n");
return 0;
}
function renderGenericText(value: unknown): string {
return JSON.stringify(value, null, 2) + "\n";
}
/**
* One line naming the integrity verdict, plus the evidence behind it.
*
* `unverified` carries its reason on the same line: the status alone would
* tell an operator that something could not be checked without telling
* them which of the three ways it happened, which is the silence this unit
* removes rather than relocates. `modified` is followed by the shared
* mismatch rendering, so it reads the same here as on every other
* integrity surface.
*/
function renderIntegrityLines(integrity: SchemaPackIntegrity): ReadonlyArray<string> {
const reason =
integrity.unverified_reason === undefined ? "" : ` (${integrity.unverified_reason})`;
const lines = [`integrity: ${integrity.status}${reason}`];
if (integrity.status === SCHEMA_PACK_INTEGRITY.modified) {
for (const mismatch of integrity.mismatches) lines.push(` ${formatStampMismatch(mismatch)}`);
}
return lines;
}
function renderSchemaReportText(report: BrainSchemaReport, integrity: SchemaPackIntegrity): string {
const lines = ["brain schema", "", ...renderIntegrityLines(integrity), "", "vocabulary:"];
for (const category of SCHEMA_VOCAB_CATEGORIES) {
lines.push(` ${category}: ${report.vocabulary[category].join(", ") || "(none)"}`);
}
lines.push("", "usage:");
for (const category of SCHEMA_VOCAB_CATEGORIES) {
const usage = report.usage[category].map((item) => `${item.token} x${item.count}`).join(", ");
lines.push(` ${category} usage: ${usage || "(none)"}`);
}
lines.push("", "findings:");
if (report.findings.length === 0) {
lines.push(" none");
} else {
for (const finding of report.findings) lines.push(` ${renderFinding(finding)}`);
}
return lines.join("\n") + "\n";
}
/**
* One finding as a line, exhaustively over the union.
*
* The `switch` with a `never` default is deliberate: this used to be two
* `if`s and a trailing `return` that rendered EVERY other kind as
* `[unused-declaration]`, so a new member of the union would have been
* printed under the wrong label with no compile error to say so.
*/
function renderFinding(finding: SchemaReportFinding): string {
switch (finding.kind) {
case "unknown-token":
return `[unknown-token] ${finding.category} ${finding.token} (${finding.path})`;
case "link-constraint-violation":
return (
`[link-constraint-violation] ${finding.relation} ` +
`${finding.source_type ?? "?"}->${finding.target_type ?? "?"} ` +
`(${finding.source} -> ${finding.target})`
);
case "unreadable-artifact":
return `[unreadable-artifact] ${finding.category} ${finding.path}: ${finding.detail}`;
case "unused-declaration":
return `[unused-declaration] ${finding.category} ${finding.token}`;
default: {
const unreachable: never = finding;
return unreachable;
}
}
}