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
9.4 KB
Raw Blame
/**
 * Single-step dream requests (no-dead-ends, Unit E).
 *
 * An operator sometimes wants one piece of the dream pass rather than the
 * whole thing. Most of the pass cannot serve that request, and the honest
 * answer is a named refusal rather than a partial run:
 *
 *   - The five `DREAM_PHASE` labels are a REPORTING layer. Their metrics
 *     are assembled after all work completes, from counters produced by
 *     different functions; there is no function named `close`,
 *     `reconcile`, `synthesize`, `heal` or `log` to call.
 *   - `planRefresh` and `planAutoRetires` are two-way mutably coupled:
 *     `planRefresh` pushes into `plan.retires`, and `planAutoRetires`
 *     deletes those slugs out of `refresh.updated`, precisely so that a
 *     preference is never both refreshed and retired in one pass. Running
 *     either alone with writes enabled is a data-correctness bug, not a
 *     missing feature.
 *
 * Exactly two units of work are provably independent, and this module
 * offers those two and refuses everything else by name:
 *
 *   - `scan` - {@link scanBrain}, a pure read of the `Brain/` tree. It
 *     opens no writer, takes no clock and mutates nothing.
 *   - `heal-enrich` - {@link runHealEnrichment}, the opt-in deterministic
 *     vault enrichment. It reads and rewrites user pages outside the Brain
 *     root and shares no accumulator with the planning steps. Asking for
 *     it IS the opt-in, so it runs regardless of
 *     `dream.heal_enrich_enabled`; that config key gates the automatic
 *     pass, and `DreamOptions.gates` overrides it for one full run.
 *
 * ## What a partial run returns
 *
 * NOT a `DreamRunSummary`. Almost every field of that record is
 * produced by steps a single-step request does not run, so returning one
 * would assert `retired: []` and `changed: false` about work that never
 * happened - a misleading fallback of exactly the kind this release
 * removes. Each step returns its own shape instead, discriminated by
 * `step` and marked `partial: true`, carrying only what that step actually
 * observed or did.
 */

import { scanBrain } from "./dream.ts";
import { DREAM_PHASE, type DreamPhase } from "./dream-phases.ts";
import { runHealEnrichment } from "./heal-run.ts";
import { vaultRelative } from "./paths.ts";
import type { ProgressSink } from "./progress.ts";
import type { Safeguard } from "./safeguard.ts";

/** The units of dream work that are provably runnable on their own. */
export const DREAM_STEP = Object.freeze({
  scan: "scan",
  healEnrich: "heal-enrich",
} as const);

export type DreamStep = (typeof DREAM_STEP)[keyof typeof DREAM_STEP];

/** Canonical order the refusal message lists the runnable steps in. */
export const DREAM_STEP_RUNNABLE: ReadonlyArray<DreamStep> = Object.freeze([
  DREAM_STEP.scan,
  DREAM_STEP.healEnrich,
]);

/**
 * Why each reporting label cannot be honoured on its own. One entry per
 * `DREAM_PHASE` member: a caller asking for a phase gets the reason for
 * THAT phase, never a generic "unsupported" line.
 */
const PHASE_REFUSAL: Readonly<Record<DreamPhase, string>> = Object.freeze({
  [DREAM_PHASE.close]:
    `it labels both the read scan and the pre-run snapshot that the mutating pass rolls back to, ` +
    `and a snapshot outside a run has nothing to protect; its read half is the '${DREAM_STEP.scan}' step`,
  [DREAM_PHASE.reconcile]:
    `it classifies contradictions over the plan that planTopics builds in the same pass, and records ` +
    `the outcome as run-log events; it owns no state of its own to run against`,
  [DREAM_PHASE.synthesize]:
    `planRefresh and planAutoRetires mutate each other's accumulators - planRefresh pushes into ` +
    `plan.retires and planAutoRetires deletes those slugs out of refresh.updated - so that a ` +
    `preference is never both refreshed and retired; running the refresh half alone with writes ` +
    `enabled would write a preference that the same pass had decided to retire`,
  [DREAM_PHASE.heal]:
    `its retire half is the other side of the planRefresh/planAutoRetires accumulator coupling ` +
    `(planAutoRetires deletes from refresh.updated the slugs planRefresh queued into plan.retires), ` +
    `so retiring alone would drop a refresh the same pass computed; its enrichment half is ` +
    `available on its own as the '${DREAM_STEP.healEnrich}' step`,
  [DREAM_PHASE.log]:
    `it writes the run summary and audit events describing work that a single-step request did not ` +
    `perform, so running it alone would record a pass that never happened`,
});

/** Reason given for a token that is not even a reporting label. */
const UNKNOWN_STEP_REFUSAL =
  "it is neither a runnable dream step nor one of the dream reporting phases";

/**
 * Raised when a caller asks for a step the dream pass cannot perform in
 * isolation. Carries the requested token, the steps that ARE runnable, and
 * the specific reason - so an agent reading only the error knows both why
 * it was refused and what it may ask for instead.
 */
export class DreamStepNotRunnableError extends Error {
  /** The token the caller asked for, verbatim. */
  readonly requested: string;
  /** The steps {@link runDreamStep} does honour. */
  readonly runnable: ReadonlyArray<DreamStep>;
  /** Why {@link requested} specifically cannot be run alone. */
  readonly reason: string;

  constructor(requested: string, reason: string) {
    super(
      `dream step '${requested}' is not independently runnable: ${reason}. ` +
        `Independently runnable steps: ${DREAM_STEP_RUNNABLE.join(", ")}. ` +
        `Everything else runs only as part of a full dream() pass.`,
    );
    this.name = "DreamStepNotRunnableError";
    this.requested = requested;
    this.runnable = DREAM_STEP_RUNNABLE;
    this.reason = reason;
  }
}

/** Result of the `scan` step: what the read saw, and nothing more. */
export interface DreamScanStepResult {
  readonly step: typeof DREAM_STEP.scan;
  /** Always true: this is one step of the pass, not a run summary. */
  readonly partial: true;
  /** Signals still in `inbox/`. */
  readonly active_signals: number;
  /** Signals already in `inbox/processed/`. */
  readonly processed_signals: number;
  /** Signals in `inbox/archived/` (left the contradiction window unconsumed). */
  readonly archived_signals: number;
  readonly preferences: number;
  readonly retired: number;
  /** Vault-relative paths whose frontmatter would not parse. */
  readonly corrupted: ReadonlyArray<string>;
}

/** Result of the `heal-enrich` step: what the enrichment rewrote. */
export interface DreamHealEnrichStepResult {
  readonly step: typeof DREAM_STEP.healEnrich;
  /** Always true: this is one step of the pass, not a run summary. */
  readonly partial: true;
  /** User pages considered (the Brain root is never touched). */
  readonly scanned: number;
  readonly enriched: number;
  /** Paths actually rewritten, sorted. */
  readonly pages: ReadonlyArray<string>;
}

export type DreamStepResult = DreamScanStepResult | DreamHealEnrichStepResult;

/**
 * What a caller may hand a single-step request.
 *
 * A step is a whole call, not a phase of one: nothing above it holds a
 * deadline or a stream, so both belong here and both are forwarded
 * unchanged to whichever step runs. This is a DISPATCHER over two units
 * of work and owns no counter of its own - each step opens exactly one
 * stream, named for the stage it is - which is the same shape the
 * maintenance lane takes over its four tasks, and for the same reason: a
 * second counter here would put two terminators on one run.
 *
 * Until this existed the MCP `step` branch passed neither, so a step over
 * a large tree held the server's event loop with no upper bound and said
 * nothing while it did.
 */
export interface DreamStepOptions {
  /** Cooperative deadline, honoured at the step's own iteration boundary. */
  readonly safeguard?: Safeguard;
  /** Where the step reports; absence means nobody asked. */
  readonly onProgress?: ProgressSink;
}

/**
 * Run exactly one dream step, or refuse by name.
 *
 * Never runs more than was asked and never runs less: a request this
 * function cannot honour in full throws {@link DreamStepNotRunnableError}
 * and writes nothing.
 */
export function runDreamStep(
  vault: string,
  step: string,
  opts: DreamStepOptions = {},
): DreamStepResult {
  switch (step) {
    case DREAM_STEP.scan: {
      const scan = scanBrain(vault, opts);
      return Object.freeze({
        step: DREAM_STEP.scan,
        partial: true,
        active_signals: scan.signals.filter((s) => s.active).length,
        processed_signals: scan.signals.filter((s) => !s.active && !s.archived).length,
        archived_signals: scan.signals.filter((s) => s.archived).length,
        preferences: scan.preferences.length,
        retired: scan.retired.length,
        corrupted: Object.freeze(scan.corrupted.map((c) => vaultRelative(c.path, vault))),
      } satisfies DreamScanStepResult);
    }
    case DREAM_STEP.healEnrich: {
      const result = runHealEnrichment(vault, opts);
      return Object.freeze({
        step: DREAM_STEP.healEnrich,
        partial: true,
        scanned: result.scanned,
        enriched: result.enriched,
        pages: Object.freeze([...result.pages]),
      } satisfies DreamHealEnrichStepResult);
    }
    default:
      throw new DreamStepNotRunnableError(step, refusalReason(step));
  }
}

/** The specific reason for a refused token. */
function refusalReason(step: string): string {
  return Object.hasOwn(PHASE_REFUSAL, step)
    ? PHASE_REFUSAL[step as DreamPhase]
    : UNKNOWN_STEP_REFUSAL;
}