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
13.5 KB
Raw Blame
/**
 * Recurring obligations as first-class Brain entities (upstream parity
 * with obsidian-second-brain `/obsidian-recurring`, t_f7b82ba4).
 *
 * A recurring obligation is a periodic commitment - a weekly review, a
 * monthly report, a quarterly backup audit - that the operator wants
 * tracked with a cadence and a deterministically computed next-due
 * date. Each obligation is a Markdown page at
 * `Brain/obligations/<slug>.md`: operator-readable in Obsidian, greppable,
 * versionable. The kernel never calls a model - cadence arithmetic is
 * pure calendar math over UTC dates, so the same inputs always yield the
 * same next-due date.
 *
 *   - `add`    creates the page; `next_due` starts at the anchor date.
 *   - `done`   records a completion and advances `next_due` by one cadence
 *              interval from the completion date.
 *   - `list`   reads every page, sorted by next-due, with an overdue flag.
 *   - `show`   reads one page.
 *   - `remove` retires the page into `Brain/obligations/archive/`.
 */

import { join } from "node:path";

import { slugify } from "../vault.ts";
import { obligationPath, obligationsArchiveDir, obligationsDir, validateIsoDate } from "./paths.ts";
import { isoDate, isoSecond } from "./time.ts";
import {
  assertLaneWrite,
  lanePageExists,
  lanePagesInStore,
  listLaneFiles,
  moveLanePage,
  parseLanePage,
  readLaneFile,
  readLaneText,
  removeLanePage,
  writeLaneText,
} from "../store/lane-pages.ts";

/**
 * Supported cadences. Day-based cadences add a fixed number of days;
 * calendar cadences (`monthly`/`quarterly`/`yearly`) add whole months
 * with end-of-month clamping. `every-<N>-days` covers any custom
 * day interval (N ≥ 1).
 */
export type ObligationCadence =
  | "daily"
  | "weekly"
  | "biweekly"
  | "monthly"
  | "quarterly"
  | "yearly"
  | `every-${number}-days`;

const FIXED_CADENCE_DAYS: Record<string, number> = {
  daily: 1,
  weekly: 7,
  biweekly: 14,
};

const CALENDAR_CADENCE_MONTHS: Record<string, number> = {
  monthly: 1,
  quarterly: 3,
  yearly: 12,
};

const EVERY_N_DAYS_RE = /^every-(\d+)-days$/u;
const HISTORY_HEADER = "## Completions";

export interface ObligationPage {
  readonly slug: string;
  readonly title: string;
  readonly cadence: ObligationCadence;
  readonly createdAt: string;
  /** First due date; `next_due` derives from completions or this. */
  readonly anchor: string;
  /** Most recent completion date, or null if never completed. */
  readonly lastDone: string | null;
  /** Deterministically computed next due date (`YYYY-MM-DD`). */
  readonly nextDue: string;
  readonly agent: string;
  /** Completion dates, newest first. */
  readonly completions: ReadonlyArray<string>;
  readonly notes: string;
  readonly path: string;
}

export interface AddObligationInput {
  readonly title: string;
  readonly cadence: string;
  readonly agent: string;
  /** First due date (`YYYY-MM-DD`); defaults to today (UTC). */
  readonly anchor?: string;
  readonly notes?: string;
  readonly now?: Date;
}

export interface CompleteObligationInput {
  readonly slug: string;
  /** Completion date (`YYYY-MM-DD`); defaults to today (UTC). */
  readonly date?: string;
  readonly now?: Date;
}

export interface RemoveObligationResult {
  readonly slug: string;
  readonly archivePath: string;
}

export class ObligationError extends Error {}

/** The refusal for a slug that names no active obligation page. */
export function noObligationError(slug: string): ObligationError {
  return new ObligationError(`no obligation: ${slug}`);
}

/** Validate and narrow an arbitrary cadence string. */
export function parseCadence(raw: string): ObligationCadence {
  const value = raw.trim().toLowerCase();
  if (value in FIXED_CADENCE_DAYS || value in CALENDAR_CADENCE_MONTHS) {
    return value as ObligationCadence;
  }
  const match = EVERY_N_DAYS_RE.exec(value);
  if (match) {
    const n = Number.parseInt(match[1]!, 10);
    if (n >= 1) return `every-${n}-days`;
  }
  throw new ObligationError(
    `unknown cadence: ${JSON.stringify(raw)} (expected daily, weekly, biweekly, monthly, quarterly, yearly, or every-<N>-days)`,
  );
}

function requireIsoDate(value: string, label: string): string {
  try {
    validateIsoDate(value);
  } catch {
    throw new ObligationError(`${label} is not a valid calendar date: ${JSON.stringify(value)}`);
  }
  return value;
}

/**
 * Soft-parse an ISO date read from disk: return it when it is a valid
 * calendar date, otherwise return the empty string. Unlike
 * {@link requireIsoDate} this never throws, because a frontmatter value
 * edited by hand should not crash listing/rendering of the whole page.
 */
function parseIsoDate(value: unknown): string {
  if (typeof value !== "string") return "";
  try {
    validateIsoDate(value);
    return value;
  } catch {
    return "";
  }
}

function lastDayOfMonth(year: number, monthZeroBased: number): number {
  // Day 0 of the next month is the last day of this month.
  return new Date(Date.UTC(year, monthZeroBased + 1, 0)).getUTCDate();
}

function addMonths(date: string, months: number): string {
  const [y, m, d] = date.split("-").map((part) => Number.parseInt(part, 10)) as [
    number,
    number,
    number,
  ];
  const targetIndex = m - 1 + months;
  const targetYear = y + Math.floor(targetIndex / 12);
  const targetMonth = ((targetIndex % 12) + 12) % 12;
  const clampedDay = Math.min(d, lastDayOfMonth(targetYear, targetMonth));
  const out = new Date(Date.UTC(targetYear, targetMonth, clampedDay));
  return isoDate(out);
}

function addDays(date: string, days: number): string {
  const ms = Date.parse(`${date}T00:00:00Z`) + days * 24 * 3600 * 1000;
  return isoDate(new Date(ms));
}

/**
 * Advance a date by exactly one cadence interval. Pure calendar math:
 * deterministic for a given (cadence, from) pair.
 */
export function nextDueDate(cadence: ObligationCadence, from: string): string {
  requireIsoDate(from, "from");
  if (cadence in FIXED_CADENCE_DAYS) return addDays(from, FIXED_CADENCE_DAYS[cadence]!);
  if (cadence in CALENDAR_CADENCE_MONTHS) return addMonths(from, CALENDAR_CADENCE_MONTHS[cadence]!);
  const match = EVERY_N_DAYS_RE.exec(cadence);
  if (match) return addDays(from, Number.parseInt(match[1]!, 10));
  throw new ObligationError(`unknown cadence: ${JSON.stringify(cadence)}`);
}

function render(page: Omit<ObligationPage, "path">): string {
  const completions =
    page.completions.length === 0
      ? ""
      : `\n${HISTORY_HEADER}\n\n${page.completions.map((c) => `- ${c}`).join("\n")}\n`;
  const lines = [
    "---",
    `title: ${JSON.stringify(page.title)}`,
    `cadence: ${page.cadence}`,
    `created_at: ${page.createdAt}`,
    `anchor: ${page.anchor}`,
    `last_done: ${page.lastDone ?? ""}`,
    `next_due: ${page.nextDue}`,
    `agent: ${JSON.stringify(page.agent)}`,
    "---",
    "",
    page.notes,
    completions,
  ];
  return lines.join("\n");
}

function parsePage(vault: string, slug: string): ObligationPage | null {
  const path = obligationPath(vault, slug);
  if (!lanePageExists(vault, path)) return null;
  const [meta, body] = parseLanePage(vault, path);
  const cadenceRaw = typeof meta["cadence"] === "string" ? meta["cadence"] : "";
  let cadence: ObligationCadence;
  try {
    cadence = parseCadence(cadenceRaw);
  } catch {
    return null;
  }
  const headerMatch = /^## Completions$/mu.exec(body);
  const headerIndex = headerMatch?.index ?? -1;
  const notes = (headerIndex < 0 ? body : body.slice(0, headerIndex)).trim();
  const completions: string[] = [];
  if (headerIndex >= 0) {
    for (const line of body.slice(headerIndex + HISTORY_HEADER.length).split("\n")) {
      const trimmed = line.trim();
      if (trimmed.startsWith("- ")) completions.push(trimmed.slice(2));
    }
  }
  const lastDoneRaw = typeof meta["last_done"] === "string" ? meta["last_done"].trim() : "";
  // Full calendar validation (not just format): "2024-02-30" would
  // otherwise pass a regex and then yield NaN in the due/overdue math.
  const anchor = parseIsoDate(meta["anchor"]);
  const nextDue = parseIsoDate(meta["next_due"]) || anchor;
  return Object.freeze({
    slug,
    title: typeof meta["title"] === "string" ? meta["title"] : slug,
    cadence,
    createdAt: typeof meta["created_at"] === "string" ? meta["created_at"] : "",
    anchor,
    lastDone: lastDoneRaw.length > 0 ? lastDoneRaw : null,
    nextDue,
    agent: typeof meta["agent"] === "string" ? meta["agent"] : "",
    completions: Object.freeze(completions),
    notes,
    path,
  });
}

/** Create a recurring obligation page. */
export function addObligation(vault: string, input: AddObligationInput): ObligationPage {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertLaneWrite(vault);
  const title = input.title.trim();
  if (title.length === 0) throw new ObligationError("obligation title must not be empty");
  const cadence = parseCadence(input.cadence);
  const now = input.now ?? new Date();
  const today = isoDate(now);
  const anchor = input.anchor ? requireIsoDate(input.anchor, "anchor") : today;
  const slug = slugify(title);
  if (lanePageExists(vault, obligationPath(vault, slug))) {
    throw new ObligationError(`obligation already exists: ${slug} (remove it first to recreate)`);
  }
  const page = {
    slug,
    title,
    cadence,
    createdAt: isoSecond(now),
    anchor,
    lastDone: null,
    // The first occurrence is the anchor itself.
    nextDue: anchor,
    agent: input.agent,
    completions: Object.freeze([] as string[]),
    notes: (input.notes ?? "").trim(),
  };
  const path = obligationPath(vault, slug);
  writeLaneText(vault, path, render(page));
  return Object.freeze({ ...page, path });
}

/** Record a completion and advance next-due by one cadence interval. */
export function completeObligation(vault: string, input: CompleteObligationInput): ObligationPage {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertLaneWrite(vault);
  const slug = slugify(input.slug);
  const prior = parsePage(vault, slug);
  if (prior === null) throw noObligationError(slug);
  const now = input.now ?? new Date();
  const date = input.date ? requireIsoDate(input.date, "date") : isoDate(now);
  const page = {
    slug: prior.slug,
    title: prior.title,
    cadence: prior.cadence,
    createdAt: prior.createdAt,
    anchor: prior.anchor,
    lastDone: date,
    nextDue: nextDueDate(prior.cadence, date),
    agent: prior.agent,
    completions: Object.freeze([date, ...prior.completions]),
    notes: prior.notes,
  };
  writeLaneText(vault, prior.path, render(page));
  return Object.freeze({ ...page, path: prior.path });
}

/** One obligation, or null. */
export function showObligation(vault: string, slug: string): ObligationPage | null {
  return parsePage(vault, slugify(slug));
}

/**
 * True when an active obligation page already exists for `slug`. Lets callers
 * (e.g. the inbox-drain pass) detect a same-title collision structurally
 * before attempting a create that {@link addObligation} would reject.
 */
export function obligationExists(vault: string, slug: string): boolean {
  return lanePageExists(vault, obligationPath(vault, slugify(slug)));
}

export interface ObligationListItem extends ObligationPage {
  /** True when next-due is strictly before today (UTC). */
  readonly overdue: boolean;
  /** Whole days until next-due; negative when overdue. */
  readonly daysUntilDue: number;
}

/** Active obligations sorted by next-due (earliest first), then slug. */
export function listObligations(
  vault: string,
  options: { now?: Date; overdueOnly?: boolean } = {},
): ObligationListItem[] {
  const dir = obligationsDir(vault);
  if (!lanePageExists(vault, dir)) return [];
  const today = isoDate(options.now ?? new Date());
  const todayMs = Date.parse(`${today}T00:00:00Z`);
  const out: ObligationListItem[] = [];
  for (const name of listLaneFiles(vault, dir, "")) {
    if (!name.endsWith(".md")) continue;
    const page = parsePage(vault, name.replace(/\.md$/u, ""));
    if (page === null) continue;
    const dueMs = Date.parse(`${page.nextDue}T00:00:00Z`);
    const daysUntilDue = Number.isNaN(dueMs)
      ? 0
      : Math.round((dueMs - todayMs) / (24 * 3600 * 1000));
    const overdue = !Number.isNaN(dueMs) && dueMs < todayMs;
    if (options.overdueOnly && !overdue) continue;
    out.push(Object.freeze({ ...page, overdue, daysUntilDue }));
  }
  return out.toSorted((a, b) => {
    if (a.nextDue !== b.nextDue) return a.nextDue < b.nextDue ? -1 : 1;
    return a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0;
  });
}

/** Retire an obligation into Brain/obligations/archive/. */
export function removeObligation(vault: string, slug: string): RemoveObligationResult {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertLaneWrite(vault);
  const normalized = slugify(slug);
  const activePath = obligationPath(vault, normalized);
  if (!lanePageExists(vault, activePath)) throw noObligationError(normalized);
  const archiveDir = obligationsArchiveDir(vault);
  let archivePath = join(archiveDir, `${normalized}.md`);
  for (let suffix = 2; lanePageExists(vault, archivePath); suffix++) {
    archivePath = join(archiveDir, `${normalized}-${suffix}.md`);
  }
  try {
    moveLanePage(vault, activePath, archivePath);
  } catch (err) {
    // The store move is already one operation (tombstone and new entry in
    // one write): retrying it as two would leave the obligation both
    // active and archived. Only a legacy rename falls back to copy and
    // remove, and a page gone since the check still throws.
    if (lanePagesInStore(vault)) throw err;
    writeLaneText(vault, archivePath, readLaneFile(vault, activePath));
    removeLanePage(vault, activePath);
  }
  return Object.freeze({ slug: normalized, archivePath });
}