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
4.6 KB
Raw Blame
/**
 * Shared derived-artifact IO helper - one home for the write/read
 * convention the co-occurrence graph and the search-tuning store each
 * shipped separately (recall-quality wave, S2).
 *
 * A derived artifact is a pure function of an input set over the vault:
 * suggestions, learned parameters, learned vocabularies. None of it is
 * authorial content, so it is re-derivable at any time, and the storage
 * contract follows from that:
 *
 *   - SCHEMA-VERSIONED: `schema: "o2b.<name>.vN"` names the payload's
 *     shape; a reader built for another shape must never see these bytes.
 *   - DATASET-HASHED: `dataset_hash` fingerprints the input set the
 *     artifact was derived from, so a reader can tell that the vault has
 *     moved on and the stored derivation is stale.
 *   - FAIL-OPEN: a missing file, torn JSON, a schema mismatch, or a
 *     dataset-hash expiry all read as `null`. A derived artifact is a
 *     cache of a recomputable function; no consumer should ever be
 *     blocked by one, so every defect collapses to "not available" and
 *     the caller re-derives.
 *   - WRITTEN THROUGH THE RAILS: the write is atomic (temp file plus
 *     rename, so an interrupted run leaves the old artifact or the new
 *     one, never a hybrid) and passes the vault-identity guard, exactly
 *     like every other Brain write.
 *
 * Extraction only: co-occurrence and tuning keep their own code this
 * wave. New derived artifacts (entity lexicon, hallways) route through
 * here so the convention stops being copied.
 */

import { createHash } from "node:crypto";
import { join } from "node:path";

import { ensureInsideVault } from "../path-safety.ts";
import { assertLaneWrite, readLaneText, writeLaneText } from "../store/lane-pages.ts";

/** The fields every derived artifact carries, beside its own payload. */
export interface DerivedArtifact {
  /** Schema tag of the payload shape, spelled `o2b.<name>.vN`. */
  schema: string;
  /** ISO instant the artifact was derived at. */
  generated_at: string;
  /** {@link deriveDatasetHash} over the input set the artifact was derived from. */
  dataset_hash: string;
}

/**
 * Fingerprint an input set: sha256 over the JSON encoding of its
 * deduplicated, lexicographically sorted parts. Order-independent and
 * duplicate-insensitive by construction, so two derivations over the
 * same SET of inputs agree on the hash regardless of walk order.
 */
export function deriveDatasetHash(parts: readonly string[]): string {
  const stable = [...new Set(parts)].toSorted();
  return createHash("sha256").update(JSON.stringify(stable)).digest("hex");
}

/**
 * Write a derived artifact to `<vaultDir>/<relPath>` atomically, guarded
 * by the vault-identity assertion every Brain write passes. Parent
 * directories are created as needed; the payload is pretty-printed JSON
 * with a trailing newline. Throws when `relPath` escapes the vault or
 * when the root's identity marker differs from the one this process
 * pinned - a refusal that arrives before the first byte.
 */
export function writeDerivedArtifact<T extends DerivedArtifact>(
  vaultDir: string,
  relPath: string,
  artifact: T,
): void {
  assertLaneWrite(vaultDir);
  // A record-lane file: a store record once switched (task 2.10 WP6).
  const path = ensureInsideVault(join(vaultDir, relPath), vaultDir);
  writeLaneText(vaultDir, path, `${JSON.stringify(artifact, null, 2)}\n`);
}

/**
 * Read a derived artifact written by {@link writeDerivedArtifact},
 * re-validated against `expectedSchema` and `datasetHash`. Returns
 * `null` - never throws - when the file is missing, the JSON is torn,
 * the document is not an object, `schema` or `generated_at` is not the
 * expected shape, the schema tag differs, or the stored dataset hash is
 * not the hash of the caller's current input set (fail-open). An
 * escaping `relPath` reads as `null` too, like every other absent
 * artifact.
 */
export function readDerivedArtifact<T extends DerivedArtifact>(
  vaultDir: string,
  relPath: string,
  expectedSchema: string,
  datasetHash: string,
): T | null {
  try {
    const path = ensureInsideVault(join(vaultDir, relPath), vaultDir);
    const text = readLaneText(vaultDir, path);
    if (text === null) return null;
    const parsed: unknown = JSON.parse(text);
    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
    const record = parsed as Record<string, unknown>;
    if (record["schema"] !== expectedSchema) return null;
    if (typeof record["generated_at"] !== "string") return null;
    if (record["dataset_hash"] !== datasetHash) return null;
    return Object.freeze(parsed as T);
  } catch {
    return null;
  }
}