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.2 KB
Raw Blame
/**
 * Event-time validity windows (Time-Aware Recall & Activation Suite,
 * t_b7191486).
 *
 * OSB stores bi-temporal frontmatter (`valid_from` / `valid_until` =
 * event time, file mtime = storage time) but time-range recall used to
 * filter on mtime alone - the classic storage-vs-event-time confusion
 * (the largest LongMemEval failure category). This module makes the
 * declared validity window the authority: a document passes a
 * `since`/`until` filter iff its validity interval INTERSECTS the query
 * window. Storage time is consulted only when no parseable event time
 * exists.
 *
 * Pure functions; the orchestrator (`search.ts`) supplies frontmatter
 * and the resolved range. Accepted value forms are bare ISO dates
 * (day-start for `valid_from`, day-end for `valid_until`, UTC) and ISO
 * datetimes - never relative phrases, which would make stored
 * frontmatter clock-dependent.
 */

import type { ResolvedTimeRange } from "./time-range.ts";
import { mtimeInRange } from "./time-range.ts";

export interface ValidityWindow {
  /** Event-time start (unix ms), or null when open / undeclared. */
  readonly validFromMs: number | null;
  /** Event-time end (unix ms, inclusive), or null when open / undeclared. */
  readonly validUntilMs: number | null;
  /** True when a declared value failed to parse (mtime fallback applies). */
  readonly invalid: boolean;
}

const ISO_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
const DAY_MS = 24 * 60 * 60 * 1000;

/** Parse one frontmatter validity value. `edge` picks day-bound snapping. */
function parseValidityPoint(raw: unknown, edge: "from" | "until"): number | null {
  if (typeof raw !== "string") {
    // YAML may parse a bare date into a Date object.
    if (raw instanceof Date && Number.isFinite(raw.getTime())) return raw.getTime();
    return null;
  }
  const text = raw.trim();
  if (text === "") return null;
  const date = ISO_DATE_RE.exec(text);
  if (date) {
    const ms = Date.UTC(Number(date[1]), Number(date[2]) - 1, Number(date[3]));
    const check = new Date(ms);
    if (
      check.getUTCFullYear() !== Number(date[1]) ||
      check.getUTCMonth() !== Number(date[2]) - 1 ||
      check.getUTCDate() !== Number(date[3])
    ) {
      return null;
    }
    return edge === "from" ? ms : ms + DAY_MS - 1;
  }
  if (text.includes("T") || text.includes("t")) {
    const hasOffset = /(?:z|[+-]\d{2}:?\d{2})$/i.test(text);
    const parsed = Date.parse(hasOffset ? text : `${text}Z`);
    if (Number.isFinite(parsed)) return parsed;
  }
  return null;
}

/**
 * Read the validity window off a document's frontmatter. Returns null
 * when neither field is declared; `invalid: true` when a declared
 * value failed to parse (the caller falls back to mtime and warns).
 */
export function parseValidityWindow(meta: Record<string, unknown>): ValidityWindow | null {
  const hasFrom = meta["valid_from"] !== undefined && meta["valid_from"] !== null;
  const hasUntil = meta["valid_until"] !== undefined && meta["valid_until"] !== null;
  if (!hasFrom && !hasUntil) return null;
  const validFromMs = hasFrom ? parseValidityPoint(meta["valid_from"], "from") : null;
  const validUntilMs = hasUntil ? parseValidityPoint(meta["valid_until"], "until") : null;
  const invalid = (hasFrom && validFromMs === null) || (hasUntil && validUntilMs === null);
  return Object.freeze({ validFromMs, validUntilMs, invalid });
}

/**
 * Event-time range test: the validity interval must intersect the
 * query window. A null window (no validity fields) and an invalid one
 * both fall back to the mtime rule - never silently dropped.
 */
export function eventTimeInRange(
  window: ValidityWindow | null,
  mtimeSeconds: number,
  range: ResolvedTimeRange,
): boolean {
  if (window === null || window.invalid) return mtimeInRange(mtimeSeconds, range);
  // Interval overlap with open sides: the document's event span is
  // [validFrom, validUntil] (either side open), the query window is
  // [since, until] (either side open).
  if (range.untilMs !== null && window.validFromMs !== null && window.validFromMs > range.untilMs) {
    return false;
  }
  if (
    range.sinceMs !== null &&
    window.validUntilMs !== null &&
    window.validUntilMs < range.sinceMs
  ) {
    return false;
  }
  return true;
}