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
8.3 KB
Raw Blame
/**
 * Per-type attribute fields (write-time-integrity-governance).
 *
 * The schema pack's `attributes` field declares, per page type, a
 * small set of fields with natural-language descriptions. The
 * descriptions are agent guidance, not extraction magic: they render
 * in schema explain output so an agent capturing a typed page knows
 * the domain vocabulary, and validation is fail-closed - assigning an
 * undeclared field lists the declared fields WITH their descriptions
 * so the caller can self-correct. Values persist as a sorted
 * `attributes: [field=value]` frontmatter array, filterable through
 * the existing `--property` post-rank search filter. The regex fact
 * extractor is unchanged.
 */

import { parseFrontmatter, writeFrontmatterAtomic } from "../vault.ts";
import { resolveNotePath } from "./note-path.ts";
import { governCallerNamedWritePath } from "../write-binding/index.ts";
import { assertStandingRulesNotTargeted } from "./standing-rules.ts";
import { normalizeSchemaToken } from "./schema-vocab.ts";
import type { SchemaPack } from "./schema-pack.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";

/**
 * Surfaces for the caller-named governance refusal. The CLI `brain attr`
 * verb and marker write-back both reach the file through
 * `resolveNotePath`, so the operator's standing rules, the write
 * binding's own config, and the declared write binding are enforced at
 * the shared seam rather than inherited from the note-target envelope.
 */
const ATTR_ASSIGN_SURFACE = "attribute assignment";
const ATTR_REMOVE_SURFACE = "attribute removal";

export class AttributeVocabularyError extends Error {
  readonly type: string;
  readonly declared: Readonly<Record<string, string>>;

  constructor(type: string, declared: Readonly<Record<string, string>>, message: string) {
    super(message);
    this.name = "AttributeVocabularyError";
    this.type = type;
    this.declared = declared;
  }
}

export interface AttributeAssignment {
  readonly type: string;
  readonly field: string;
  readonly value: string;
}

export interface AssignNoteAttributeOptions {
  readonly field: string;
  readonly value: string;
  readonly pack: SchemaPack;
}

export interface RemoveNoteAttributeOptions {
  readonly field: string;
}

export interface NoteAttributeResult {
  /** Vault-relative path of the note. */
  readonly path: string;
  /** The note's full `field=value` set after the operation, sorted. */
  readonly attributes: ReadonlyArray<string>;
  /** Whether the file content changed. */
  readonly changed: boolean;
}

export interface RemoveNoteAttributeResult extends NoteAttributeResult {
  /** Whether the field was present before removal. */
  readonly removed: boolean;
}

/**
 * Validate one assignment against the declared descriptors.
 * Fail-closed both ways: a type with no declared attributes names the
 * types that have them; an undeclared field lists the declared fields
 * with their descriptions - the descriptions ARE the guidance.
 */
export function validateAttributeAssignment(
  pack: SchemaPack,
  type: string,
  field: string,
  value: string,
): AttributeAssignment {
  const normalizedType = normalizeSchemaToken(type);
  const declared = pack.attributes[normalizedType];
  if (declared === undefined) {
    const types = Object.keys(pack.attributes);
    throw new AttributeVocabularyError(
      normalizedType,
      {},
      types.length === 0
        ? "no attribute fields are declared in the schema pack"
        : `type "${normalizedType}" declares no attributes - declared attribute types: ${types.join(", ")}`,
    );
  }
  const normalizedField = normalizeSchemaToken(field);
  if (declared[normalizedField] === undefined) {
    const fields = Object.entries(declared)
      .map(([name, description]) => `${name} (${description})`)
      .join(", ");
    throw new AttributeVocabularyError(
      normalizedType,
      declared,
      `attribute "${normalizedField}" is not declared for type "${normalizedType}" - declared fields: ${fields}`,
    );
  }
  const trimmed = value.trim();
  if (trimmed.length === 0) {
    throw new AttributeVocabularyError(
      normalizedType,
      declared,
      "attribute value must not be empty",
    );
  }
  if (/[\r\n]/.test(value)) {
    throw new AttributeVocabularyError(
      normalizedType,
      declared,
      "attribute value must be a single line",
    );
  }
  if (trimmed.includes(",")) {
    throw new AttributeVocabularyError(
      normalizedType,
      declared,
      "attribute value must not contain a comma (it breaks the inline frontmatter array)",
    );
  }
  return { type: normalizedType, field: normalizedField, value: trimmed };
}

/**
 * Assign one attribute to a typed note. The note's own frontmatter
 * `type` selects the descriptor set; validation runs before any write
 * so an invalid assignment never touches the file. One value per
 * field - reassignment replaces.
 */
export function assignNoteAttribute(
  vault: string,
  relPath: string,
  opts: AssignNoteAttributeOptions,
): NoteAttributeResult {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertVaultIdentityForWrite(vault);
  // The note-target envelope's walls, applied at this seam because the
  // file is reached through the weaker `resolveNotePath`: the operator's
  // standing rules and the write binding's own config are refused by
  // name, the declared write binding is enforced. Run before the type
  // read so a refused target performs no I/O at all.
  assertStandingRulesNotTargeted(vault, relPath, ATTR_ASSIGN_SURFACE);
  governCallerNamedWritePath(vault, relPath, ATTR_ASSIGN_SURFACE);
  const path = resolveNotePath(vault, relPath);
  const [metadata, body] = parseFrontmatter(path);
  const rawType = metadata["type"];
  if (typeof rawType !== "string" || normalizeSchemaToken(rawType).length === 0) {
    throw new Error(`note declares no type in frontmatter: ${relPath}`);
  }
  const assignment = validateAttributeAssignment(opts.pack, rawType, opts.field, opts.value);
  const existing = readAttributeEntries(metadata);
  const kept = existing.filter((entry) => !entry.startsWith(`${assignment.field}=`));
  const next = [...kept, `${assignment.field}=${assignment.value}`].toSorted((a, b) =>
    a.localeCompare(b),
  );
  const changed = !sameEntries(existing, next);
  if (changed) {
    writeFrontmatterAtomic(path, { ...metadata, attributes: next }, body, { overwrite: true });
  }
  return { path: relPath, attributes: next, changed };
}

/** Remove a field's attribute from a note. */
export function removeNoteAttribute(
  vault: string,
  relPath: string,
  opts: RemoveNoteAttributeOptions,
): RemoveNoteAttributeResult {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertVaultIdentityForWrite(vault);
  // Removal rewrites the same frontmatter with the same overwrite, so it
  // is the same write and takes the same refusals.
  assertStandingRulesNotTargeted(vault, relPath, ATTR_REMOVE_SURFACE);
  governCallerNamedWritePath(vault, relPath, ATTR_REMOVE_SURFACE);
  const field = normalizeSchemaToken(opts.field);
  const path = resolveNotePath(vault, relPath);
  const [metadata, body] = parseFrontmatter(path);
  const existing = readAttributeEntries(metadata);
  const next = existing.filter((entry) => !entry.startsWith(`${field}=`));
  const removed = next.length !== existing.length;
  if (removed) {
    const nextMetadata = { ...metadata };
    if (next.length > 0) nextMetadata["attributes"] = next;
    else delete nextMetadata["attributes"];
    writeFrontmatterAtomic(path, nextMetadata, body, { overwrite: true });
  }
  return { path: relPath, attributes: next, changed: removed, removed };
}

/** Parse a note's `attributes` array into a `field -> value` record. */
export function readAttributes(metadata: Record<string, unknown>): Record<string, string> {
  const out: Record<string, string> = {};
  for (const entry of readAttributeEntries(metadata)) {
    const eq = entry.indexOf("=");
    if (eq <= 0) continue;
    out[entry.slice(0, eq)] = entry.slice(eq + 1);
  }
  return out;
}

function readAttributeEntries(metadata: Record<string, unknown>): string[] {
  const raw = metadata["attributes"];
  if (!Array.isArray(raw)) return [];
  return raw.filter((entry): entry is string => typeof entry === "string");
}

function sameEntries(left: ReadonlyArray<string>, right: ReadonlyArray<string>): boolean {
  return left.length === right.length && left.every((entry, index) => entry === right[index]);
}