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
8.6 KB
Raw Blame
/**
 * Dual-output reports (t_00eece5d, article: Hermes as an Onchain
 * Analyst): digest/brief surfaces persist a machine-diffable JSON
 * snapshot per run so the NEXT run can report "what changed since
 * last time" deterministically - the run-over-run continuation of the
 * dashboard-ready `Brain/metrics/` contract from v0.45.0.
 *
 * Layout: `Brain/reports/<surface>/<ISO-date>.json`, schema
 * `o2b.report-snapshot.v1`, atomic single-file writes, fail-soft
 * reader (a torn prior snapshot reads as none - the delta degrades to
 * "no prior", never to a crash).
 *
 * The diff keys on STABLE identities, not array order:
 *
 *   - objects flatten by key path (`counts/events`);
 *   - arrays of objects key each element by its `id` / `topic` /
 *     `path` / `slug` field when one exists (index as last resort);
 *   - arrays of primitives compare as sets (`topics[gamma]` added).
 *
 * Opt-in: `report_snapshots_enabled` config key, env mirror
 * `OPEN_SECOND_BRAIN_REPORT_SNAPSHOTS`. A vault that enables nothing
 * writes nothing and renders byte-identically.
 */

import { join } from "node:path";

import { discoverConfig } from "../config.ts";
import {
  assertLaneWrite,
  listLaneFiles,
  readLaneText,
  writeLaneText,
} from "../store/lane-pages.ts";

export const REPORT_SNAPSHOT_SCHEMA_VERSION = "o2b.report-snapshot.v1";

/** Fields stripped before snapshotting: volatile per-render decoration. */
const VOLATILE_KEYS: ReadonlySet<string> = new Set([
  "generated_at",
  // CLI surfaces snapshot raw core envelopes whose render stamp is
  // camelCase - both spellings are per-render decoration.
  "generatedAt",
  "run_id",
  "local_time",
  "timezone",
  "delta",
]);

/** Identity fields tried (in order) to key array-of-object elements. */
const IDENTITY_KEYS = ["id", "pref_id", "topic", "path", "slug", "date"] as const;

export interface ReportChange {
  readonly path: string;
  readonly before: string;
  readonly after: string;
}

export interface ReportDelta {
  /** Date of the prior snapshot the delta is computed against. */
  readonly prior_date: string | null;
  readonly added: ReadonlyArray<string>;
  readonly removed: ReadonlyArray<string>;
  readonly changed: ReadonlyArray<ReportChange>;
}

export interface LoadedReportSnapshot {
  readonly date: string;
  readonly payload: unknown;
}

export function reportSnapshotsEnabled(configPath?: string): boolean {
  const env = process.env["OPEN_SECOND_BRAIN_REPORT_SNAPSHOTS"];
  if (env === "true" || env === "1") return true;
  if (env === "false" || env === "0") return false;
  try {
    const value = discoverConfig(configPath).data["report_snapshots_enabled"];
    return value === "true" || value === "1";
  } catch {
    return false;
  }
}

function reportsDir(vault: string, surface: string): string {
  return join(vault, "Brain", "reports", surface);
}

/** Strip volatile decoration recursively before persisting/diffing. */
function stripVolatile(value: unknown): unknown {
  if (Array.isArray(value)) return value.map(stripVolatile);
  if (value !== null && typeof value === "object") {
    const out: Record<string, unknown> = {};
    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
      if (VOLATILE_KEYS.has(k)) continue;
      out[k] = stripVolatile(v);
    }
    return out;
  }
  return value;
}

/** Flatten one payload into stable-identity leaf paths. */
function flatten(value: unknown, prefix: string, out: Map<string, string>): void {
  if (Array.isArray(value)) {
    const allPrimitive = value.every((v) => v === null || typeof v !== "object");
    if (allPrimitive) {
      // Set semantics: membership is the identity.
      for (const item of value) out.set(`${prefix}[${String(item)}]`, "present");
      return;
    }
    value.forEach((item, index) => {
      let key = String(index);
      if (item !== null && typeof item === "object" && !Array.isArray(item)) {
        for (const idKey of IDENTITY_KEYS) {
          const candidate = (item as Record<string, unknown>)[idKey];
          if (typeof candidate === "string" && candidate !== "") {
            key = candidate;
            break;
          }
        }
      }
      flatten(item, prefix === "" ? key : `${prefix}/${key}`, out);
    });
    return;
  }
  if (value !== null && typeof value === "object") {
    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
      flatten(v, prefix === "" ? k : `${prefix}/${k}`, out);
    }
    return;
  }
  out.set(prefix, JSON.stringify(value) ?? "undefined");
}

/** Deterministic keyed diff between two report payloads. */
export function diffReportPayloads(
  before: unknown,
  after: unknown,
): Pick<ReportDelta, "added" | "removed" | "changed"> {
  const a = new Map<string, string>();
  const b = new Map<string, string>();
  flatten(stripVolatile(before), "", a);
  flatten(stripVolatile(after), "", b);
  const added: string[] = [];
  const removed: string[] = [];
  const changed: ReportChange[] = [];
  for (const [path, value] of b) {
    if (!a.has(path)) added.push(path);
    else if (a.get(path) !== value) changed.push({ path, before: a.get(path)!, after: value });
  }
  for (const path of a.keys()) {
    if (!b.has(path)) removed.push(path);
  }
  return {
    added: Object.freeze(added.toSorted()),
    removed: Object.freeze(removed.toSorted()),
    changed: Object.freeze(changed.toSorted((x, y) => (x.path < y.path ? -1 : 1))),
  };
}

/** Persist one surface snapshot (atomic; same-date overwrite is fine). */
export function writeReportSnapshot(
  vault: string,
  surface: string,
  date: string,
  payload: unknown,
): string {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertLaneWrite(vault);
  const dir = reportsDir(vault, surface);
  const path = join(dir, `${date}.json`);
  writeLaneText(
    vault,
    path,
    JSON.stringify(
      { schema: REPORT_SNAPSHOT_SCHEMA_VERSION, surface, date, payload: stripVolatile(payload) },
      null,
      2,
    ) + "\n",
  );
  return path;
}

/** Newest snapshot strictly before `beforeDate`. Fail-soft null. */
export function loadLatestReportSnapshot(
  vault: string,
  surface: string,
  beforeDate: string,
): LoadedReportSnapshot | null {
  // `listLaneFiles` answers [] for a missing folder in both modes: no
  // separate existence probe (a second full pass over the store).
  const dir = reportsDir(vault, surface);
  let names: string[];
  try {
    names = listLaneFiles(vault, dir, "");
  } catch {
    return null;
  }
  const dates = names
    .filter((n) => n.endsWith(".json"))
    .map((n) => n.slice(0, -".json".length))
    .filter((d) => d < beforeDate)
    .toSorted();
  for (let i = dates.length - 1; i >= 0; i--) {
    try {
      const parsed: unknown = JSON.parse(readLaneText(vault, join(dir, `${dates[i]}.json`)) ?? "");
      if (parsed === null || typeof parsed !== "object") continue;
      const record = parsed as Record<string, unknown>;
      if (record["schema"] !== REPORT_SNAPSHOT_SCHEMA_VERSION) continue;
      return { date: dates[i]!, payload: record["payload"] };
    } catch {
      // Torn snapshot: skip to the next-older one.
    }
  }
  return null;
}

/**
 * The one call surfaces make: when snapshots are enabled, persist the
 * current payload and return the delta against the latest prior
 * snapshot (no prior -> empty delta with `prior_date: null`). When
 * disabled, returns null and touches nothing.
 */
export function captureReportDelta(
  vault: string,
  surface: string,
  date: string,
  payload: unknown,
  opts: { configPath?: string } = {},
): ReportDelta | null {
  if (!reportSnapshotsEnabled(opts.configPath)) return null;
  const prior = loadLatestReportSnapshot(vault, surface, date);
  writeReportSnapshot(vault, surface, date, payload);
  if (prior === null) {
    return Object.freeze({
      prior_date: null,
      added: Object.freeze([]),
      removed: Object.freeze([]),
      changed: Object.freeze([]),
    });
  }
  return Object.freeze({ prior_date: prior.date, ...diffReportPayloads(prior.payload, payload) });
}

/** Human-readable "Since last run" block for markdown/text output. */
export function renderReportDelta(delta: ReportDelta): string {
  if (delta.prior_date === null) {
    return "Since last run: first snapshot - nothing to compare yet.";
  }
  if (delta.added.length === 0 && delta.removed.length === 0 && delta.changed.length === 0) {
    return `Since last run (${delta.prior_date}): no changes.`;
  }
  const lines = [`Since last run (${delta.prior_date}):`];
  for (const path of delta.added) lines.push(`  + ${path}`);
  for (const path of delta.removed) lines.push(`  - ${path}`);
  for (const change of delta.changed) {
    lines.push(`  ~ ${change.path}: ${change.before} -> ${change.after}`);
  }
  return lines.join("\n");
}