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.2 KB
Raw Blame
/**
 * Page interchange contract (Brain Portability & Interop suite, Unit B).
 *
 * `projectPageContracts` serialises every user vault page (the Brain
 * machinery root and the standard ignored dirs excluded) into a stable,
 * sorted, schema-versioned interchange record a downstream importer can
 * consume without knowing OSB internals. Each record carries the page's
 * `path`, `kind`, advisory `confidence`/`provenance`, flattened
 * `citations`, `aliases`, and `freshness`.
 *
 * Derivation is structural only - frontmatter fields, body wikilinks,
 * typed-relation targets, and the file mtime. The provider-agnostic
 * kernel never synthesises a field, and no natural-language heuristic
 * (keyword/title matching in any language) is used: an absent advisory
 * field is reported as `null`, never guessed.
 */

import { statSync } from "node:fs";
import { posix, relative } from "node:path";

import { EXCLUDED_DIRS, extractWikilinks, listVaultPages, parseFrontmatter } from "../../vault.ts";
import type { FrontmatterMap, FrontmatterValue } from "../../types.ts";
import {
  extractFrontmatterRelations,
  normalizeRelationTarget,
} from "../../graph/frontmatter-relations.ts";
import { BRAIN_ROOT_REL } from "../paths.ts";
import { isoSecond } from "../time.ts";
import { MAINTENANCE_LANE_REACH } from "../../graph/transport-reach.ts";

export const PAGE_CONTRACT_VERSION = "1";

/** Structural default `kind` for a page with no frontmatter `kind:` field. */
export const DEFAULT_PAGE_KIND = "note";

export interface PageContract {
  /** Vault-relative POSIX path. */
  readonly path: string;
  /** Frontmatter `kind:` when present, else the structural default. */
  readonly kind: string;
  /** Advisory: frontmatter `confidence` (number or string) when present. */
  readonly confidence: number | string | null;
  /** Advisory: frontmatter `provenance` string when present. */
  readonly provenance: string | null;
  /** Sorted-unique body wikilink + typed-relation targets. */
  readonly citations: ReadonlyArray<string>;
  /** Frontmatter `aliases`, else empty. */
  readonly aliases: ReadonlyArray<string>;
  /** Frontmatter `updated_at`/`updated` else the file mtime (ISO second). */
  readonly freshness: string | null;
}

/** Frontmatter timestamp fields, in precedence order, for `freshness`. */
const FRESHNESS_FIELDS = ["updated_at", "updated"] as const;

function stringField(meta: FrontmatterMap, key: string): string | null {
  const value: FrontmatterValue | undefined = meta[key];
  return typeof value === "string" && value.length > 0 ? value : null;
}

function confidenceField(meta: FrontmatterMap): number | string | null {
  const value: FrontmatterValue | undefined = meta["confidence"];
  if (typeof value === "number") return value;
  if (typeof value === "string" && value.length > 0) return value;
  return null;
}

function aliasField(meta: FrontmatterMap): ReadonlyArray<string> {
  const value: FrontmatterValue | undefined = meta["aliases"];
  if (!Array.isArray(value)) return [];
  return value.filter((item): item is string => typeof item === "string");
}

function sortedUnique(values: Iterable<string>): string[] {
  return [...new Set([...values].filter((v) => v.length > 0))].toSorted();
}

/**
 * Collect a page's citations: every body wikilink plus every typed
 * relation target, normalised, de-duplicated, and sorted. Reuses the
 * same extraction the graph exporter uses so the contract stays
 * decoupled from any natural-language parsing.
 */
function collectCitations(meta: FrontmatterMap, body: string): string[] {
  const targets: string[] = [];
  for (const raw of extractWikilinks(body)) {
    const norm = normalizeRelationTarget(raw);
    if (norm !== null) targets.push(norm);
  }
  for (const edge of extractFrontmatterRelations(meta)) targets.push(edge.target);
  return sortedUnique(targets);
}

function freshnessOf(meta: FrontmatterMap, absPath: string): string | null {
  for (const field of FRESHNESS_FIELDS) {
    const stamp = stringField(meta, field);
    if (stamp !== null) return stamp;
  }
  try {
    return isoSecond(statSync(absPath).mtime);
  } catch {
    // A page that listed but cannot be stat'd has no derivable freshness;
    // report null rather than fabricating a timestamp.
    return null;
  }
}

/**
 * Project every user vault page to a {@link PageContract}, sorted by
 * `path` for deterministic output. Pure and read-only.
 */
export function projectPageContracts(vault: string): ReadonlyArray<PageContract> {
  const pages = listVaultPages(vault, {
    skipDirs: [...EXCLUDED_DIRS, BRAIN_ROOT_REL],
    reach: MAINTENANCE_LANE_REACH,
  });
  const contracts: PageContract[] = [];
  for (const page of pages) {
    let body: string;
    try {
      const [, parsedBody] = parseFrontmatter(page.path);
      body = parsedBody;
    } catch {
      continue;
    }
    const meta = page.metadata;
    contracts.push({
      path: relative(vault, page.path).split(/[\\/]/).join(posix.sep),
      kind: stringField(meta, "kind") ?? DEFAULT_PAGE_KIND,
      confidence: confidenceField(meta),
      provenance: stringField(meta, "provenance"),
      citations: collectCitations(meta, body),
      aliases: aliasField(meta),
      freshness: freshnessOf(meta, page.path),
    });
  }
  contracts.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
  return contracts;
}