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
5.5 KB
Raw Blame
import { requireObsidianTagValue } from "./tag-syntax.ts";

export interface RenderMemoryInput {
  readonly name: string;
  readonly description: string;
  readonly body: string;
  readonly memoryPath: string;
  readonly importedAt: string; // ISO Z
  /**
   * The trial deadline the imported rule lands under (ISO Z). The
   * orchestrator derives it from the vault's
   * `dream.unconfirmed_window_days`, so the renderer stays a pure
   * function of its input.
   */
  readonly unconfirmedUntil: string;
  readonly bodySha256: string;
  /** Owner token for the rendered page; omitted renders no `owner:`. */
  readonly owner?: string | undefined;
  /**
   * First line of the rendered Origin section. Defaults to the Claude
   * Code MEMORY label, byte-identical to the pre-field output; a caller
   * that renders from a different substrate (the continuity ledger's
   * host-memory promotion) passes its own so the page never claims a
   * source it did not come from.
   */
  readonly originLabel?: string;
  /**
   * The name the page's IDENTITY derives from (the `id:` frontmatter and
   * the `topic` tag, both slugified). Defaults to `name`, byte-identical
   * to the import, where the display name and the identity are the same
   * string. A caller whose target filename is keyed by something other
   * than the display name - the continuity ledger's host-memory
   * promotion, whose pages are named after the record id so the target
   * never moves - passes its stable identity here and keeps its display
   * text in `name`; a mismatched `id:` and basename would otherwise send
   * every id-keyed lookup (evidence appends, confirmation) to a page
   * that does not exist.
   */
  readonly identityName?: string;
}

/**
 * Slugify a Claude Memory `name` field for use as a Brain preference id.
 * Single source of truth: both the orchestrator and the renderer must
 * produce byte-identical slugs from the same input. Steps:
 *   - underscores → dashes
 *   - non-alphanumeric → dash
 *   - lowercase
 *   - collapse runs of dashes → single dash
 *   - trim leading/trailing dashes
 *
 * The collapse step keeps human-typable ids like `pref-no-em-dashes`
 * instead of `pref-no---em-dashes` when the source name contains
 * punctuation or whitespace.
 */
export function slugifyMemoryName(name: string): string {
  return name
    .replace(/_/g, "-")
    .replace(/[^a-z0-9-]/gi, "-")
    .toLowerCase()
    .replace(/-{2,}/g, "-")
    .replace(/^-+|-+$/g, "");
}

const SCOPE_RE = /^scope:\s*([a-z][a-z0-9-]*)\s*$/m;

function extractScope(body: string): string {
  const m = body.match(SCOPE_RE);
  return m?.[1] ?? "writing";
}

function isoDay(iso: string): string {
  return iso.slice(0, 10);
}

export function renderPreferenceFromMemory(input: RenderMemoryInput): string {
  const slug = slugifyMemoryName(input.identityName ?? input.name);
  if (!slug) {
    // Punctuation-only / whitespace-only names produce an empty slug,
    // which would yield the bare `pref-` id and a blank `topic:` field.
    // Fail fast so the caller (orchestrator → CLI) surfaces a clear error
    // rather than writing an ambiguous preference file.
    throw new Error(
      `claude-memory: cannot derive a slug from name ${JSON.stringify(input.name)}; rename the memory entry to include at least one alphanumeric character`,
    );
  }
  // The derived topic/scope are validated against the one shared tag rule
  // (t_11ee559f). Both are slugified by construction, so this is a pin -
  // except a purely numeric name, whose slug still fails the rule and
  // refuses here with the field named rather than landing an unparseable
  // frontmatter tag. The import loop treats that refusal as a per-entry
  // disposition - a named skip row, import continues - so one legacy
  // MEMORY file cannot abort the whole run.
  const prefId = `pref-${slug}`;
  const topic = requireObsidianTagValue(slug, "topic");
  const scope = requireObsidianTagValue(extractScope(input.body), "scope");
  // The import lands UNDER TRIAL, not confirmed. MEMORY.md is
  // session-derived - agent-writable from conversation content - so a
  // poisoned entry must not become a live rule on landing; it gets the
  // same trial window every first-party write observes, and the dream
  // pass reviews it like any other candidate. Provenance is carried by
  // the `_imported_*` fields below; the old `_force_confirmed_via`
  // marker is gone because its claim would now be false.
  const fm = [
    "---",
    "kind: brain-preference",
    `id: ${prefId}`,
    `created_at: "${input.importedAt}"`,
    `unconfirmed_until: "${input.unconfirmedUntil}"`,
    `tags: [brain, brain/preference, brain/topic/${topic}, brain/scope/${scope}]`,
    `topic: ${topic}`,
    "_status: unconfirmed",
    `principle: ${JSON.stringify(input.description)}`,
    "_evidenced_by: []",
    "_applied_count: 0",
    "_violated_count: 0",
    "_last_evidence_at: null",
    "_confidence: low",
    "pinned: false",
    `scope: ${scope}`,
    // Ownership, on the same terms every other preference writer uses.
    // Absent when the gate is off, so a vault that never opted in keeps
    // byte-identical imports.
    ...(input.owner === undefined ? [] : [`owner: ${input.owner}`]),
    `_imported_from: ${JSON.stringify(input.memoryPath)}`,
    `_imported_sha256: ${input.bodySha256}`,
    `_imported_at: "${input.importedAt}"`,
    "---",
    "",
    input.body.trim(),
    "",
    "## Origin",
    "",
    input.originLabel ?? "Imported from Claude Code MEMORY:",
    `\`${input.memoryPath}\``,
    `on ${isoDay(input.importedAt)}.`,
    "",
  ].join("\n");
  return fm;
}