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.7 KB
Raw Blame
/**
 * The decisions a dream pass takes about its own outcome once the plan is
 * known: whether anything changes at all (the `changed` gate), the
 * non-fatal warnings it reports, and the retire-sibling projection a
 * changed run's summary carries. Pure over the plan; split from
 * `dream.ts`, which sequences them.
 */

import { resolveNearDuplicateRetireSiblingsEnabled } from "../config.ts";
import { shouldGateRetireFromConfirmed } from "./dream-apply.ts";
import type { PlanState, ScanResult } from "./dream-plan.ts";
import type { RefreshResult } from "./dream-refresh.ts";
import type { DreamGatedRetireEntry, DreamRunSummary, DreamWarning } from "./dream-types.ts";
import { READ_ALL_REFS } from "./near-duplicate.ts";
import { planRetireSiblings, retireSiblingPool } from "./retire-siblings.ts";
import type { RollupLadderPlan } from "./rollup-ladder.ts";

/**
 * Attach the retire-sibling projection (near-duplicate defense) to a
 * changed run's summary. Computed from the completed retire plan, then
 * reconciled against the retires the confirmed-evidence gate holds back:
 * the ones the apply step gated, or on a dry run the ones it would gate,
 * so the dry run and the real run agree. A retiring preference is never
 * refreshed first, so its scanned frontmatter is what the apply step
 * reads. The scan is the pass's own reach (a preview scan is already
 * admitted), hence {@link READ_ALL_REFS}. Off (`enabled`, else the
 * default config's key), or with nothing to report, the summary is
 * returned untouched.
 */
export function withRetireSiblings(
  summary: DreamRunSummary,
  scan: ScanResult,
  plan: PlanState,
  opts: {
    readonly enabled: boolean | undefined;
    readonly gatedRetires: ReadonlyArray<DreamGatedRetireEntry>;
    readonly previewGateThreshold: number | undefined;
  },
): DreamRunSummary {
  if (plan.retires.length === 0 || !(opts.enabled ?? resolveNearDuplicateRetireSiblingsEnabled())) {
    return summary;
  }
  const gated = new Set(opts.gatedRetires.map((g) => g.pref_id));
  if (opts.previewGateThreshold !== undefined) {
    const byId = new Map(scan.preferences.map((p) => [p.pref.id, p.pref] as const));
    for (const r of plan.retires) {
      const existing = byId.get(`pref-${r.slug}`);
      if (
        existing !== undefined &&
        shouldGateRetireFromConfirmed(existing, r.reason, opts.previewGateThreshold)
      ) {
        gated.add(existing.id);
      }
    }
  }
  const siblings = planRetireSiblings(
    retireSiblingPool(scan.preferences.map((p) => p.pref)),
    plan.retires.map((r) => ({ id: `pref-${r.slug}`, principle: r.principle, reason: r.reason })),
    { readable: READ_ALL_REFS, gated },
  );
  if (siblings.length === 0) return summary;
  return Object.freeze({ ...summary, retire_siblings: Object.freeze([...siblings]) });
}

/**
 * Non-fatal warnings raised during the run. The non-primary-dream-run
 * check is the first one: when the caller declares an agent name and it
 * differs from the vault's declared primary, surface a structured
 * warning. We do NOT abort — the declaration is observability, not
 * access control.
 */
export function collectWarnings(
  isNonPrimary: boolean,
  callerAgent: string,
  primaryAgent: string | null,
): DreamWarning[] {
  if (!isNonPrimary) return [];
  return [
    {
      code: "non-primary-dream-run",
      message:
        `dream run from agent '${callerAgent}', but primary is ` +
        `'${primaryAgent}'. Convention violation, run proceeds.`,
    },
  ];
}

/**
 * Decide if anything is going to change. We treat any of the following
 * as a state change:
 *   - a new unconfirmed pref
 *   - a refreshed pref (counters/confidence/status changed)
 *   - a retire
 *   - a same-sign signal noted on an active pref (move + log)
 *   - an inbox signal archived because it left the contradiction window
 *   - a corrupted frontmatter (we want the skip event recorded)
 *   - any pinned-rebut-attempt warning
 *   - a fired rollup-ladder rung (S3)
 *   - a cross-topic rule promotion (t_642bc2b8)
 */
export function hasStateChange(
  plan: PlanState,
  refresh: RefreshResult,
  corruptedCount: number,
  rollupPlan: RollupLadderPlan,
): boolean {
  return (
    plan.newUnconfirmed.length > 0 ||
    refresh.confirmed.size > 0 ||
    refresh.updated.size > 0 ||
    plan.retires.length > 0 ||
    plan.notedRedundant.length > 0 ||
    plan.signalsToMove.size > 0 ||
    plan.signalsToArchive.size > 0 ||
    plan.retainPinned.length > 0 ||
    plan.signalsSuppressed.length > 0 ||
    // v0.10.16: quarantine is a recorded decision (deferred-but-noted),
    // so a run that produces only quarantine entries is still a
    // meaningful run from the operator's perspective.
    plan.quarantined.length > 0 ||
    plan.crossTopicRules.length > 0 ||
    rollupPlan.fired ||
    corruptedCount > 0
  );
}