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.1 KB
Raw Blame
import { buildTimelineIndex } from "./temporal/build-index.ts";
import { collectTransitions } from "./temporal/period-common.ts";
import type { TemporalEvent } from "./temporal/types.ts";
import { BRAIN_APPLY_RESULT, BRAIN_LOG_EVENT_KIND } from "./types.ts";

export interface MonthlyReviewWindow {
  readonly since: string;
  readonly until: string;
}

export interface MonthlyReviewSummary {
  readonly events: number;
  readonly status_transitions: number;
  readonly retired: number;
  readonly contradictions: number;
  readonly neglected_areas: ReadonlyArray<string>;
}

export interface MonthlyReviewReport {
  readonly schema_version: 1;
  readonly generated_at: string;
  readonly month: string;
  readonly window: MonthlyReviewWindow;
  readonly summary: MonthlyReviewSummary;
}

export interface BuildMonthlyReviewOptions {
  /** Target month in `YYYY-MM` form. Defaults to current UTC month. */
  readonly month?: string;
  readonly now?: Date;
  /** Optional area labels expected to show activity in the month. */
  readonly expectedAreas?: ReadonlyArray<string>;
  /**
   * The form of one log event the caller may see, or `null` when it may
   * not see it at all. Applied once to the month's events before every
   * count, so a withheld event moves none of them. Omitted, every event
   * counts as logged (the operator's own shell).
   */
  readonly eventAtReach?: (ev: TemporalEvent) => TemporalEvent | null;
}

const MONTH_RE = /^\d{4}-\d{2}$/;

export function buildMonthlyReview(
  vault: string,
  options: BuildMonthlyReviewOptions = {},
): MonthlyReviewReport {
  const now = options.now ?? new Date();
  const month = normalizeMonthlyReviewMonth(options.month ?? now.toISOString().slice(0, 7));
  const window = monthWindow(month);
  const index = buildTimelineIndex(vault, window);
  const atReach = options.eventAtReach;
  const events =
    atReach === undefined ? index.events : index.events.flatMap((ev) => atReach(ev) ?? []);
  const transitions = collectTransitions(events);
  const retired = transitions.filter((transition) => transition.kind === "retirement").length;
  const contradictions = countContradictions(events);

  return Object.freeze({
    schema_version: 1 as const,
    generated_at: now.toISOString(),
    month,
    window,
    summary: Object.freeze({
      events: events.length,
      status_transitions: transitions.length,
      retired,
      contradictions,
      neglected_areas: Object.freeze(neglectedAreas(events, options.expectedAreas ?? [])),
    }),
  });
}

export function normalizeMonthlyReviewMonth(month: string): string {
  const normalized = month.trim();
  if (!MONTH_RE.test(normalized)) {
    throw new Error(`buildMonthlyReview: month must be YYYY-MM; got ${JSON.stringify(month)}`);
  }
  const monthNumber = Number(normalized.slice(5, 7));
  if (monthNumber < 1 || monthNumber > 12) {
    throw new Error(`buildMonthlyReview: invalid month ${JSON.stringify(month)}`);
  }
  return normalized;
}

function monthWindow(month: string): MonthlyReviewWindow {
  const start = Date.parse(`${month}-01T00:00:00Z`);
  if (!Number.isFinite(start)) {
    throw new Error(`buildMonthlyReview: invalid month ${JSON.stringify(month)}`);
  }
  const startDate = new Date(start);
  const endDate = new Date(Date.UTC(startDate.getUTCFullYear(), startDate.getUTCMonth() + 1, 1));
  return Object.freeze({
    since: `${month}-01T00:00:00Z`,
    until: endDate.toISOString().replace(".000Z", "Z"),
  });
}

function countContradictions(events: ReadonlyArray<TemporalEvent>): number {
  let count = 0;
  for (const event of events) {
    if (event.kind === BRAIN_LOG_EVENT_KIND.signalSuppressed) count += 1;
    if (
      event.kind === BRAIN_LOG_EVENT_KIND.applyEvidence &&
      event.result === BRAIN_APPLY_RESULT.violated
    ) {
      count += 1;
    }
  }
  return count;
}

function neglectedAreas(
  events: ReadonlyArray<TemporalEvent>,
  expectedAreas: ReadonlyArray<string>,
): string[] {
  if (expectedAreas.length === 0) return [];
  const lowerText = events.map((event) => JSON.stringify(event).toLowerCase()).join("\n");
  return expectedAreas.filter((area) => !lowerText.includes(area.toLowerCase())).toSorted();
}