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 {
applySchemaAdminMutations,
buildSchemaGraph,
buildSchemaLint,
buildSchemaStats,
coerceSchemaMutations,
explainSchemaToken,
getActiveSchemaPack,
listSchemaPacks,
reviewSchemaOrphans,
} from "../core/brain/schema-admin.ts";
import { previewSchemaMutations, type SchemaMutation } from "../core/brain/schema-mutate.ts";
import { WriteRefusedError } from "../core/brain/write-disposition.ts";
import { buildSchemaReport, type SchemaReportFinding } from "../core/brain/schema-report.ts";
import { reachView } from "../core/brain/reach-view.ts";
import { TRANSPORT_REACH } from "../core/graph/transport-reach.ts";
import { resolveSearchConfig } from "../core/search/index.ts";
import { INVALID_PARAMS, MCPError } from "./protocol.ts";
import { coerceBool, coerceStr } from "./coerce.ts";
import { MCP_PREVIEW_BUDGET } from "./preview-budget.ts";
import { contextReach, type ServerContext, type ToolDefinition } from "./tool-contract.ts";
/**
* The pages a schema finding names, as references the reach view judges.
* A declaration nobody uses names no page.
*/
function findingRefs(finding: SchemaReportFinding): ReadonlyArray<string> {
switch (finding.kind) {
case "unknown-token":
case "unreadable-artifact":
return [finding.path];
case "link-constraint-violation":
return [finding.source, finding.target];
case "unused-declaration":
return [];
}
}
/**
* The findings a caller may see at its reach. Every finding that names a
* record names it by path, so below local reach a record the caller may
* not read is reported by no view, and `stats` counts what `lint` lists:
* a malformed private page answers as an absent one.
*/
function visibleFindings<T extends SchemaReportFinding>(
ctx: ServerContext,
findings: ReadonlyArray<T>,
): ReadonlyArray<T> {
const view = reachView(ctx.vault, contextReach(ctx));
return view.filtersNothing ? findings : view.keep(findings, findingRefs);
}
// Read-side handlers behind the consolidated `schema_inspect` views.
// The per-view alias tools were removed in 1.0.0 (tombstones in
// `REMOVED_TOOLS`, src/mcp/tools.ts).
const SCHEMA_INSPECT_VIEWS: Readonly<
Record<string, (ctx: ServerContext, args: Record<string, unknown>) => Promise<unknown> | unknown>
> = Object.freeze({
graph: (ctx: ServerContext) => buildSchemaGraph(ctx.vault),
lint: (ctx: ServerContext) => {
const lint = buildSchemaLint(ctx.vault, {
dbPath: resolveSearchConfig({ vault: ctx.vault, configPath: ctx.configPath ?? undefined })
.dbPath,
});
return { ...lint, findings: visibleFindings(ctx, lint.findings) };
},
stats: (ctx: ServerContext) => {
const stats = buildSchemaStats(ctx.vault);
if (contextReach(ctx) === TRANSPORT_REACH.local) return stats;
return {
...stats,
findings: visibleFindings(ctx, buildSchemaReport(ctx.vault).findings).length,
};
},
orphans: (ctx: ServerContext) => {
const orphans = reviewSchemaOrphans(ctx.vault);
return { ...orphans, orphans: visibleFindings(ctx, orphans.orphans) };
},
explain_type: (ctx: ServerContext, args: Record<string, unknown>) =>
explainSchemaToken(ctx.vault, coerceStr(args, "token")!),
active_pack: (ctx: ServerContext) => getActiveSchemaPack(ctx.vault),
packs: (ctx: ServerContext) => listSchemaPacks(ctx.vault),
});
function toolSchemaInspect(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<unknown> | unknown {
const view = typeof args["view"] === "string" ? args["view"] : "";
const handler = SCHEMA_INSPECT_VIEWS[view];
if (handler === undefined) {
throw new MCPError(
INVALID_PARAMS,
`view must be one of ${Object.keys(SCHEMA_INSPECT_VIEWS).join(", ")}; got ${JSON.stringify(
args["view"],
)}`,
);
}
return handler(ctx, args);
}
export const SCHEMA_TOOLS: ReadonlyArray<ToolDefinition> = [
{
name: "schema_inspect",
kind: "read",
previewBudget: MCP_PREVIEW_BUDGET,
description:
"Read-only Brain schema inspection, one tool for every view: graph, lint, stats, orphans, explain_type (needs token), active_pack, or packs. Replaces the per-view schema read tools.",
inputSchema: {
type: "object",
properties: {
view: {
type: "string",
enum: ["graph", "lint", "stats", "orphans", "explain_type", "active_pack", "packs"],
description: "Which schema view to produce.",
},
token: { type: "string", description: "view=explain_type: schema token to explain." },
},
required: ["view"],
additionalProperties: false,
},
handler: toolSchemaInspect,
},
{
name: "schema_apply_mutations",
kind: "write",
description:
"Apply an atomic batch of schema mutations to the active schema pack and write an audit record. With dry_run, returns the pack that would result and its diff instead, writing nothing.",
inputSchema: {
type: "object",
properties: {
mutations: {
type: "array",
description: "Array of schema mutation objects.",
items: { type: "object" },
},
actor: {
type: "string",
description: "Audit actor label. Defaults to mcp.",
},
reason: {
type: "string",
description: "Optional audit reason.",
},
dry_run: {
type: "boolean",
description:
"Preview WITHOUT writing: the pack that would result plus its diff, same validator rejections, no config write, no audit record. Absent by default.",
},
},
required: ["mutations"],
additionalProperties: false,
},
handler: async (ctx, args) => {
let mutations: SchemaMutation[];
let actor: string;
let reason: string | undefined;
let dryRun: boolean;
try {
mutations = coerceSchemaMutations(args["mutations"]);
actor = coerceStr(args, "actor", false, "mcp")!;
reason = coerceStr(args, "reason", false) ?? undefined;
dryRun = coerceBool(args, "dry_run");
} catch (err) {
throw new MCPError(INVALID_PARAMS, (err as Error).message);
}
// The preview shape carries no `audit_path` and no `applied` count, so
// a dry run can never be read back as a mutation that landed.
if (dryRun) return previewSchemaMutations(ctx.vault, mutations);
try {
return await applySchemaAdminMutations(ctx.vault, mutations, {
actor,
...(reason !== undefined ? { reason } : {}),
// An agent's change: on a store-only machine it never outvotes a
// field the operator set.
authority: "agent",
// The deny consult answers for the credential-minted subject,
// never for the caller-named actor label (write-side-trust,
// Task 7) - the same discipline as the delete tool.
...(ctx.requestIdentity !== undefined ? { subject: ctx.requestIdentity } : {}),
});
} catch (err) {
// Write-side trust (Task 12): a permissions document rule denied
// the schema batch. Named code, the rule that decided, and the
// operator exit - never an internal error a caller would retry
// into the same wall.
if (err instanceof WriteRefusedError) {
throw new MCPError(INVALID_PARAMS, `schema_apply_mutations: ${err.message}`, {
code: err.code,
rule: err.rule,
agent: err.agent,
next_command: err.nextCommand,
});
}
throw err;
}
},
},
];