Skip to content

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
4.6 KB
Raw Blame
import { BRAIN_LOG_EVENT_KIND } from "./types.ts";

export const SCHEMA_VOCAB_CATEGORIES = Object.freeze([
  "preference_types",
  "signal_types",
  "page_types",
  "log_event_kinds",
] as const);

export type SchemaVocabularyCategory = (typeof SCHEMA_VOCAB_CATEGORIES)[number];

export interface BrainSchemaDeclarations {
  readonly preference_types?: ReadonlyArray<string>;
  readonly signal_types?: ReadonlyArray<string>;
  readonly page_types?: ReadonlyArray<string>;
  readonly log_event_kinds?: ReadonlyArray<string>;
}

export interface BrainSchemaVocabulary {
  readonly preference_types: ReadonlyArray<string>;
  readonly signal_types: ReadonlyArray<string>;
  readonly page_types: ReadonlyArray<string>;
  readonly log_event_kinds: ReadonlyArray<string>;
}

export class SchemaVocabularyError extends Error {
  readonly field: string;
  readonly token: unknown;

  constructor(field: string, token: unknown, message: string) {
    super(`${field}: ${message}`);
    this.name = "SchemaVocabularyError";
    this.field = field;
    this.token = token;
  }
}

const TOKEN_RE = /^[\p{L}][\p{L}\p{N}_-]*$/u;

export const DEFAULT_SCHEMA_VOCAB: BrainSchemaVocabulary = Object.freeze({
  preference_types: Object.freeze(["preference"]),
  signal_types: Object.freeze(["feedback"]),
  page_types: Object.freeze(["note"]),
  log_event_kinds: Object.freeze(Object.values(BRAIN_LOG_EVENT_KIND)),
});

export function normalizeSchemaToken(raw: string): string {
  return raw.normalize("NFC").trim().toLowerCase();
}

/**
 * The two halves of a compound `type.field` key (the `attributes` and
 * `frontmatter_tiers` entries), split at its first `.`, or `null` when
 * either half would be empty. `rawKey` is the trimmed text before the
 * entry's `=`; the halves are not normalised. The pack parser and the
 * store's per-entry fold of those lists both split here, so they agree on
 * which entries name one key.
 */
export function splitCompoundSchemaKey(rawKey: string): readonly [string, string] | null {
  const dot = rawKey.indexOf(".");
  if (dot <= 0 || dot === rawKey.length - 1) return null;
  return [rawKey.slice(0, dot), rawKey.slice(dot + 1)];
}

export function validateSchemaDeclarations(
  declarations: BrainSchemaDeclarations | undefined | null,
): BrainSchemaDeclarations {
  if (declarations == null) return Object.freeze({});

  const normalized: Partial<Record<SchemaVocabularyCategory, ReadonlyArray<string>>> = {};
  for (const category of SCHEMA_VOCAB_CATEGORIES) {
    const values = declarations[category];
    if (values === undefined) continue;
    if (!Array.isArray(values)) {
      throw new SchemaVocabularyError(`schema.${category}`, values, "must be an array of tokens");
    }
    normalized[category] = Object.freeze(
      values.map((value, index) => validateSchemaToken(value, `schema.${category}[${index}]`)),
    );
  }

  return Object.freeze(normalized) as BrainSchemaDeclarations;
}

export function resolveSchemaVocabulary(
  declarations: BrainSchemaDeclarations | undefined | null = undefined,
): BrainSchemaVocabulary {
  const normalized = validateSchemaDeclarations(declarations);

  return Object.freeze({
    preference_types: mergeCategory(
      DEFAULT_SCHEMA_VOCAB.preference_types,
      normalized.preference_types,
    ),
    signal_types: mergeCategory(DEFAULT_SCHEMA_VOCAB.signal_types, normalized.signal_types),
    page_types: mergeCategory(DEFAULT_SCHEMA_VOCAB.page_types, normalized.page_types),
    log_event_kinds: mergeCategory(
      DEFAULT_SCHEMA_VOCAB.log_event_kinds,
      normalized.log_event_kinds,
    ),
  });
}

export function isKnownSchemaToken(
  vocab: BrainSchemaVocabulary,
  category: SchemaVocabularyCategory,
  token: string,
): boolean {
  const normalized = normalizeSchemaToken(token);
  return vocab[category].includes(normalized);
}

function mergeCategory(
  builtins: ReadonlyArray<string>,
  declared: ReadonlyArray<string> | undefined,
): ReadonlyArray<string> {
  const seen = new Set<string>();
  const merged: string[] = [];
  for (const token of [...builtins, ...(declared ?? [])]) {
    const normalized = normalizeSchemaToken(token);
    if (seen.has(normalized)) continue;
    seen.add(normalized);
    merged.push(normalized);
  }
  return Object.freeze(merged);
}

export function validateSchemaToken(value: unknown, field: string): string {
  if (typeof value !== "string") {
    throw new SchemaVocabularyError(field, value, "must be a string token");
  }
  const normalized = normalizeSchemaToken(value);
  if (!TOKEN_RE.test(normalized)) {
    throw new SchemaVocabularyError(
      field,
      value,
      "must start with a letter and contain only letters, numbers, underscores, or hyphens",
    );
  }
  return normalized;
}