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
9.1 KB
Raw Blame
/**
 * The note-write reader (who-wrote-what, Task A / t_662f4e82).
 *
 * `recordNoteWrite` appends one `note-write` event per write; this is the
 * only module that reads them back, and it exists so that `o2b brain
 * writes`, the `brain_writes` MCP tool and the per-agent revert
 * (t_924129c5) all answer from one projection rather than three parsers
 * of the same payload.
 *
 * It reads through {@link readLogDay}, which merges every device shard of
 * a day in a deterministic order and reports malformed lines as warnings
 * instead of aborting. Two consequences the callers rely on:
 *
 *   - the DEVICE comes off the shard the entry was read from, not off the
 *     payload. No writer stamps its device id into a note-write body, and
 *     one that did would be asserting a fact the file name already
 *     records - a caller naming its own provenance, which is the shape
 *     the origin-channel stamp exists not to be.
 *   - a warning is carried out rather than swallowed. A day whose JSONL
 *     lost a line is a day whose write history is incomplete, and an
 *     operator deciding what to revert has to be told that.
 *
 * Order is newest-first, because every surface over this reader answers
 * "what just happened" before it answers "what happened once".
 */

import type { BrainLogEntry, BrainLogParseWarning } from "../log.ts";
import { BRAIN_LOG_EVENT_KIND } from "../types.ts";
import { ORIGIN_CHANNEL_FIELD } from "../../origin-channel.ts";
import {
  DATE_LENGTH,
  DAY_END_SUFFIX,
  DAY_START_SUFFIX,
  parseWindowBound,
  timestampInWindow,
} from "./log-window.ts";
import { isNoteWriteOp, type NoteWriteOp } from "./write-record.ts";
import { logDaysWithDevices } from "../log-days.ts";

/** One recorded note write, projected from its log event. */
export interface NoteWriteRecord {
  readonly write_id: string;
  /** ISO-8601 UTC second the event carries. */
  readonly timestamp: string;
  readonly op: NoteWriteOp;
  /** Vault-relative POSIX path of the note. */
  readonly target: string;
  /** sha256 of the replaced bytes, or `absent` when there were none. */
  readonly hash_before: string;
  readonly hash_after: string;
  readonly bytes_before: number;
  readonly bytes_after: number;
  readonly agent: string;
  /**
   * Device that recorded the write, read off the log shard. The empty
   * string is the legacy un-sharded pair, which is a real answer ("the
   * machine that wrote this had no device id configured") and not a
   * missing one.
   */
  readonly device: string;
  /** Channel the appender stamped, or null on a line written before it. */
  readonly origin_channel: string | null;
}

/** How a caller narrows {@link listNoteWrites}. */
export interface ListNoteWritesFilter {
  /** Exact agent identity. */
  readonly agent?: string;
  /**
   * Exact device id; the empty string selects the legacy un-sharded pair.
   * Read one raw flag or argument into this field through
   * {@link isLegacyPairDevice}: a coercion that treats emptiness as
   * absence turns the pair's name into "no filter", and a device-scoped
   * read or revert silently widens to every device.
   */
  readonly device?: string;
  /** Exact vault-relative target path. */
  readonly path?: string;
  /**
   * The machine config that decides whether the log is the day files or
   * the store, and which store (default: the resolved one).
   */
  readonly configPath?: string;
  /** Inclusive lower bound: an ISO date or an ISO-8601 UTC timestamp. */
  readonly since?: string;
  /** Inclusive upper bound, same two spellings. */
  readonly until?: string;
  readonly op?: NoteWriteOp;
  /**
   * The caller is below local reach: a write logged by an event of the
   * store's `private` partition is not listed. Default false.
   */
  readonly withholdsPrivate?: boolean;
}

export interface ListNoteWritesResult {
  /** Matching writes, newest first. */
  readonly writes: ReadonlyArray<NoteWriteRecord>;
  /** Every parse warning the underlying log days reported. */
  readonly warnings: ReadonlyArray<BrainLogParseWarning>;
}

/**
 * Whether one raw `--device` / `device` argument names the legacy
 * un-sharded pair: an empty or whitespace-only string. The pair's name
 * IS a filter value ({@link ListNoteWritesFilter.device}), so every
 * surface must test this before any coercion that treats emptiness as
 * absence - the shared rule behind the CLI's `deviceSelector` and the
 * MCP `deviceArg`, which the revert selector once skipped and silently
 * reverted every device's writes.
 */
export function isLegacyPairDevice(raw: unknown): raw is string {
  return typeof raw === "string" && raw.trim() === "";
}

/** Payload value as a string, or null when the key is absent or a list. */
function stringField(
  body: Readonly<Record<string, string | ReadonlyArray<string>>>,
  key: string,
): string | null {
  const value = body[key];
  return typeof value === "string" ? value : null;
}

/**
 * A byte count as recorded. The payload contract carries strings only, so
 * the count is rendered on the way in and parsed back here; a value that
 * is not a non-negative integer is reported as `-1` rather than silently
 * becoming zero, because a zero-length note and an unreadable count are
 * different facts.
 */
const UNREADABLE_BYTE_COUNT = -1;

function byteField(
  body: Readonly<Record<string, string | ReadonlyArray<string>>>,
  key: string,
): number {
  const raw = stringField(body, key);
  if (raw === null) return UNREADABLE_BYTE_COUNT;
  const value = Number.parseInt(raw, 10);
  return Number.isInteger(value) && value >= 0 && String(value) === raw
    ? value
    : UNREADABLE_BYTE_COUNT;
}

/**
 * Project one log entry into a record, or null when it is not a
 * note-write event this build can read.
 *
 * A `note-write` line missing its `write_id`, `target` or `op` is not
 * projected: those three are what every surface over this reader keys on,
 * and a record with a blank one would be a row an operator could select
 * and never act on.
 */
function projectRecord(entry: BrainLogEntry, device: string): NoteWriteRecord | null {
  if (entry.eventType !== BRAIN_LOG_EVENT_KIND.noteWrite) return null;
  const writeId = stringField(entry.body, "write_id");
  const target = stringField(entry.body, "target");
  const op = stringField(entry.body, "op");
  if (writeId === null || target === null || op === null || !isNoteWriteOp(op)) return null;
  return {
    write_id: writeId,
    timestamp: entry.timestamp,
    op,
    target,
    hash_before: stringField(entry.body, "hash_before") ?? "",
    hash_after: stringField(entry.body, "hash_after") ?? "",
    bytes_before: byteField(entry.body, "bytes_before"),
    bytes_after: byteField(entry.body, "bytes_after"),
    agent: stringField(entry.body, "agent") ?? "",
    device,
    origin_channel: stringField(entry.body, ORIGIN_CHANNEL_FIELD),
  };
}

/**
 * Every recorded note write matching the filter, newest first.
 *
 * The date range narrows which log days are opened at all, so a filter
 * with both bounds does not pay for the whole history; the remaining
 * predicates run per record because they key on payload fields the file
 * layout cannot answer.
 */
export function listNoteWrites(
  vault: string,
  filter: ListNoteWritesFilter = {},
): ListNoteWritesResult {
  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);
  const warnings: BrainLogParseWarning[] = [];
  const writes: NoteWriteRecord[] = [];

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

  // Newest first, by REVERSING the order the log already merged rather
  // than re-sorting on the timestamp. Timestamps are second-precision, so
  // a sort would tie for every pair of writes made inside one second and
  // any tiebreak invented here - the write id, the path - would order
  // them by something that is not when they happened. `readLogDay`
  // already merges shards by (timestamp, shard id, line), and line order
  // inside a shard IS the order the appends landed, so reversing keeps
  // the causal order within a second and stays deterministic across
  // devices reading one synced vault.
  writes.reverse();
  return { writes, warnings };
}