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
12.2 KB
Raw Blame
/**
 * `buildBeliefEvolution(index, vault, target)` - per-preference or
 * per-topic chronological view assembled from the `TimelineIndex`
 * plus `Brain/retired/*.md` frontmatter for retirement chain
 * resolution.
 *
 * Transitions are derived from `dream` summary events:
 *   - `pref-id` appears in `new_unconfirmed` -> creation
 *   - `pref-id` appears in `confirmed`       -> promotion
 *   - matching `ret-id` appears in `retired` -> retirement
 *
 * Evidence rows come from `apply-evidence` timeline events filtered
 * to the target id (or any pref/ret matching the topic). Running
 * applied / violated / outdated counts are carried per row.
 *
 * Retirement chain resolution walks `superseded_by` links across
 * `Brain/retired/*.md` with a visited-set cycle guard.
 *
 * Design anchor: `docs/brainstorm/temporal-synthesis/design.md`,
 * Task 4 in `plan.md`.
 */

import { memoryFolderPages, memoryPageNamed } from "./../memory-pages.ts";
import { BRAIN_APPLY_RESULT, BRAIN_LOG_EVENT_KIND, type BrainApplyResult } from "./../types.ts";
import { classifyFreshnessTrend, type FreshnessTrendReport } from "./freshness-trend.ts";
import { extractId } from "./period-common.ts";
import { selectEvents } from "./select-events.ts";
import type { TemporalEvent, TimelineIndex } from "./types.ts";

/** What the caller wants the evolution for. */
export type BeliefEvolutionTarget = { readonly prefId: string } | { readonly topic: string };

/** One status-change row. */
export interface BeliefTransition {
  /** ISO-8601 UTC timestamp. */
  readonly at: string;
  /** Transition kind. */
  readonly kind: "creation" | "promotion" | "retirement";
  /** Preference / retired id the transition applies to. */
  readonly prefId: string;
  /** Wikilink the dream summary used (for audit). */
  readonly link: string;
}

/** One evidence row with running counts. */
export interface BeliefEvidenceRow {
  readonly at: string;
  readonly prefId: string;
  readonly result: BrainApplyResult;
  readonly artifact?: string;
  readonly runningApplied: number;
  readonly runningViolated: number;
  readonly runningOutdated: number;
}

/** One retirement record sourced from `Brain/retired/*.md`. */
export interface BeliefRetirement {
  readonly prefId: string;
  readonly retiredAt: string;
  readonly reason?: string;
  readonly retiredBy?: string;
  readonly supersededBy?: string;
  readonly supersedes?: string;
  readonly topic?: string;
}

export interface BeliefEvolutionEnvelope {
  readonly target: BeliefEvolutionTarget;
  readonly transitions: ReadonlyArray<BeliefTransition>;
  readonly evidence: ReadonlyArray<BeliefEvidenceRow>;
  readonly retirements: ReadonlyArray<BeliefRetirement>;
  /**
   * Directional freshness trend computed live from the evidence rows
   * (Time-Aware Recall & Activation Suite, t_ee09a6ce). Absent only
   * when the window holds no signal at all (no transitions and no
   * evidence), so empty envelopes stay shaped as before.
   */
  readonly freshnessTrend?: FreshnessTrendReport;
  readonly generatedAt: string;
}

export interface BuildBeliefEvolutionOptions {
  readonly now?: Date;
}

export function buildBeliefEvolution(
  index: TimelineIndex,
  vault: string,
  target: BeliefEvolutionTarget,
  opts: BuildBeliefEvolutionOptions = {},
): BeliefEvolutionEnvelope {
  const now = opts.now ?? new Date();
  const generatedAt = now.toISOString();
  const targetIdSet = resolveTargetIds(index, vault, target);

  const transitions = collectTransitions(index, targetIdSet);
  const evidence = collectEvidence(index, targetIdSet);
  const retirements = collectRetirements(vault, target, targetIdSet);

  // Freshness trend (t_ee09a6ce): classified live from the evidence
  // rows. `createdAt` comes from the creation transition when the
  // window saw one; otherwise the classifier treats age as unknown.
  const creation = transitions.find((t) => t.kind === "creation");
  const freshnessTrend =
    transitions.length > 0 || evidence.length > 0
      ? classifyFreshnessTrend({
          createdAt: creation?.at ?? null,
          events: evidence.map((e) => ({ at: e.at, result: e.result })),
          nowMs: now.getTime(),
        })
      : undefined;

  return Object.freeze({
    target,
    transitions: Object.freeze(transitions),
    evidence: Object.freeze(evidence),
    retirements: Object.freeze(retirements),
    ...(freshnessTrend !== undefined ? { freshnessTrend } : {}),
    generatedAt,
  });
}

/**
 * Resolve the set of pref-* / ret-* ids that the target references.
 * For a prefId target the set is just that id plus its `ret-` sibling.
 * For a topic target we scan every `pref-*` / `ret-*` file with that
 * topic in frontmatter, plus every timeline event grouped under that
 * topic that carries a prefId.
 */
function resolveTargetIds(
  index: TimelineIndex,
  vault: string,
  target: BeliefEvolutionTarget,
): ReadonlySet<string> {
  if ("prefId" in target) {
    const ids = new Set<string>();
    ids.add(target.prefId);
    // pref-foo / ret-foo share the same slug. Treat the pair as the
    // same lifecycle anchor so transitions across the rename are
    // surfaced together.
    if (target.prefId.startsWith("pref-")) {
      ids.add(`ret-${target.prefId.slice("pref-".length)}`);
    } else if (target.prefId.startsWith("ret-")) {
      ids.add(`pref-${target.prefId.slice("ret-".length)}`);
    }
    return ids;
  }
  const ids = new Set<string>();
  const fromIndex = index.eventsByTopic.get(target.topic);
  if (fromIndex !== undefined) {
    for (const ev of fromIndex) {
      if (ev.prefId !== undefined) ids.add(ev.prefId);
    }
  }
  collectTopicIdsFromDisk(vault, target.topic, "preferences", "pref-", ids);
  collectTopicIdsFromDisk(vault, target.topic, "retired", "ret-", ids);
  return ids;
}

function collectTopicIdsFromDisk(
  vault: string,
  topic: string,
  subdir: "preferences" | "retired",
  prefix: "pref-" | "ret-",
  out: Set<string>,
): void {
  for (const entry of memoryFolderPages(vault, subdir, { regularFilesOnly: true })) {
    if (!entry.name.endsWith(".md")) continue;
    if (!entry.name.startsWith(prefix)) continue;
    let meta: Record<string, unknown>;
    try {
      [meta] = entry.read();
    } catch {
      continue;
    }
    if (meta["topic"] !== topic) continue;
    const id = typeof meta["id"] === "string" ? meta["id"] : null;
    out.add(id ?? entry.name.slice(0, -".md".length));
  }
}

function collectTransitions(
  index: TimelineIndex,
  targetIds: ReadonlySet<string>,
): BeliefTransition[] {
  const dreamEvents = index.eventsByKind.get(BRAIN_LOG_EVENT_KIND.dream) ?? [];
  const out: BeliefTransition[] = [];
  for (const ev of dreamEvents) {
    const summary = ev.dreamSummary;
    if (summary === undefined) continue;
    appendTransitionsFromLinks(ev.at, summary.newUnconfirmed, "creation", targetIds, out);
    appendTransitionsFromLinks(ev.at, summary.confirmed, "promotion", targetIds, out);
    appendTransitionsFromLinks(ev.at, summary.retired, "retirement", targetIds, out);
  }
  out.sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0));
  return out;
}

function appendTransitionsFromLinks(
  at: string,
  links: ReadonlyArray<string> | undefined,
  kind: BeliefTransition["kind"],
  targetIds: ReadonlySet<string>,
  out: BeliefTransition[],
): void {
  if (links === undefined) return;
  for (const link of links) {
    const id = extractId(link);
    if (id === undefined) continue;
    if (!matchesTarget(id, targetIds)) continue;
    out.push(
      Object.freeze({
        at,
        kind,
        prefId: id,
        link,
      }),
    );
  }
}

function matchesTarget(candidateId: string, targetIds: ReadonlySet<string>): boolean {
  if (targetIds.has(candidateId)) return true;
  // pref-foo / ret-foo share lifecycle; treat the alternate prefix as
  // matching too so a `retirement` entry against `ret-foo` resolves
  // even when only `pref-foo` was requested.
  if (candidateId.startsWith("pref-")) {
    return targetIds.has(`ret-${candidateId.slice("pref-".length)}`);
  }
  if (candidateId.startsWith("ret-")) {
    return targetIds.has(`pref-${candidateId.slice("ret-".length)}`);
  }
  return false;
}

function collectEvidence(
  index: TimelineIndex,
  targetIds: ReadonlySet<string>,
): BeliefEvidenceRow[] {
  // apply-evidence rows do not carry `topic` themselves - the topic
  // lives on the target preference. So we narrow to the apply-evidence
  // bucket and filter by the resolved `targetIds` set (which contains
  // every pref-* / ret-* the topic / prefId pair points at).
  const candidate = selectEvents(index, {
    kind: BRAIN_LOG_EVENT_KIND.applyEvidence,
  });
  const filtered: TemporalEvent[] = [];
  for (const ev of candidate) {
    if (ev.prefId === undefined) continue;
    if (!matchesTarget(ev.prefId, targetIds)) continue;
    if (ev.result === undefined) continue;
    filtered.push(ev);
  }
  let applied = 0;
  let violated = 0;
  let outdated = 0;
  const out: BeliefEvidenceRow[] = [];
  for (const ev of filtered) {
    if (ev.result === BRAIN_APPLY_RESULT.applied) applied++;
    if (ev.result === BRAIN_APPLY_RESULT.violated) violated++;
    if (ev.result === BRAIN_APPLY_RESULT.outdated) outdated++;
    const row: BeliefEvidenceRow = {
      at: ev.at,
      prefId: ev.prefId!,
      result: ev.result!,
      ...(ev.artifact !== undefined ? { artifact: ev.artifact } : {}),
      runningApplied: applied,
      runningViolated: violated,
      runningOutdated: outdated,
    };
    out.push(Object.freeze(row));
  }
  return out;
}

function collectRetirements(
  vault: string,
  _target: BeliefEvolutionTarget,
  targetIds: ReadonlySet<string>,
): BeliefRetirement[] {
  const out: BeliefRetirement[] = [];
  const visited = new Set<string>();
  // Seed queue once per source id. `pref-foo` and `ret-foo` share
  // the slug, so a `pref-` id always pushes its `ret-` sibling too.
  // Topic targets already enumerate every `ret-*` with the topic
  // via `resolveTargetIds`, so a second loop would only feed
  // duplicates (the visited-set guards them out, but the dedup at
  // the seed step avoids the queue grind in the first place).
  const queue: string[] = [];
  for (const id of targetIds) {
    if (id.startsWith("ret-")) queue.push(id);
    if (id.startsWith("pref-")) queue.push(`ret-${id.slice("pref-".length)}`);
  }
  while (queue.length > 0) {
    const id = queue.shift();
    if (id === undefined) break;
    if (visited.has(id)) continue;
    visited.add(id);
    const page = memoryPageNamed(vault, "retired", `${id}.md`);
    if (page === null) continue;
    let meta: Record<string, unknown>;
    try {
      [meta] = page.read();
    } catch {
      continue;
    }
    const retiredAt = readScalar(meta["retired_at"]);
    if (retiredAt === undefined) continue;
    const supersededByLink = readScalar(meta["superseded_by"]);
    const supersededBy = supersededByLink !== undefined ? extractId(supersededByLink) : undefined;
    const supersedesLink = readScalar(meta["supersedes"]);
    const supersedes = supersedesLink !== undefined ? extractId(supersedesLink) : undefined;
    const row: BeliefRetirement = {
      prefId: id,
      retiredAt,
      ...(readScalar(meta["retired_reason"]) !== undefined
        ? { reason: readScalar(meta["retired_reason"])! }
        : {}),
      ...(readScalar(meta["retired_by"]) !== undefined
        ? { retiredBy: readScalar(meta["retired_by"])! }
        : {}),
      ...(supersededBy !== undefined ? { supersededBy } : {}),
      ...(supersedes !== undefined ? { supersedes } : {}),
      ...(readScalar(meta["topic"]) !== undefined ? { topic: readScalar(meta["topic"])! } : {}),
    };
    out.push(Object.freeze(row));
    // Walk the chain: `supersedes` points to the previous retired
    // record; `superseded_by` to the new active pref (we follow the
    // ret- sibling so we keep enumerating retired records, not active
    // ones).
    if (supersedes !== undefined && supersedes.startsWith("ret-")) {
      queue.push(supersedes);
    }
    if (supersededBy !== undefined && supersededBy.startsWith("pref-")) {
      queue.push(`ret-${supersededBy.slice("pref-".length)}`);
    }
  }
  out.sort((a, b) => {
    if (a.retiredAt < b.retiredAt) return -1;
    if (a.retiredAt > b.retiredAt) return 1;
    return a.prefId.localeCompare(b.prefId);
  });
  return out;
}

function readScalar(value: unknown): string | undefined {
  return typeof value === "string" && value.length > 0 ? value : undefined;
}