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
3.0 KB
Raw Blame
/**
 * Pure debounce/coalesce planner for the file-watcher index sync (Unit 3
 * of the Vault Integrity & Trust suite).
 *
 * A vault edit fires a burst of filesystem events; re-indexing on every
 * raw event would thrash. This planner answers one question - "which
 * changed paths have been quiet long enough to index now?" - given an
 * explicit clock value. It is deliberately dependency-free and never
 * reads the clock itself, so the coalescing behaviour is deterministic
 * and unit-testable without a real `fs.watch` or timers.
 *
 * The lifecycle around it (the CLI verb) owns the OS watcher, the timer
 * that calls {@link take}, and the single-flight guard that prevents
 * overlapping index passes. The planner owns no I/O.
 */

export interface IndexWatchPlannerOptions {
  /**
   * Quiet window in milliseconds. A path is due only once no further
   * change has been recorded for it within this window. Each new change
   * to the same path resets its window, so a file under continuous
   * editing is indexed once it settles rather than on every keystroke.
   */
  readonly debounceMs: number;
}

export class IndexWatchPlanner {
  private readonly debounceMs: number;
  private readonly lastSeen = new Map<string, number>();

  constructor(opts: IndexWatchPlannerOptions) {
    if (!Number.isFinite(opts.debounceMs) || opts.debounceMs < 0) {
      throw new Error(
        `IndexWatchPlanner debounceMs must be a non-negative finite number, got ${opts.debounceMs}`,
      );
    }
    this.debounceMs = opts.debounceMs;
  }

  /** Number of paths currently waiting out their quiet window. */
  get pendingCount(): number {
    return this.lastSeen.size;
  }

  /** Record a change to `path` observed at `atMs`, resetting its window. */
  record(path: string, atMs: number): void {
    this.lastSeen.set(path, atMs);
  }

  /**
   * Paths whose quiet window has fully elapsed as of `now`, sorted for
   * deterministic output. Non-mutating - use {@link take} to also remove
   * them.
   */
  due(now: number): string[] {
    const out: string[] = [];
    for (const [path, seen] of this.lastSeen) {
      if (now - seen >= this.debounceMs) out.push(path);
    }
    return out.toSorted();
  }

  /**
   * Return the due paths (see {@link due}) and remove them from the
   * pending set, so the caller can hand them to one index pass without
   * re-flushing them next tick. Paths still inside their window stay
   * pending.
   */
  take(now: number): string[] {
    const ready = this.due(now);
    for (const path of ready) this.lastSeen.delete(path);
    return ready;
  }

  /**
   * Earliest wall-clock time at which some pending path becomes due, or
   * `null` when nothing is pending. Lets the lifecycle sleep until the
   * next flush instead of polling on a fixed interval.
   */
  nextDueAt(): number | null {
    let min: number | null = null;
    for (const seen of this.lastSeen.values()) {
      const due = seen + this.debounceMs;
      if (min === null || due < min) min = due;
    }
    return min;
  }
}