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.2 KB
Raw Blame
/**
 * `findStaleEntries(index, vault, cfg, opts)` - reports preferences,
 * signals, and log files that have been idle past their configured
 * threshold.
 *
 * The TimelineIndex contributes the most-recent event timestamp per
 * preference - that's the canonical staleness anchor (more accurate
 * than `last_evidence_at` on disk, which lags behind the dream pass).
 * Falls back to the file's own `last_evidence_at` / `created_at` when
 * no event is on the timeline.
 *
 * Design anchor: `docs/brainstorm/temporal-synthesis/design.md`,
 * Task 5 in `plan.md`.
 */

import { existsSync, readdirSync } from "node:fs";
import { join } from "node:path";

import { brainDirs } from "./../paths.ts";
import { vaultRelative } from "../../path-safety.ts";
import { memoryFromStore, memoryRecordReads, signalPageRaw } from "../memory-pages.ts";
import { parsePreference, parsePreferenceMeta } from "./../preference.ts";
import { parseSignal, parseStoreSignal } from "./../signal.ts";
import { fileAgeMs, msToWholeDays } from "./../time.ts";
import type { ResolvedBrainTemporalConfig } from "./../types.ts";
import type { TimelineIndex } from "./types.ts";

export interface FindStaleEntriesOptions {
  /** Wall clock; defaults to `new Date()`. */
  readonly now?: Date;
}

export interface StalePreferenceRow {
  readonly prefId: string;
  readonly topic: string;
  readonly path: string;
  /** ISO timestamp of the most-recent event used as the staleness anchor. */
  readonly lastSeenAt: string;
  /** Whole days between `lastSeenAt` and `now`. */
  readonly ageDays: number;
}

export interface StaleSignalRow {
  readonly signalId: string;
  readonly topic: string;
  readonly path: string;
  readonly lastSeenAt: string;
  readonly ageDays: number;
}

export interface StaleLogFileRow {
  readonly path: string;
  readonly mtime: string;
  readonly ageDays: number;
}

export interface StaleWatchEnvelope {
  readonly stalePreferences: ReadonlyArray<StalePreferenceRow>;
  readonly staleSignals: ReadonlyArray<StaleSignalRow>;
  readonly staleLogFiles: ReadonlyArray<StaleLogFileRow>;
  readonly thresholds: ResolvedBrainTemporalConfig;
  readonly generatedAt: string;
}

export function findStaleEntries(
  index: TimelineIndex,
  vault: string,
  cfg: ResolvedBrainTemporalConfig,
  opts: FindStaleEntriesOptions = {},
): StaleWatchEnvelope {
  const now = opts.now ?? new Date();
  const generatedAt = now.toISOString();
  const nowMs = now.getTime();
  return Object.freeze({
    stalePreferences: Object.freeze(scanPreferences(index, vault, cfg.stale_pref_days, nowMs)),
    staleSignals: Object.freeze(scanSignals(vault, cfg.stale_signal_days, nowMs)),
    staleLogFiles: Object.freeze(scanLogFiles(vault, cfg.stale_log_days, nowMs)),
    thresholds: cfg,
    generatedAt,
  });
}

function scanPreferences(
  index: TimelineIndex,
  vault: string,
  thresholdDays: number,
  nowMs: number,
): StalePreferenceRow[] {
  const out: StalePreferenceRow[] = [];
  const dirs = brainDirs(vault);
  const fromStore = memoryFromStore(vault);
  if (!fromStore && !existsSync(dirs.preferences)) return out;
  for (const { path, read } of memoryRecordReads(
    vault,
    fromStore,
    dirs.preferences,
    "pref-",
    parsePreference,
    (page) => parsePreferenceMeta(page.meta, page.path),
  )) {
    let pref;
    try {
      pref = read();
    } catch {
      continue;
    }
    const lastSeenAt =
      mostRecentEventAt(index, pref.id) ?? pref.last_evidence_at ?? pref.created_at;
    const ageDays = computeAgeDays(lastSeenAt, nowMs);
    if (ageDays === undefined) continue;
    if (ageDays < thresholdDays) continue;
    out.push(
      Object.freeze({
        prefId: pref.id,
        topic: pref.topic,
        path: vaultRelative(path, vault),
        lastSeenAt,
        ageDays,
      }),
    );
  }
  out.sort((a, b) => b.ageDays - a.ageDays);
  return out;
}

function scanSignals(vault: string, thresholdDays: number, nowMs: number): StaleSignalRow[] {
  const out: StaleSignalRow[] = [];
  const dirs = brainDirs(vault);
  const fromStore = memoryFromStore(vault);
  if (!fromStore && !existsSync(dirs.inbox)) return out;
  for (const { path, read } of memoryRecordReads(
    vault,
    fromStore,
    dirs.inbox,
    "sig-",
    parseSignal,
    (page) => parseStoreSignal(page.path, page.meta, signalPageRaw(page)),
  )) {
    let signal;
    try {
      signal = read();
    } catch {
      continue;
    }
    const ageDays = computeAgeDays(signal.created_at, nowMs);
    if (ageDays === undefined) continue;
    if (ageDays < thresholdDays) continue;
    out.push(
      Object.freeze({
        signalId: signal.id,
        topic: signal.topic,
        path: vaultRelative(path, vault),
        lastSeenAt: signal.created_at,
        ageDays,
      }),
    );
  }
  out.sort((a, b) => b.ageDays - a.ageDays);
  return out;
}

function scanLogFiles(vault: string, thresholdDays: number, nowMs: number): StaleLogFileRow[] {
  const out: StaleLogFileRow[] = [];
  // A store-only machine keeps its log in the store, not in day files: a
  // leftover legacy file is no live log entry to report as stale.
  if (memoryFromStore(vault)) return out;
  const dirs = brainDirs(vault);
  if (!existsSync(dirs.log)) return out;
  for (const entry of readdirSync(dirs.log, { withFileTypes: true })) {
    if (!entry.isFile()) continue;
    if (!entry.name.endsWith(".jsonl") && !entry.name.endsWith(".md")) continue;
    const path = join(dirs.log, entry.name);
    const ageMs = fileAgeMs(path, nowMs);
    // A log file this loop enumerated a moment ago that can no longer be
    // stat'ed is not a stale entry and is not an absent one either: the
    // scan cannot say. `StaleLogFileRow` has no reason field and the
    // envelope has no notice channel, so the honest surface is the one
    // this scan already used - the failure propagates - except that it now
    // names the scan and the file instead of arriving as a bare `ENOENT`
    // from a path the report never mentions. Skipping the row instead
    // would trade an unreadable log for a clean bill of health, which is
    // the failure mode this release exists to remove.
    if (ageMs === null) {
      throw new Error(`findStaleEntries: cannot read the mtime of log file ${path}`);
    }
    const mtimeMs = nowMs - ageMs;
    const ageDays = msToWholeDays(ageMs);
    if (ageDays < thresholdDays) continue;
    out.push(
      Object.freeze({
        path: vaultRelative(path, vault),
        mtime: new Date(mtimeMs).toISOString(),
        ageDays,
      }),
    );
  }
  out.sort((a, b) => b.ageDays - a.ageDays);
  return out;
}

function mostRecentEventAt(index: TimelineIndex, prefId: string): string | undefined {
  const events = index.eventsByPrefId.get(prefId);
  if (events === undefined || events.length === 0) return undefined;
  // events is sorted ascending; last element is most recent.
  return events[events.length - 1]!.at;
}

/**
 * Compute whole-day age between an anchor timestamp and `now`.
 * Returns `undefined` when the anchor is unparseable so the caller
 * can skip the row instead of emitting a `NaN` `ageDays`.
 */
function computeAgeDays(anchorIso: string, nowMs: number): number | undefined {
  const ms = Date.parse(anchorIso);
  if (!Number.isFinite(ms)) return undefined;
  return msToWholeDays(nowMs - ms);
}