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.4 KB
Raw Blame
/**
 * The destination-keyed write aggregate (actionable-now batch, A3 /
 * t_69fec179).
 *
 * "Which destinations did the recorded writes touch?" - one query-time
 * fold over the Brain log, grouping BOTH recorded write kinds by the
 * vault-relative target they name:
 *
 *   - `note-write` events (one per recorded note write, written by the
 *     note seams after the bytes land), and
 *   - `write-session` audit rows - one per TERMINAL write-session
 *     transition, of which only the `done` rows record a write (a
 *     `failed` session landed nothing); the write-session lane emits NO
 *     note-write events, which is exactly why this reader walks both
 *     kinds instead of reusing `listNoteWrites`, whose projection is
 *     note-write only.
 *
 * LOG-DERIVED ON QUERY, like every read aggregate over the log
 * (`listNoteWrites`, `buildTimelineIndex`, the today dashboard): the
 * aggregate adds no new fact, so a persisted table would be a cache with
 * a maintenance lane and a census burden. A query writes nothing.
 *
 * Coverage honesty: the write binding splits destinations three ways,
 * and slug-derived and fully-derived sites (a signal slug, a daily log)
 * emit NEITHER kind. A destination absent from this aggregate may
 * therefore still have been written; {@link WRITE_DESTINATION_COVERAGE_NOTE}
 * says so on every result instead of letting a clean answer imply a
 * complete one. Underclaiming is acceptable; overclaiming is not.
 */

import type { BrainLogEntry, BrainLogParseWarning } from "../log.ts";
import type { WriteSessionStatus } from "../write-session/types.ts";
import { BRAIN_LOG_EVENT_KIND } from "../types.ts";
import {
  DATE_LENGTH,
  DAY_END_SUFFIX,
  DAY_START_SUFFIX,
  parseWindowBound,
  timestampInWindow,
} from "./log-window.ts";
import { logDaysWithDevices } from "../log-days.ts";

/** Which recorded write kinds a destination's rows cover. */
export const WRITE_DESTINATION_KIND = Object.freeze({
  noteWrite: "note-write",
  writeSession: "write-session",
} as const);

export type WriteDestinationKind =
  (typeof WRITE_DESTINATION_KIND)[keyof typeof WRITE_DESTINATION_KIND];

/** The kinds, in declaration order - the order a row's `kinds` field uses. */
export const WRITE_DESTINATION_KINDS: ReadonlyArray<WriteDestinationKind> = Object.freeze(
  Object.values(WRITE_DESTINATION_KIND),
);

/**
 * Stated on every result: what this aggregate does not see. Written as a
 * constant because it is part of the answer, not a flourish a caller may
 * reword into an overclaim.
 */
export const WRITE_DESTINATION_COVERAGE_NOTE =
  "covers the destinations recorded write events name: slug-derived and fully-derived " +
  "write-binding sites (signal slugs, daily logs, telemetry) emit no note-write and no " +
  "write-session event, so a destination absent here may still have been written";

/** Default lookback window in whole UTC days, including today (the today-dashboard precedent). */
export const DEFAULT_WRITE_DESTINATION_WINDOW_DAYS = 7;

/** One destination: everything the recorded writes say about one target. */
export interface WriteDestinationRow {
  /** Vault-relative target path, exactly as the events recorded it. */
  readonly target: string;
  /**
   * Which recorded kinds contributed to this row, in declaration order.
   * A single-kind row answers honestly that the other kind said nothing
   * about this destination.
   */
  readonly kinds: ReadonlyArray<WriteDestinationKind>;
  readonly note_writes: number;
  readonly write_sessions: number;
  /** Both kinds together. */
  readonly writes: number;
  /** Contributing agents, first-seen order. */
  readonly agents: ReadonlyArray<string>;
  /**
   * Contributing devices, read off the log shards, first-seen order. The
   * empty string is the legacy un-sharded pair, which is an answer.
   */
  readonly devices: ReadonlyArray<string>;
  /** Newest recorded timestamp across both kinds. */
  readonly last_write: string;
}

/** How a caller narrows the aggregate. */
export interface WriteDestinationsFilter {
  /** Exact agent identity, as either kind recorded it. */
  readonly agent?: string;
  /** Exact device id; the empty string selects the legacy un-sharded pair. */
  readonly device?: string;
  /** Exact vault-relative target path. */
  readonly path?: string;
  /** Inclusive lower bound: an ISO date or an ISO-8601 UTC timestamp. */
  readonly since?: string;
  /** Inclusive upper bound, same two spellings; a bare date covers its day. */
  readonly until?: string;
  /** Maximum rows returned; `total_matched` still reports the full count. */
  readonly limit?: number;
  /**
   * Instant the default window is measured from; defaults to now. When
   * `until` is given, the default window is anchored on `until` instead -
   * an `--until` naming a past period asks about THAT period, and a lower
   * bound measured from the present would answer a clean, wrong empty.
   */
  readonly now?: Date;
  /**
   * The caller is below local reach: a write logged by an event of the
   * store's `private` partition is not counted. Default false.
   */
  readonly withholdsPrivate?: boolean;
}

export interface WriteDestinationsResult {
  /** Matching destinations, ordered by target. */
  readonly destinations: ReadonlyArray<WriteDestinationRow>;
  /** Row count before `limit` truncated the page. */
  readonly total_matched: number;
  readonly limit: number;
  /**
   * The window the walk covered, completed to timestamps. The lower
   * end is never null: a caller that sent no `--since` gets the
   * default window's computed bound, not an open walk.
   */
  readonly window: { readonly since: string; readonly until: string | null };
  /** Every parse warning the underlying log days reported. */
  readonly warnings: ReadonlyArray<BrainLogParseWarning>;
  readonly coverage_note: string;
}

/** Whole days one UTC day apart, for the default-window cutoff. */
const DAY_MS = 86_400_000;

/**
 * The only write-session audit status that records a write. The audit
 * lane emits one row per TERMINAL transition (`auditTerminal` in
 * `src/core/brain/write-session/engine.ts`, statuses spelled by
 * `WriteSessionStatus` in `src/core/brain/write-session/types.ts`), and
 * the `failed` terminal - abandon, retry cap, TTL expiry - is a session
 * that died before anything landed. Counting it would claim a write
 * that never happened; separating a failed session from a committed one
 * is exactly what a per-destination tally is for.
 */
const WRITE_SESSION_DONE_STATUS = "done" as const satisfies WriteSessionStatus;

/** The default window's lower bound as an ISO date: today minus (days - 1). */
function defaultSinceDate(days: number, now: Date): string {
  return new Date(now.getTime() - (days - 1) * DAY_MS).toISOString().slice(0, DATE_LENGTH);
}

/** Body value as a string, or null when the key is absent or a list. */
function stringField(entry: BrainLogEntry, key: string): string | null {
  const value = entry.body[key];
  return typeof value === "string" ? value : null;
}

/** The agent a recorded event carries: body first, the top-level second. */
function eventAgent(entry: BrainLogEntry): string {
  return stringField(entry, "agent") ?? entry.agent ?? "";
}

/**
 * One recorded destination touch projected from either kind, or null for
 * an event that names no target, is neither kind - or is a write-session
 * audit row for a session that never committed. The device is not
 * projected because it is not the event's to tell: it is read off the
 * shard the entry arrived in, at the call site.
 */
function projectTouch(
  entry: BrainLogEntry,
): { kind: WriteDestinationKind; target: string; agent: string } | null {
  const target = stringField(entry, "target");
  if (target === null || target.length === 0) return null;
  const agent = eventAgent(entry);
  if (entry.eventType === BRAIN_LOG_EVENT_KIND.noteWrite) {
    return { kind: WRITE_DESTINATION_KIND.noteWrite, target, agent };
  }
  if (
    entry.eventType === BRAIN_LOG_EVENT_KIND.writeSession &&
    stringField(entry, "status") === WRITE_SESSION_DONE_STATUS
  ) {
    return { kind: WRITE_DESTINATION_KIND.writeSession, target, agent };
  }
  return null;
}

/** Accumulator behind one destination row; frozen into the row at the end. */
interface DestinationAccumulator {
  target: string;
  noteWrites: number;
  writeSessions: number;
  agents: string[];
  agentSeen: Set<string>;
  devices: string[];
  deviceSeen: Set<string>;
  lastWrite: string;
}

/** Rows order by target; a named comparator because a fold owes its order a name. */
function byTargetAsc(a: DestinationAccumulator, b: DestinationAccumulator): number {
  if (a.target < b.target) return -1;
  if (a.target > b.target) return 1;
  return 0;
}

/**
 * Every destination the recorded writes touched inside the window,
 * ordered by target.
 *
 * The date range narrows which log days are opened at all (default: the
 * last seven days including today, or ending at `until` when the caller
 * names one); the remaining predicates run per
 * event because they key on payload fields the file layout cannot answer.
 * Both bounds accept a bare `YYYY-MM-DD`, completed to the day's start
 * and end - an `--until` naming a day means "through the end of it".
 *
 * Rows order by target with a stable sort, and everything inside a row
 * keeps first-seen order: `readLogDay` already merges shards by
 * (timestamp, shard id, line), so two same-second touches from one shard
 * stay in the order the appends landed, and the fold adds nothing that
 * would reorder them.
 */
export function listWriteDestinations(
  vault: string,
  filter: WriteDestinationsFilter = {},
): WriteDestinationsResult {
  const since =
    filter.since === undefined ? null : parseWindowBound(filter.since, "since", DAY_START_SUFFIX);
  const until =
    filter.until === undefined ? null : parseWindowBound(filter.until, "until", DAY_END_SUFFIX);
  // The default window's anchor is the upper bound when the caller named
  // one, and the present only when it did not: "the last seven days" of a
  // query about March is the seven days ending in March, never the seven
  // days before the question was asked.
  const windowAnchor = until !== null ? new Date(until) : (filter.now ?? new Date());
  const effectiveSince =
    since ??
    `${defaultSinceDate(DEFAULT_WRITE_DESTINATION_WINDOW_DAYS, windowAnchor)}${DAY_START_SUFFIX}`;
  const warnings: BrainLogParseWarning[] = [];
  const byTarget = new Map<string, DestinationAccumulator>();

  // The day files and their shard ids, or the store's log events and
  // their devices once switched.
  for (const day of logDaysWithDevices(
    vault,
    effectiveSince.slice(0, DATE_LENGTH),
    until === null ? null : until.slice(0, DATE_LENGTH),
  )) {
    warnings.push(...day.warnings);
    day.entries.forEach((entry, index) => {
      if (filter.withholdsPrivate === true && entry.fromPrivatePartition === true) return;
      const device = day.entryShardIds[index] ?? "";
      if (filter.device !== undefined && device !== filter.device) return;
      const touch = projectTouch(entry);
      if (touch === null) return;
      if (filter.agent !== undefined && touch.agent !== filter.agent) return;
      if (filter.path !== undefined && touch.target !== filter.path) return;
      if (!timestampInWindow(entry.timestamp, effectiveSince, until)) return;

      let acc = byTarget.get(touch.target);
      if (acc === undefined) {
        acc = {
          target: touch.target,
          noteWrites: 0,
          writeSessions: 0,
          agents: [],
          agentSeen: new Set<string>(),
          devices: [],
          deviceSeen: new Set<string>(),
          lastWrite: entry.timestamp,
        };
        byTarget.set(touch.target, acc);
      }
      if (touch.kind === WRITE_DESTINATION_KIND.noteWrite) acc.noteWrites += 1;
      else acc.writeSessions += 1;
      if (!acc.agentSeen.has(touch.agent)) {
        acc.agentSeen.add(touch.agent);
        acc.agents.push(touch.agent);
      }
      if (!acc.deviceSeen.has(device)) {
        acc.deviceSeen.add(device);
        acc.devices.push(device);
      }
      // Newest touch by instant, not by string: the JSONL reader admits
      // foreign sub-second timestamps, and a string compare orders
      // `…56.789Z` before `…56Z` (the `log-window.ts` rule). Both sides
      // parse - `timestampInWindow` already rejected NaN against the
      // never-null effective since - so the original spelling survives.
      if (Date.parse(entry.timestamp) > Date.parse(acc.lastWrite)) acc.lastWrite = entry.timestamp;
    });
  }

  const rows = [...byTarget.values()].toSorted(byTargetAsc).map((acc) => {
    const kinds = WRITE_DESTINATION_KINDS.filter((kind) =>
      kind === WRITE_DESTINATION_KIND.noteWrite ? acc.noteWrites > 0 : acc.writeSessions > 0,
    );
    return Object.freeze({
      target: acc.target,
      kinds: Object.freeze(kinds),
      note_writes: acc.noteWrites,
      write_sessions: acc.writeSessions,
      writes: acc.noteWrites + acc.writeSessions,
      agents: Object.freeze([...acc.agents]),
      devices: Object.freeze([...acc.devices]),
      last_write: acc.lastWrite,
    });
  });

  const limit =
    filter.limit === undefined || !Number.isInteger(filter.limit) || filter.limit < 1
      ? rows.length
      : filter.limit;
  return Object.freeze({
    destinations: Object.freeze(rows.slice(0, limit)),
    total_matched: rows.length,
    limit,
    window: Object.freeze({ since: effectiveSince, until }),
    warnings: Object.freeze([...warnings]),
    coverage_note: WRITE_DESTINATION_COVERAGE_NOTE,
  });
}