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
7.0 KB
Raw Blame
/**
 * Inbox archive policy (issue #195): which inbox signals can no longer
 * become candidates, and so leave `Brain/inbox/` for `Brain/inbox/archived/`.
 *
 * ## The rule
 *
 * An inbox signal is archivable when its `created_at` parses and lies
 * strictly before `now - dream.contradiction_window_days`.
 *
 * That is exactly the complement of `filterWithinWindow`, the filter every
 * counting path of the dream pass goes through: promotion, redundancy,
 * rebuttal and the contradiction classifier all count windowed signals only.
 * A signal outside the window therefore contributes to no candidate, and
 * because time only moves forward it never will again. Singletons, topics
 * below the promotion threshold, quarantined clusters and contended keys all
 * reduce to this one rule: while a signal is inside the window it stays,
 * whatever its topic's state, and once it has left the window no state of
 * its topic can make it count.
 *
 * Deliberately NOT archivable:
 *
 *   - a signal whose `created_at` does not parse. It can never count either,
 *     but it is malformed, and moving it would hide the defect from the
 *     doctor checks that report it;
 *   - a signal past its `expiration_date` but still inside the window. The
 *     dream pass does not read `expiration_date` (expiry filters READ
 *     surfaces, see `expiration.ts`), so such a signal still counts toward a
 *     candidate today, and archiving it would change a promotion outcome.
 *     Once it leaves the window it is archived like any other;
 *   - a signal the same pass consumes (promotes, notes redundant, suppresses
 *     or spends on a rebuttal). Those go to `processed/` as before;
 *   - a signal whose file name is already taken in the archive, by any
 *     entry of `inbox/archived/` (a tombstoned or unparseable file there
 *     takes the name as much as a live one). The move never overwrites; the
 *     collision is reported as a warning instead and plans nothing;
 *   - a tombstoned inbox signal. The scan never reads one, so it is not a
 *     candidate and not a record the plan can move. A tombstone is an
 *     operator decision about that file, recorded in place, and tombstones
 *     are bounded by operator actions rather than by capture volume, so the
 *     inbox stays bounded without moving them.
 *
 * ## The clock
 *
 * The rule runs against `min(now, wall clock)` ({@link archiveClock}). A
 * pass run with `--now` in the future plans promotions for that instant,
 * but a move to the archive is not undone by a later pass, so it never
 * archives a signal that is still inside the window at the real time.
 *
 * Archiving is a move of the file, byte for byte. Nothing is deleted, and the
 * archive stays readable by the provenance and history readers.
 *
 * Pure: no I/O. The only clock read is {@link archiveClock}'s default
 * wall clock, which a caller can inject.
 */

import { basename } from "node:path";

import type { PlanState, ScanResult, SignalRecord } from "./dream-plan.ts";
import type { DreamWarning } from "./dream-types.ts";
import type { BrainConfig } from "./types.ts";

const DAY_MS = 24 * 60 * 60 * 1000;

/** Warning code for an inbox signal whose archive name is already taken. */
export const ARCHIVE_NAME_COLLISION_CODE = "archive-name-collision";

/** Whether the archive step is enabled; absent means enabled. */
export function archiveEnabled(cfg: BrainConfig): boolean {
  return cfg.dream.archive_stale_signals !== false;
}

/**
 * Whether one signal's `created_at` lies outside the contradiction window.
 * The exact complement of `filterWithinWindow` for a parseable timestamp;
 * an unparseable one is neither inside nor archivable.
 */
export function isOutsideWindow(createdAt: string, windowDays: number, now: Date): boolean {
  const t = Date.parse(createdAt);
  if (!Number.isFinite(t)) return false;
  return t < now.getTime() - windowDays * DAY_MS;
}

/**
 * The instant the archive rule runs against: `now`, or the wall clock when
 * `now` lies ahead of it (see "The clock" above).
 */
export function archiveClock(now: Date, wallClock: Date = new Date()): Date {
  return now.getTime() > wallClock.getTime() ? wallClock : now;
}

/** The archive rule's verdict over a set of signal records. */
export interface ArchiveSelection {
  /** Active inbox signals the rule archives, in record order. */
  readonly archivable: ReadonlyArray<SignalRecord>;
  /** Active inbox signals the rule would archive but whose name is taken. */
  readonly collisions: ReadonlyArray<SignalRecord>;
}

/**
 * Apply the archive rule to `signals`: every active record whose
 * `created_at` lies outside the window at {@link archiveClock}`(now)`,
 * split by whether its file name is free in the archive. `archivedNames`
 * is the listing of `inbox/archived/`, every entry of it.
 *
 * The one selection both the dream plan and the `inbox-archivable` doctor
 * check go through, so the doctor's count is what a dry run archives less
 * the signals that pass consumes instead.
 */
export function selectArchivableSignals(
  signals: ReadonlyArray<SignalRecord>,
  archivedNames: ReadonlySet<string>,
  windowDays: number,
  now: Date,
): ArchiveSelection {
  const clock = archiveClock(now);
  const archivable: SignalRecord[] = [];
  const collisions: SignalRecord[] = [];
  for (const rec of signals) {
    if (!rec.active || !isOutsideWindow(rec.signal.created_at, windowDays, clock)) continue;
    if (archivedNames.has(basename(rec.path))) collisions.push(rec);
    else archivable.push(rec);
  }
  return { archivable, collisions };
}

/**
 * Plan the archive step onto `plan.signalsToArchive`. Runs after the topic
 * plan, so a signal the pass consumes is never archived. Returns the
 * warnings the step raised (name collisions).
 */
export function planSignalArchive(
  scan: ScanResult,
  cfg: BrainConfig,
  now: Date,
  plan: PlanState,
): DreamWarning[] {
  if (!archiveEnabled(cfg)) return [];
  const { archivable, collisions } = selectArchivableSignals(
    scan.signals,
    scan.archivedNames ?? archivedRecordNames(scan),
    cfg.dream.contradiction_window_days,
    now,
  );
  const consumed = (rec: SignalRecord): boolean =>
    plan.signalsToMove.has(rec.signal.id) || plan.signalsToArchive.has(rec.signal.id);
  const warnings: DreamWarning[] = [];
  for (const rec of collisions) {
    if (consumed(rec)) continue;
    const name = basename(rec.path);
    warnings.push({
      code: ARCHIVE_NAME_COLLISION_CODE,
      message:
        `signal ${rec.signal.id} is outside the contradiction window but inbox/archived/${name} ` +
        `already exists; it stays in the inbox. Compare the two files and remove the ` +
        `duplicate by hand.`,
    });
  }
  for (const rec of archivable) {
    if (consumed(rec)) continue;
    const id = rec.signal.id;
    plan.signalsToArchive.set(id, { id, path: rec.path });
  }
  return warnings;
}

/**
 * Fallback for a scan built without a directory listing (a hand-made
 * fixture): the names of the archived records it holds.
 */
function archivedRecordNames(scan: ScanResult): ReadonlySet<string> {
  return new Set(scan.signals.filter((r) => r.archived).map((r) => basename(r.path)));
}