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
11.5 KB
Raw Blame
import { mkdirSync, readFileSync } from "node:fs";
import { basename, dirname, join } from "node:path";

import { atomicWriteFileSync } from "../fs-atomic.ts";

import { ensureInsideVault } from "../path-safety.ts";
import {
  proceduralGraphPath,
  proceduralMemoryIndexPath,
  skillProposalAcceptedPath,
  skillProposalPendingPath,
  skillProposalRejectedPath,
} from "./paths.ts";
import type { ProceduralMemoryEntry } from "./types.ts";
import {
  assertLaneWrite,
  readLaneFile,
  lanePageExists,
  listLaneFiles,
  parseLanePage,
  lanePagesInStore,
  readLaneText,
} from "../store/lane-pages.ts";
import { BRAIN_PROCEDURAL_MEMORY_REL } from "./path-constants.ts";

export type ProceduralGraphNodeKind = "procedure" | "skill" | "runbook" | "proposal" | "entity";
export type ProceduralGraphEdgeKind =
  | "derived_from_proposal"
  | "trigger_matches"
  | "tag_matches"
  | "source_mentions"
  | "proposal_mentions";

export interface ProceduralGraphNode {
  readonly id: string;
  readonly kind: ProceduralGraphNodeKind;
  readonly title: string;
  readonly sourcePath: string | null;
  readonly metadata: Readonly<Record<string, unknown>>;
}

export interface ProceduralGraphEdge {
  readonly from: string;
  readonly to: string;
  readonly kind: ProceduralGraphEdgeKind;
}

export interface ProceduralGraphProjection {
  readonly schema_version: 1;
  readonly generated_at: string;
  readonly nodes: ReadonlyArray<ProceduralGraphNode>;
  readonly edges: ReadonlyArray<ProceduralGraphEdge>;
}

export interface ProceduralGraphBuildOptions {
  readonly now?: Date;
}

export function rebuildProceduralGraph(
  vault: string,
  opts: ProceduralGraphBuildOptions = {},
): ProceduralGraphProjection {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertLaneWrite(vault);
  const now = opts.now ?? new Date();
  const nodes: ProceduralGraphNode[] = [];
  const edges: ProceduralGraphEdge[] = [];

  const entries = readProceduralIndex(vault);
  const nodeById = new Set<string>();
  for (const entry of entries) {
    const node: ProceduralGraphNode = {
      id: entry.id,
      kind: entry.kind,
      title: entry.title,
      sourcePath: entry.sourcePath,
      metadata: {
        triggers: [...entry.triggers],
        tags: [...entry.tags],
        source: entry.source,
        version: entry.version,
      },
    };
    nodes.push(node);
    nodeById.add(node.id);

    if (entry.kind === "procedure") {
      const proposalId = detectProcedureSourceProposal(vault, entry.sourcePath);
      if (proposalId) {
        edges.push({
          from: node.id,
          to: proposalId,
          kind: "derived_from_proposal",
        });
      }
    }

    for (const trigger of entry.triggers) {
      const entityId = entityNodeId(`trigger:${trigger}`);
      ensureEntityNode(nodes, nodeById, entityId, `Trigger: ${trigger}`);
      edges.push({ from: node.id, to: entityId, kind: "trigger_matches" });
    }

    for (const tag of entry.tags) {
      const entityId = entityNodeId(`tag:${tag}`);
      ensureEntityNode(nodes, nodeById, entityId, `Tag: ${tag}`);
      edges.push({ from: node.id, to: entityId, kind: "tag_matches" });
    }

    for (const token of sourcePathTokens(entry.sourcePath)) {
      const entityId = entityNodeId(`path:${token}`);
      ensureEntityNode(nodes, nodeById, entityId, `Path: ${token}`);
      edges.push({ from: node.id, to: entityId, kind: "source_mentions" });
    }
  }

  for (const proposal of listProposals(vault)) {
    nodes.push(proposal);
    nodeById.add(proposal.id);
    for (const token of sourcePathTokens(proposal.sourcePath ?? "")) {
      const entityId = entityNodeId(`proposal-path:${token}`);
      ensureEntityNode(nodes, nodeById, entityId, `Proposal Path: ${token}`);
      edges.push({
        from: proposal.id,
        to: entityId,
        kind: "proposal_mentions",
      });
    }
  }

  const projection: ProceduralGraphProjection = {
    schema_version: 1,
    generated_at: now.toISOString(),
    nodes: Object.freeze(
      nodes
        .toSorted((left, right) => left.id.localeCompare(right.id))
        .map((item) => Object.freeze(item)),
    ),
    edges: Object.freeze(
      dedupeEdges(edges)
        .toSorted(
          (left, right) =>
            left.from.localeCompare(right.from) ||
            left.to.localeCompare(right.to) ||
            left.kind.localeCompare(right.kind),
        )
        .map((item) => Object.freeze(item)),
    ),
  };

  writeMachineStateText(proceduralGraphPath(vault), `${JSON.stringify(projection, null, 2)}\n`);
  return projection;
}

/**
 * Write a procedural projection or counter file. They are machine state
 * (`paths.ts`), never store records: the graph and the hints are
 * recomputed on each machine, and the counters tick on every use.
 */
export function writeMachineStateText(path: string, text: string): void {
  mkdirSync(dirname(path), { recursive: true });
  atomicWriteFileSync(path, text);
}

/** The text of a machine-state file, or null when there is none. */
function readMachineStateText(path: string): string | null {
  try {
    return readFileSync(path, "utf8");
  } catch {
    return null;
  }
}

/**
 * The text of the procedural projection or counter file at `path` (its
 * machine-state location), or null when there is none.
 *
 * A machine switched before these files became machine state (task 3.10)
 * holds them as `lane-entry` records of the store, the migration's import
 * of the legacy files. Until this machine has its own copy, that record is
 * read and adopted: copied into the machine-state location on the first
 * read, so a switched machine answers from it before its next reconcile.
 * The record itself stays in the store until the legacy tree leaves the
 * vault (`store-migration/removal.ts` retires it then), so a rollback
 * still finds the legacy file it was imported from.
 *
 * `guard` runs the adoption write: a file other writers update (the usage
 * counters) passes the run of its write lock, and the copy is written only
 * when the file is still absent inside it, so an adoption never lands over
 * a tick another process wrote first. A caller that already holds the lock
 * passes none.
 */
export function readProceduralState(
  vault: string,
  path: string,
  guard: (write: () => void) => void = (write) => write(),
): string | null {
  const own = readMachineStateText(path);
  if (own !== null) return own;
  if (!lanePagesInStore(vault)) return null;
  const stored = join(vault, BRAIN_PROCEDURAL_MEMORY_REL, basename(path));
  if (stored === path) return null;
  let text: string | null;
  try {
    text = readLaneText(vault, stored);
  } catch {
    return null;
  }
  if (text === null) return null;
  let answer = text;
  try {
    guard(() => {
      // Another process may have adopted (and ticked) it meanwhile.
      const now = readMachineStateText(path);
      if (now !== null) {
        answer = now;
        return;
      }
      writeMachineStateText(path, text);
    });
  } catch {
    // Adopted on the next read instead; the answer stands.
  }
  return answer;
}

export function readProceduralGraph(vault: string): ProceduralGraphProjection | null {
  const text = readProceduralState(vault, proceduralGraphPath(vault));
  if (text === null) return null;
  try {
    const parsed = JSON.parse(text) as ProceduralGraphProjection;
    if (parsed.schema_version !== 1) return null;
    if (!Array.isArray(parsed.nodes) || !Array.isArray(parsed.edges)) return null;
    return parsed;
  } catch {
    return null;
  }
}

function readProceduralIndex(vault: string): ProceduralMemoryEntry[] {
  const path = proceduralMemoryIndexPath(vault);
  if (!lanePageExists(vault, path)) return [];
  try {
    const parsed = JSON.parse(readLaneFile(vault, path)) as {
      schema_version?: unknown;
      entries?: ProceduralMemoryEntry[];
    };
    if (parsed.schema_version !== 1) return [];
    if (!Array.isArray(parsed.entries)) return [];
    return parsed.entries;
  } catch {
    return [];
  }
}

function detectProcedureSourceProposal(vault: string, sourcePath: string): string | null {
  if (!sourcePath.startsWith("Brain/procedures/")) return null;
  let absPath: string;
  try {
    absPath = ensureInsideVault(join(vault, sourcePath), vault);
  } catch {
    return null;
  }
  if (!lanePageExists(vault, absPath)) return 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, since a failed read
  // yields an empty map and falls through to the same `return null`.
  // Dropped lines are reported centrally; see the "Why most readers keep
  // the two-tuple form" section in src/core/vault.ts.
  const [fm] = parseLanePage(vault, absPath);
  if (typeof fm["source_proposal"] === "string" && fm["source_proposal"].trim()) {
    return fm["source_proposal"].trim();
  }
  return null;
}

function listProposals(vault: string): ProceduralGraphNode[] {
  const out: ProceduralGraphNode[] = [];
  for (const tuple of [
    ["pending", skillProposalPendingPath],
    ["accepted", skillProposalAcceptedPath],
    ["rejected", skillProposalRejectedPath],
  ] as const) {
    const [status, builder] = tuple;
    const dir = dirname(builder(vault, "sample"));
    if (!lanePageExists(vault, dir)) continue;
    for (const name of readDirSorted(vault, dir)) {
      if (!name.endsWith(".md")) continue;
      const absPath = join(dir, name);
      // Unit F: unreachable `catch { continue }` removed - nothing in this
      // body throws (`parseFrontmatter` reads inside its own try, and the
      // rest is property reads and `basename`). A file whose frontmatter
      // could not be read yields an empty map, fails the `kind` check on
      // the next line, and is skipped exactly as the dead branch intended.
      // See the "Why most readers keep the two-tuple form" section in
      // src/core/vault.ts for where the condition IS reported.
      const [fm] = parseLanePage(vault, absPath);
      if (fm["kind"] !== "brain-skill-proposal") continue;
      const id = typeof fm["id"] === "string" ? fm["id"] : `proposal-${basename(name, ".md")}`;
      out.push({
        id,
        kind: "proposal",
        title:
          typeof fm["slug"] === "string"
            ? `Proposal: ${fm["slug"]}`
            : `Proposal: ${basename(name, ".md")}`,
        sourcePath: `Brain/skill-proposals/${status}/${name}`,
        metadata: {
          status,
          pattern_kind: fm["pattern_kind"] ?? null,
        },
      });
    }
  }
  return out;
}

function readDirSorted(vault: string, dir: string): string[] {
  try {
    return listLaneFiles(vault, dir, "").toSorted();
  } catch {
    return [];
  }
}

function sourcePathTokens(path: string): string[] {
  return path
    .replaceAll("\\", "/")
    .split("/")
    .map((part) => part.trim().toLowerCase())
    .filter((part) => part.length >= 3 && /^[a-z0-9._-]+$/.test(part));
}

function ensureEntityNode(
  nodes: ProceduralGraphNode[],
  nodeById: Set<string>,
  id: string,
  title: string,
): void {
  if (nodeById.has(id)) return;
  nodes.push({
    id,
    kind: "entity",
    title,
    sourcePath: null,
    metadata: {},
  });
  nodeById.add(id);
}

function entityNodeId(raw: string): string {
  return `ent-${raw
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, "-")
    .replace(/^-+|-+$/g, "")}`;
}

function dedupeEdges(edges: ReadonlyArray<ProceduralGraphEdge>): ProceduralGraphEdge[] {
  const out: ProceduralGraphEdge[] = [];
  const seen = new Set<string>();
  for (const edge of edges) {
    const key = `${edge.from}\u0000${edge.to}\u0000${edge.kind}`;
    if (seen.has(key)) continue;
    seen.add(key);
    out.push(edge);
  }
  return out;
}