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
/**
* A minimal JSON Schema validator for the published `schemas/brain/*.schema.json`
* contracts - exactly the keyword subset those files use, and no more.
*
* It began life as `src/core/brain/schema-contracts.ts`, a hand-written TS
* mirror of the published schemas with no production consumer. The mirror
* could drift from the published files without anything noticing (and had:
* it declared `format: date-time` on fields the published schemas leave as
* plain strings). What survives is the validator alone, now pointed at the
* published files themselves, so a contract test checks the real generator
* output against the real contract.
*
* An unsupported keyword is an error, not a silent pass: a schema that grows
* a keyword this subset does not check must fail the contract test until the
* validator learns it, or the test would claim a guarantee it does not give.
*/
export type SchemaType = "object" | "array" | "string" | "integer" | "number" | "boolean";
export interface SchemaNode {
readonly $schema?: string;
readonly $id?: string;
readonly $defs?: Readonly<Record<string, SchemaNode>>;
readonly type?: SchemaType;
readonly title?: string;
readonly description?: string;
readonly format?: "date-time";
readonly minimum?: number;
readonly maximum?: number;
readonly minLength?: number;
readonly maxLength?: number;
readonly maxItems?: number;
readonly enum?: ReadonlyArray<unknown>;
readonly required?: ReadonlyArray<string>;
readonly properties?: Readonly<Record<string, SchemaNode>>;
readonly items?: SchemaNode;
/**
* The boolean form excludes unknown keys; the SCHEMA form validates each
* unknown key against it (the search-query artifact's `properties` row
* types its filter map this way).
*/
readonly additionalProperties?: boolean | SchemaNode;
}
export interface SchemaValidationResult {
readonly ok: boolean;
readonly errors: ReadonlyArray<string>;
}
const SUPPORTED_KEYWORDS: ReadonlySet<string> = new Set([
"$schema",
"$id",
"$defs",
"type",
"title",
"description",
"format",
"minimum",
"maximum",
"minLength",
"maxLength",
"maxItems",
"enum",
"required",
"properties",
"items",
"additionalProperties",
]);
const SUPPORTED_TYPES: ReadonlySet<string> = new Set([
"object",
"array",
"string",
"integer",
"number",
"boolean",
]);
/**
* Throws when `schema` uses a keyword, type, or format this validator does
* not implement. Run it over every published schema before trusting a
* validation result.
*/
export function assertSupportedSchema(schema: unknown, path = ""): void {
if (!isRecord(schema)) throw new Error(`${formatPath(path)}: schema node must be an object`);
for (const key of Object.keys(schema)) {
if (!SUPPORTED_KEYWORDS.has(key)) {
throw new Error(`${formatPath(path)}: unsupported schema keyword ${JSON.stringify(key)}`);
}
}
const type = schema["type"];
if (type !== undefined && (typeof type !== "string" || !SUPPORTED_TYPES.has(type))) {
throw new Error(`${formatPath(path)}: unsupported type ${JSON.stringify(type)}`);
}
const format = schema["format"];
if (format !== undefined && format !== "date-time") {
throw new Error(`${formatPath(path)}: unsupported format ${JSON.stringify(format)}`);
}
const additional = schema["additionalProperties"];
if (additional !== undefined && typeof additional !== "boolean") {
// The schema form is checked recursively below, like properties.
if (!isRecord(additional)) {
throw new Error(`${formatPath(path)}: additionalProperties must be a boolean or a schema`);
}
}
const properties = schema["properties"];
if (properties !== undefined) {
if (!isRecord(properties)) throw new Error(`${formatPath(path)}: properties must be an object`);
for (const [key, child] of Object.entries(properties)) {
assertSupportedSchema(child, appendPath(path, key));
}
}
if (schema["$defs"] !== undefined) {
const defs = schema["$defs"];
if (!isRecord(defs)) throw new Error(`${formatPath(path)}: $defs must be an object`);
for (const [name, child] of Object.entries(defs)) {
assertSupportedSchema(child, appendPath(path, name));
}
}
if (schema["items"] !== undefined) assertSupportedSchema(schema["items"], `${path}[]`);
if (additional !== undefined && typeof additional !== "boolean") {
assertSupportedSchema(additional, appendPath(path, "(additionalProperties)"));
}
}
export function validateAgainstSchema(schema: SchemaNode, value: unknown): SchemaValidationResult {
const errors: string[] = [];
validateNode(schema, value, "", errors);
return Object.freeze({ ok: errors.length === 0, errors: Object.freeze(errors) });
}
function validateNode(schema: SchemaNode, value: unknown, path: string, errors: string[]): void {
if (schema.type !== undefined && !matchesType(schema.type, value)) {
errors.push(`${formatPath(path)} must be ${schema.type}`);
return;
}
if (schema.enum !== undefined && !schema.enum.some((allowed) => Object.is(allowed, value))) {
errors.push(
`${formatPath(path)} must be one of ${schema.enum.map((v) => JSON.stringify(v)).join(", ")}`,
);
return;
}
if (schema.format === "date-time" && typeof value === "string") {
if (!Number.isFinite(Date.parse(value))) errors.push(`${formatPath(path)} must be date-time`);
}
if (typeof value === "string") {
if (schema.minLength !== undefined && value.length < schema.minLength) {
errors.push(`${formatPath(path)} must be at least ${schema.minLength} character(s)`);
}
if (schema.maxLength !== undefined && value.length > schema.maxLength) {
errors.push(`${formatPath(path)} must be at most ${schema.maxLength} character(s)`);
}
}
if (typeof value === "number") {
if (schema.minimum !== undefined && value < schema.minimum) {
errors.push(`${formatPath(path)} must be >= ${schema.minimum}`);
}
if (schema.maximum !== undefined && value > schema.maximum) {
errors.push(`${formatPath(path)} must be <= ${schema.maximum}`);
}
}
if (Array.isArray(value) && schema.maxItems !== undefined && value.length > schema.maxItems) {
errors.push(`${formatPath(path)} must have at most ${schema.maxItems} item(s)`);
}
if (schema.type === "object" && isRecord(value)) {
const properties = schema.properties ?? {};
for (const key of schema.required ?? []) {
if (!(key in value)) errors.push(`${formatPath(appendPath(path, key))} is required`);
}
for (const [key, child] of Object.entries(value)) {
const childSchema = properties[key];
if (childSchema === undefined) {
if (schema.additionalProperties === false) {
errors.push(`${formatPath(appendPath(path, key))} is not allowed`);
} else if (typeof schema.additionalProperties === "object") {
validateNode(schema.additionalProperties, child, appendPath(path, key), errors);
}
continue;
}
validateNode(childSchema, child, appendPath(path, key), errors);
}
}
if (schema.type === "array" && Array.isArray(value) && schema.items !== undefined) {
for (let index = 0; index < value.length; index++) {
validateNode(schema.items, value[index], `${path}[${index}]`, errors);
}
}
}
function matchesType(type: SchemaType, value: unknown): boolean {
switch (type) {
case "object":
return isRecord(value);
case "array":
return Array.isArray(value);
case "string":
return typeof value === "string";
case "integer":
return typeof value === "number" && Number.isInteger(value);
case "number":
return typeof value === "number" && Number.isFinite(value);
case "boolean":
return typeof value === "boolean";
}
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
function appendPath(path: string, key: string): string {
return path.length === 0 ? key : `${path}.${key}`;
}
function formatPath(path: string): string {
return path.length === 0 ? "<root>" : path;
}