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
21.2 KB
Raw Blame
/**
 * Evidence refresh and promotion planning (dream phase F4).
 *
 * Extracted from dream.ts. Scans apply-evidence log events (merge-
 * alias aware), recomputes per-preference counters, status
 * transitions (confirm, quarantine, context-driven retire), and
 * confidence - including the outcome-regression penalty. Pure
 * planning: callers apply the returned updates.
 */

import { BAND_RANK, computeConfidence, rebandConfidence } from "./confidence.ts";
import type { PlanState, ScanResult } from "./dream-plan.ts";
import { collectEvidenceForSlug, privateEvidenceCounts } from "./evidence.ts";
import { preferencesStoreOnly, storePreferenceEntry } from "./preference-store.ts";
import { countersForShared } from "../store/read/store-entities.ts";
import { logDayReader } from "./log-days.ts";
import { isPinned } from "./pin.ts";
import { wouldRewritePreference } from "./preference.ts";
import { classifyFreshnessTrend } from "./temporal/freshness-trend.ts";
import { parseWikilink, renderPrefLink } from "./wikilink.ts";
import {
  BRAIN_APPLY_RESULT,
  BRAIN_LOG_EVENT_KIND,
  BRAIN_PREFERENCE_STATUS,
  BRAIN_RETIRED_REASON,
  type BrainConfidence,
  type BrainConfig,
  type BrainPreference,
} from "./types.ts";

export interface RefreshUpdate {
  readonly slug: string;
  readonly topic: string;
  readonly scope?: string;
  readonly principle: string;
  readonly created_at: string;
  readonly unconfirmed_until: string;
  readonly status: (typeof BRAIN_PREFERENCE_STATUS)[keyof typeof BRAIN_PREFERENCE_STATUS];
  readonly evidenced_by: ReadonlyArray<string>;
  readonly confirmed_at: string | null;
  readonly applied_count: number;
  readonly violated_count: number;
  readonly last_evidence_at: string | null;
  readonly confidence: BrainConfidence;
  readonly confidence_value: number;
  readonly pinned: boolean;
  /**
   * Freshness trend (t_ee09a6ce), computed at PLAN time so the no-op
   * pre-flight (`wouldRewritePreference`) renders the same bytes the
   * write loop will stamp. Computing it only in the write loop would
   * make every stamped pref look like "needs rewrite" forever. Absent
   * when the stamp is withheld: a pref that has never carried the
   * field and is not being rewritten anyway stays byte-identical, so
   * legacy vaults keep their no-op dream guarantees.
   */
  readonly freshness_trend?: string;
  /**
   * Derived-fact fields (finding 77), carried for the same reason the
   * pre-flight carries them: the renderer emits a non-default
   * `provenance` and a non-empty `related` only when the write input
   * supplies them, so an update loop that omitted them would strip both
   * from a promoted rule on its first counter change - and, because the
   * no-op pre-flight renders from the input too, leave the file looking
   * "needs rewrite" on every pass after that. Absent stays absent: a
   * pref without these fields is written exactly as before.
   */
  readonly provenance?: BrainPreference["provenance"];
  readonly related?: ReadonlyArray<string>;
  /**
   * The record's `visibility:` tokens, carried for the same reason the
   * derived-fact fields are (finding 77; review round 2): the renderer
   * emits a `visibility:` line only when the write input supplies it,
   * and `wouldRewritePreference` builds its output from the input alone
   * - it does not run the tiered merge that keeps the file's existing
   * line - so an update that omitted the tokens would leave every pref
   * carrying `visibility:` on disk looking "needs rewrite" on every
   * pass, each rewrite a real `_revision` bump. Absent stays absent: a
   * pref without the field is written exactly as before.
   */
  readonly visibility?: ReadonlyArray<string>;
}

/**
 * Pref β†’ recorded band drop within the current dream pass. Captured
 * during refresh so the digest can render a `## Confidence drops`
 * section without re-deriving transitions from the log.
 */
/**
 * Outcome regression (t_d478df53): minimum applied-with-failure events
 * before a preference is flagged, and the multiplicative confidence
 * penalty a flagged preference receives. The penalty is part of the
 * deterministic confidence derivation, so reruns stay no-ops.
 */
export const OUTCOME_REGRESSION_MIN_FAILURES = 2;
export const OUTCOME_REGRESSION_PENALTY = 0.8;

export interface DreamOutcomeRegression {
  readonly id: string;
  readonly principle: string;
  readonly failures: number;
  readonly successes: number;
}

export interface RefreshBandDrop {
  readonly id: string;
  readonly principle: string;
  readonly previous: BrainConfidence;
  readonly next: BrainConfidence;
  readonly applied: number;
  readonly violated: number;
  readonly previous_value: number | null;
  readonly next_value: number;
}

export interface RefreshResult {
  /** Slugs transitioning unconfirmed β†’ confirmed in THIS run. */
  readonly confirmed: Set<string>;
  /** Slug β†’ full updated frontmatter to write. */
  readonly updated: Map<string, RefreshUpdate>;
  /**
   * Preferences whose `confidence` band dropped (e.g. `high β†’ medium`)
   * during the refresh phase. Newest-first stable order (insertion
   * order at construction).
   */
  readonly bandDrops: RefreshBandDrop[];
  /** Preferences flagged by the outcome-regression rule (t_d478df53). */
  readonly outcomeRegressions: DreamOutcomeRegression[];
}

export interface ApplyEvidenceEntry {
  readonly pref_slug: string;
  readonly timestamp: string;
  readonly result: (typeof BRAIN_APPLY_RESULT)[keyof typeof BRAIN_APPLY_RESULT];
  /** Downstream outcome when recorded (t_d478df53). */
  readonly outcome?: "success" | "failure";
  /** The event was read from the `private` partition (see `evidence.ts`). */
  readonly fromPrivatePartition?: true;
}

export function scanApplyEvidence(vault: string | null): ApplyEvidenceEntry[] {
  const out: ApplyEvidenceEntry[] = [];
  const mergeAliases = new Map<string, string>();
  // Shard-aware (Memory Integrity Suite): merged per-day reads.
  const log = logDayReader(vault);
  for (const date of log.dates) {
    const { entries } = log.day(date);
    for (const e of entries) {
      if (e.eventType === BRAIN_LOG_EVENT_KIND.merge) {
        const keep = parseWikilinkFromBodyValue(e.body["keep"]);
        const drop = parseWikilinkFromBodyValue(e.body["drop"]);
        if (keep?.startsWith("pref-") && drop?.startsWith("pref-")) {
          mergeAliases.set(
            drop.slice("pref-".length),
            resolveMergeAlias(keep.slice("pref-".length), mergeAliases),
          );
        }
        continue;
      }
      if (e.eventType !== BRAIN_LOG_EVENT_KIND.applyEvidence) continue;
      const prefRaw = e.body["preference"];
      const result = e.body["result"];
      if (typeof prefRaw !== "string" || typeof result !== "string") continue;
      if (
        result !== BRAIN_APPLY_RESULT.applied &&
        result !== BRAIN_APPLY_RESULT.violated &&
        result !== BRAIN_APPLY_RESULT.outdated
      )
        continue;
      // Parse `[[pref-slug]]` β†’ slug.
      const target = parseWikilink(prefRaw);
      if (!target || !target.startsWith("pref-")) continue;
      out.push({
        pref_slug: target.slice("pref-".length),
        timestamp: e.timestamp,
        result: result as ApplyEvidenceEntry["result"],
        ...(e.body["outcome"] === "success" || e.body["outcome"] === "failure"
          ? { outcome: e.body["outcome"] as "success" | "failure" }
          : {}),
        ...(e.fromPrivatePartition === true ? { fromPrivatePartition: true as const } : {}),
      });
    }
  }
  // A private event counts only toward a private preference (`evidence.ts`),
  // judged after the merge aliases name the preference it lands on.
  const takesPrivate = new Map<string, boolean>();
  const counts = (slug: string): boolean => {
    let known = takesPrivate.get(slug);
    if (known === undefined) {
      known = privateEvidenceCounts(slug);
      takesPrivate.set(slug, known);
    }
    return known;
  };
  const resolved = out
    .map((entry) => ({
      ...entry,
      pref_slug: resolveMergeAlias(entry.pref_slug, mergeAliases),
    }))
    .filter((entry) => entry.fromPrivatePartition !== true || counts(entry.pref_slug));
  // Stable order: by timestamp ascending. Multiple entries at the same
  // second keep their parse order (parseLogDay returns insertion order).
  resolved.sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp));
  return resolved;
}

/** The applied and violated counts of `pref` as the dream scan counts evidence. */
function priorCounters(
  vault: string | null,
  slug: string,
  pref: { readonly applied_count: number; readonly violated_count: number },
): { readonly applied: number; readonly violated: number } {
  const entry = preferencesStoreOnly(vault) ? storePreferenceEntry(slug) : undefined;
  if (entry === undefined) return { applied: pref.applied_count, violated: pref.violated_count };
  const counters = countersForShared(entry);
  return { applied: counters.applied_count, violated: counters.violated_count };
}

function parseWikilinkFromBodyValue(value: unknown): string | null {
  return typeof value === "string" ? parseWikilink(value) : null;
}

function resolveMergeAlias(slug: string, aliases: ReadonlyMap<string, string>): string {
  let current = slug;
  const seen = new Set<string>();
  while (!seen.has(current)) {
    seen.add(current);
    const next = aliases.get(current);
    if (!next) return current;
    current = next;
  }
  return current;
}

export function planRefresh(
  vault: string | null,
  scan: ScanResult,
  evidence: ApplyEvidenceEntry[],
  cfg: BrainConfig,
  now: Date,
  plan: PlanState,
): RefreshResult {
  const confirmed = new Set<string>();
  const updated = new Map<string, RefreshUpdate>();
  const bandDrops: RefreshBandDrop[] = [];
  const outcomeRegressions: DreamOutcomeRegression[] = [];

  // Index evidence by slug.
  const bySlug = new Map<string, ApplyEvidenceEntry[]>();
  for (const e of evidence) {
    const arr = bySlug.get(e.pref_slug);
    if (arr) arr.push(e);
    else bySlug.set(e.pref_slug, [e]);
  }

  // Slugs that will retire this run β€” we skip refresh for those so the
  // retired/ snapshot reflects the pre-refresh counters (which is the
  // existing test expectation in moveToRetired).
  const retiringSlugs = new Set(plan.retires.map((r) => r.slug));

  for (const rec of scan.preferences) {
    const slug = rec.pref.id.startsWith("pref-") ? rec.pref.id.slice("pref-".length) : rec.pref.id;
    if (retiringSlugs.has(slug)) continue;
    // The counters the preference holds now, counted by the rule the scan
    // counts its evidence by: a shared preference's private uses are left
    // out (`evidence.ts`), or every pass would see them as a change.
    const prior = priorCounters(vault, slug, rec.pref);

    const ev = bySlug.get(slug) ?? [];
    const applied = ev.filter((e) => e.result === BRAIN_APPLY_RESULT.applied).length;
    const violated = ev.filter((e) => e.result === BRAIN_APPLY_RESULT.violated).length;
    const outdatedCount = ev.filter((e) => e.result === BRAIN_APPLY_RESULT.outdated).length;
    const lastEvidence = ev.length > 0 ? ev[ev.length - 1]!.timestamp : null;
    const firstApplied = ev.find((e) => e.result === BRAIN_APPLY_RESULT.applied);

    // `outdated` is a context-driven retire signal: a single event
    // means the rule's scope still matches but the artifact shows
    // the rule itself is obsolete (framework migration, convention
    // change). Pin protects against decay-based retires but NOT
    // against context-driven ones β€” pinning means "I want this
    // rule"; an `outdated` event means "context says this rule no
    // longer applies anywhere." Honour the explicit signal.
    //
    // Idempotency: once retired, the pref moves to `retired/` and
    // future dream passes don't re-process it from `preferences/`.
    if (outdatedCount > 0) {
      plan.retires.push({
        slug,
        principle: rec.pref.principle,
        reason: BRAIN_RETIRED_REASON.supersededByContext,
      });
      continue;
    }

    let status = rec.pref.status;
    let confirmedAt = rec.pref.confirmed_at;
    if (status === BRAIN_PREFERENCE_STATUS.unconfirmed && firstApplied) {
      status = BRAIN_PREFERENCE_STATUS.confirmed;
      confirmedAt = firstApplied.timestamp;
      confirmed.add(slug);
    }

    // Quarantine transitions β€” only applicable to already-confirmed
    // and already-quarantined preferences. An unconfirmed pref still
    // promotes via the firstApplied branch above; quarantine entry is
    // measured against `confirmed` counts. Detailed semantics live on
    // `BRAIN_PREFERENCE_STATUS.quarantine` in `types.ts`.
    if (
      status === BRAIN_PREFERENCE_STATUS.confirmed &&
      violated >= applied &&
      applied > cfg.confidence.low_max_applied
    ) {
      status = BRAIN_PREFERENCE_STATUS.quarantine;
    } else if (status === BRAIN_PREFERENCE_STATUS.quarantine) {
      const newViolated = violated > prior.violated;
      if (newViolated) {
        if (isPinned(rec.pref)) {
          plan.retainPinned.push({
            preference: renderPrefLink({
              id: rec.pref.id,
              principle: rec.pref.principle,
            }),
            reason: BRAIN_RETIRED_REASON.quarantineViolated,
          });
        } else {
          plan.retires.push({
            slug,
            principle: rec.pref.principle,
            reason: BRAIN_RETIRED_REASON.quarantineViolated,
          });
          // Skip refresh β€” moveToRetired will read the on-disk
          // counters when it builds the retired snapshot.
          continue;
        }
      } else if (applied > violated) {
        status = BRAIN_PREFERENCE_STATUS.confirmed;
      }
    }

    const baseConfidence = computeConfidence(applied, violated, lastEvidence, cfg, now);

    // Outcome regression (t_d478df53): applied events whose downstream
    // outcome was `failure` outnumbering `success` mean the rule looks
    // confirmed while actively hurting. The flag stages an explainable
    // finding and a multiplicative confidence penalty - retirement
    // still goes through the existing gates, never silently. The
    // penalty is a pure function of the evidence, so reruns converge.
    const appliedFailures = ev.filter(
      (e) => e.result === BRAIN_APPLY_RESULT.applied && e.outcome === "failure",
    ).length;
    const appliedSuccesses = ev.filter(
      (e) => e.result === BRAIN_APPLY_RESULT.applied && e.outcome === "success",
    ).length;
    const regressed =
      appliedFailures >= OUTCOME_REGRESSION_MIN_FAILURES && appliedFailures > appliedSuccesses;
    const confidence = regressed
      ? rebandConfidence(
          Math.round(baseConfidence.value * OUTCOME_REGRESSION_PENALTY * 10000) / 10000,
          cfg,
        )
      : baseConfidence;
    if (regressed) {
      outcomeRegressions.push({
        id: rec.pref.id,
        principle: rec.pref.principle,
        failures: appliedFailures,
        successes: appliedSuccesses,
      });
    }

    // Idempotency on a no-op rerun: skip refresh for prefs where
    // counters AND status are unchanged AND the on-disk body already
    // matches what we would render with current evidence. The second
    // half (body comparison) is what carries the v0.10.1 migration
    // forward β€” a pref whose counters are stable but whose body
    // still has the v0.9.x placeholder will fail the body check and
    // get rewritten on the next pass.
    const previousValue = rec.pref.confidence_value;
    // A `null` previous value (file not yet touched by dream) is
    // treated as "matches whatever we just computed" β€” the
    // body-bytes check in `wouldRewritePreference` is what triggers
    // the write that populates the field.
    const valueDifferent =
      previousValue !== null && Math.abs(previousValue - confidence.value) > 1e-6;
    const countersChanged =
      applied !== prior.applied ||
      violated !== prior.violated ||
      lastEvidence !== rec.pref.last_evidence_at ||
      status !== rec.pref.status ||
      confirmedAt !== rec.pref.confirmed_at ||
      confidence.band !== rec.pref.confidence ||
      valueDifferent;

    // Freshness trend (t_ee09a6ce): classified at PLAN time so the
    // no-op pre-flight below and the write loop render identical
    // bytes. The stamp is OPPORTUNISTIC: it lands when the pref is
    // being rewritten anyway (counters changed) or already carries
    // the field (then it refreshes on every consolidation pass, the
    // Hindsight contract). A never-stamped pref with unchanged
    // counters is left byte-identical so legacy vaults keep their
    // no-op dream guarantees.
    const stampTrend = countersChanged || rec.pref.freshness_trend !== undefined;
    let trendLabel: string | undefined;
    if (stampTrend) {
      const trendEv = collectEvidenceForSlug(vault, slug, {
        sinceIso: rec.pref.created_at,
        maxApplied: 1000,
        maxViolated: 1000,
      });
      trendLabel = classifyFreshnessTrend({
        createdAt: rec.pref.created_at,
        events: [...trendEv.applied, ...trendEv.violated].map((r) => ({
          at: r.timestamp,
          result: r.result,
        })),
        nowMs: now.getTime(),
      }).trend;
    }

    const prospective = {
      slug,
      topic: rec.pref.topic,
      ...(rec.pref.scope ? { scope: rec.pref.scope } : {}),
      principle: rec.pref.principle,
      created_at: rec.pref.created_at,
      unconfirmed_until: rec.pref.unconfirmed_until,
      status,
      evidenced_by: rec.pref.evidenced_by,
      confirmed_at: confirmedAt,
      applied_count: applied,
      violated_count: violated,
      last_evidence_at: lastEvidence,
      confidence: confidence.band,
      confidence_value: confidence.value,
      pinned: rec.pref.pinned,
      ...(trendLabel !== undefined ? { freshness_trend: trendLabel } : {}),
      // Carrying the derived-fact fields through the no-op pre-flight.
      // The renderer emits a non-default `provenance` and a non-empty
      // `related`, so a render that omitted them could never match a
      // preference that carries them (`deriveFact` output, the dream
      // pass's own cross-topic promotions): every pass would see the
      // file as "needs rewrite", and the txn's `_revision` auto-stamp
      // would then make each rewrite real, flipping every rerun into a
      // changed run forever. Absent stays absent, so prefs without
      // these fields render exactly the bytes they always did.
      ...(rec.pref.provenance !== undefined && rec.pref.provenance !== "stated"
        ? { provenance: rec.pref.provenance }
        : {}),
      ...(rec.pref.related !== undefined && rec.pref.related.length > 0
        ? { related: rec.pref.related }
        : {}),
      // The record's `visibility:` tokens ride along like provenance and
      // related above: the scan reads them off the raw frontmatter (the
      // typed parser drops the field), and only a render that includes
      // them can match a file that carries the line. Empty is default
      // visibility and stays absent, exactly like the writer's own rule.
      ...(rec.visibility !== undefined && rec.visibility.length > 0
        ? { visibility: rec.visibility }
        : {}),
    };

    if (!countersChanged) {
      const ev2 = collectEvidenceForSlug(vault, slug, {
        sinceIso: rec.pref.created_at,
      });
      if (
        !wouldRewritePreference(vault, {
          ...prospective,
          // Same lenient scope tags the write loop renders with.
          lenientScopeTags: true,
          recentApplied: ev2.applied,
          recentViolated: ev2.violated,
          // v0.12.0 Brain Integrity Suite: feed the existing
          // _revision and _content_hash into the pre-flight render
          // so the byte comparison matches the writePreferenceTxn
          // no-op semantic. Otherwise a refreshed pref written by a
          // prior pass (with _revision: N stamped) would look like
          // "needs rewrite" against a prospective render that omits
          // those fields, flipping changed=false runs into spurious
          // updates.
          // parsePreference defaults absent _revision to 0; treat 0
          // the same as "absent" for the pre-flight render so the
          // bytes-compare matches existing legacy starter files that
          // never had the field on disk.
          ...(rec.pref.revision !== undefined && rec.pref.revision > 0
            ? { revision: rec.pref.revision }
            : {}),
          ...(rec.pref.content_hash !== undefined ? { content_hash: rec.pref.content_hash } : {}),
        })
      ) {
        // Counters and body both unchanged β€” true no-op for this pref.
        continue;
      }
    }

    updated.set(slug, prospective);

    // Capture band drops for the digest. A drop is any transition
    // where the new band ranks lower than the previous (high β†’
    // medium, medium β†’ low, high β†’ low). Stable across re-runs as
    // long as the underlying counters do β€” the digest only renders
    // it when a real transition occurred in this pass.
    if (BAND_RANK[confidence.band] < BAND_RANK[rec.pref.confidence]) {
      bandDrops.push(
        Object.freeze({
          id: rec.pref.id,
          principle: rec.pref.principle,
          previous: rec.pref.confidence,
          next: confidence.band,
          applied,
          violated,
          previous_value: rec.pref.confidence_value,
          next_value: confidence.value,
        }),
      );
    }
  }

  return { confirmed, updated, bandDrops, outcomeRegressions };
}