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
10.7 KB
Raw Blame
/**
 * Persisted claim-graph projection (Belief lifecycle suite, A3,
 * t_6916369f).
 *
 * A bounded, deterministically-rebuildable JSON projection over the
 * relations already present in Brain memory frontmatter - `superseded_by`
 * (supersession chains), `contradicts` (contested claims), the
 * bi-temporal `valid_from` / `valid_until` fields, and `provenance`. It
 * is a VIEW, not a store of record: nothing here writes memory files or
 * touches any extractor. Rebuild reads the current vault and overwrites
 * the artifact.
 *
 * One query surface answers four questions:
 *   - "current truth"        -> {@link currentTruth}
 *   - "true at instant T"    -> {@link truthAt}
 *   - "what replaced X"      -> {@link whatReplaced}
 *   - "what contests X"      -> {@link whatContests}
 * Current-truth is the default; history / retracted content is opt-in via
 * {@link allClaims}.
 *
 * Import direction (design invariant): imports from `types.ts`, the
 * shared vault/path helpers, and the sibling lifecycle modules
 * (`tombstone.ts` chain conventions, `temporal-replace.ts` validity
 * evaluation), never the reverse.
 */

import { existsSync, readFileSync, readdirSync } from "node:fs";
import { join, relative } from "node:path";

import type { FrontmatterMap } from "../types.ts";
import { atomicWriteFileSync } from "../fs-atomic.ts";
import { parseFrontmatter } from "../vault.ts";
import { brainDirs, claimGraphPath } from "./paths.ts";
import { isTombstoned, normalizeChainLink, resolveChainTip } from "./lifecycle/tombstone-read.ts";
import { isValidAt } from "./lifecycle/temporal-replace.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";

// ----- Constants ------------------------------------------------------------

/**
 * Hard cap on projected nodes. The projection is a bounded artifact by
 * design: a runaway vault cannot produce an unbounded JSON file. Nodes
 * are sorted by path before truncation so the retained set is
 * deterministic.
 */
export const CLAIM_GRAPH_MAX_NODES = 5000;

/** Current on-disk schema version of the projection artifact. */
export const CLAIM_GRAPH_VERSION = 1;

/** Brain memory subdirectories the projection scans (relative to `Brain/`). */
const SCANNED_SUBDIRS = [
  "preferences",
  "retired",
  "inbox",
  "inbox/processed",
  "inbox/archived",
  "theses",
] as const;

// ----- Errors ---------------------------------------------------------------

export class ClaimGraphError extends Error {
  constructor(message: string, options?: ErrorOptions) {
    super(message, options);
    this.name = "ClaimGraphError";
  }
}

// ----- Types ----------------------------------------------------------------

export interface ClaimNode {
  /** Bare basename id (e.g. `pref-foo`). */
  readonly id: string;
  /** Vault-relative POSIX path. */
  readonly path: string;
  readonly topic: string;
  readonly principle: string;
  readonly valid_from: string | null;
  readonly valid_until: string | null;
  /** Normalized successor id, or `null` when this node is a chain tip. */
  readonly superseded_by: string | null;
  /** Normalized ids this node declares it contradicts. */
  readonly contradicts: ReadonlyArray<string>;
  readonly provenance: string | null;
  readonly tombstoned: boolean;
}

export interface ClaimGraph {
  readonly version: number;
  readonly generated_at: string;
  readonly node_count: number;
  /** True when the node cap dropped claims from the projection. */
  readonly truncated: boolean;
  readonly nodes: ReadonlyArray<ClaimNode>;
}

export interface BuildClaimGraphOptions {
  /** Override the node cap (defaults to {@link CLAIM_GRAPH_MAX_NODES}). */
  readonly maxNodes?: number;
  /** Wall clock for `generated_at`. Defaults to `new Date()`. */
  readonly now?: Date;
}

// ----- Field extraction -----------------------------------------------------

function scalar(meta: FrontmatterMap, key: string): string | null {
  const value = meta[key];
  return typeof value === "string" && value !== "" ? value : null;
}

function normalizedList(meta: FrontmatterMap, key: string): string[] {
  const value = meta[key];
  const raw =
    typeof value === "string" && value !== ""
      ? [value]
      : Array.isArray(value)
        ? (value as ReadonlyArray<string>)
        : [];
  const out: string[] = [];
  for (const item of raw) {
    if (typeof item !== "string" || item.trim() === "") continue;
    out.push(normalizeChainLink(item));
  }
  return out.toSorted();
}

function toNode(vault: string, absPath: string): ClaimNode | null {
  // Unit F: `parseFrontmatter` cannot throw (it reads inside its own try;
  // everything after is string work), so the `catch { return null }` that
  // stood here was unreachable - and redundant, because a failed read
  // yields an empty map and the very next line already returns null for
  // it. Dropped lines are reported centrally; see the "Why most readers
  // keep the two-tuple form" section in src/core/vault.ts. A claim node
  // is a graph vertex with no report field, so it opens no channel here.
  const [meta] = parseFrontmatter(absPath);
  if (Object.keys(meta).length === 0) return null;
  const rel = relative(vault, absPath).split("\\").join("/");
  const id = normalizeChainLink(absPath);
  const superseded = scalar(meta, "superseded_by");
  return {
    id,
    path: rel,
    topic: scalar(meta, "topic") ?? "",
    principle: scalar(meta, "principle") ?? "",
    valid_from: scalar(meta, "valid_from"),
    valid_until: scalar(meta, "valid_until"),
    superseded_by: superseded === null ? null : normalizeChainLink(superseded),
    contradicts: normalizedList(meta, "contradicts"),
    provenance: scalar(meta, "provenance"),
    tombstoned: isTombstoned(meta),
  };
}

function collectMarkdown(dir: string, out: string[]): void {
  let entries;
  try {
    entries = readdirSync(dir, { withFileTypes: true });
  } catch {
    return;
  }
  for (const entry of entries) {
    if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".md")) continue;
    out.push(join(dir, entry.name));
  }
}

// ----- Build / persist ------------------------------------------------------

/**
 * Build the claim-graph projection from the current vault. Deterministic:
 * nodes are sorted by vault-relative path, and truncation (when the node
 * cap is exceeded) keeps the lexicographically-first `maxNodes`.
 */
export function buildClaimGraph(vault: string, opts: BuildClaimGraphOptions = {}): ClaimGraph {
  const maxNodes = opts.maxNodes ?? CLAIM_GRAPH_MAX_NODES;
  if (!Number.isInteger(maxNodes) || maxNodes <= 0) {
    throw new ClaimGraphError(
      `buildClaimGraph: maxNodes must be a positive integer; got ${maxNodes}`,
    );
  }
  const brain = brainDirs(vault).brain;
  const files: string[] = [];
  for (const sub of SCANNED_SUBDIRS) collectMarkdown(join(brain, sub), files);

  const nodes: ClaimNode[] = [];
  for (const file of files) {
    const node = toNode(vault, file);
    if (node !== null) nodes.push(node);
  }
  nodes.sort((a, b) => a.path.localeCompare(b.path));

  const truncated = nodes.length > maxNodes;
  const kept = truncated ? nodes.slice(0, maxNodes) : nodes;
  return {
    version: CLAIM_GRAPH_VERSION,
    generated_at: (opts.now ?? new Date()).toISOString(),
    node_count: kept.length,
    truncated,
    nodes: kept,
  };
}

/** Persist a projection to `Brain/claim-graph.json`. */
export function writeClaimGraph(vault: string, graph: ClaimGraph): void {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertVaultIdentityForWrite(vault);
  atomicWriteFileSync(claimGraphPath(vault), `${JSON.stringify(graph, null, 2)}\n`);
}

/** Build the projection and persist it in one step. */
export function rebuildClaimGraph(vault: string, opts: BuildClaimGraphOptions = {}): ClaimGraph {
  const graph = buildClaimGraph(vault, opts);
  writeClaimGraph(vault, graph);
  return graph;
}

/** Load the persisted projection, or `null` when none has been built. */
export function loadClaimGraph(vault: string): ClaimGraph | null {
  const path = claimGraphPath(vault);
  if (!existsSync(path)) return null;
  let parsed: unknown;
  try {
    parsed = JSON.parse(readFileSync(path, "utf8"));
  } catch (err) {
    throw new ClaimGraphError(
      `loadClaimGraph: corrupt projection at ${path}: ${(err as Error).message}`,
      {
        cause: err,
      },
    );
  }
  if (
    parsed === null ||
    typeof parsed !== "object" ||
    !Array.isArray((parsed as ClaimGraph).nodes)
  ) {
    throw new ClaimGraphError(`loadClaimGraph: projection at ${path} is not a claim graph`);
  }
  return parsed as ClaimGraph;
}

// ----- Queries --------------------------------------------------------------

/**
 * Claims true at `probeMs` under half-open validity. Tombstoned claims
 * (wrong beliefs) never count as truth; a temporally-superseded
 * predecessor is not tombstoned and remains the truth for its own valid
 * window, so a past probe returns it and a present probe returns the
 * successor. Sorted by path.
 */
export function truthAt(graph: ClaimGraph, probeMs: number): ClaimNode[] {
  return graph.nodes.filter((n) => !n.tombstoned && isValidAt(n, probeMs));
}

/** Claims true right now (the default view). */
export function currentTruth(graph: ClaimGraph, now: Date = new Date()): ClaimNode[] {
  return truthAt(graph, now.getTime());
}

/** Every claim in the projection, including tombstoned ones (history / audit). */
export function allClaims(graph: ClaimGraph): ClaimNode[] {
  return [...graph.nodes];
}

/**
 * Resolve the claim that ultimately replaced `id` by walking the
 * `superseded_by` chain to its live tip. Returns the tip node, or `null`
 * when `id` is unknown or the chain tip is not in the projection.
 */
export function whatReplaced(graph: ClaimGraph, id: string): ClaimNode | null {
  const byId = new Map(graph.nodes.map((n) => [n.id, n] as const));
  const start = normalizeChainLink(id);
  if (!byId.has(start)) return null;
  const res = resolveChainTip(start, (link) => {
    const node = byId.get(link);
    return node ? { supersededBy: node.superseded_by } : null;
  });
  return byId.get(res.tip) ?? null;
}

/**
 * Claims that contest `id`: either those the target declares it
 * contradicts, or those that declare they contradict the target
 * (contradiction is treated as a symmetric contest). Sorted by path.
 */
export function whatContests(graph: ClaimGraph, id: string): ClaimNode[] {
  const target = normalizeChainLink(id);
  const out: ClaimNode[] = [];
  const seen = new Set<string>();
  const targetNode = graph.nodes.find((n) => n.id === target) ?? null;
  const declaredByTarget = new Set(targetNode?.contradicts ?? []);
  for (const node of graph.nodes) {
    if (node.id === target) continue;
    const contestsTarget = node.contradicts.includes(target) || declaredByTarget.has(node.id);
    if (contestsTarget && !seen.has(node.id)) {
      seen.add(node.id);
      out.push(node);
    }
  }
  return out;
}