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
15.0 KB
Raw Blame
/**
 * Event → context-trace join reader.
 *
 * The Brain log (`Brain/log/<date>[.<device-id>].md` + JSONL sidecar)
 * records WHAT happened; the continuity store
 * (`Brain/log/continuity/<month>[.<device-id>].jsonl`) records WHICH
 * CONTEXT was supplied to those operations. The two
 * surfaces are written independently and, until now, were read
 * independently — an operator asking "why did the agent do this?" had
 * to query the log, copy a correlation id, and then query each
 * continuity reader by hand.
 *
 * This module is the single reader that joins them: given a selector
 * for one (or several) logged events, it resolves the continuity
 * records attached to each via the stable correlation ids the
 * observability contract already guarantees (`docs/observability.md`
 * §Correlation IDs):
 *
 *   - `session_id` — the cross-surface session join. Log events written
 *     by the write-session chokepoint and session-lifecycle capture
 *     carry `session_id` in their body; recall_telemetry /
 *     context_receipt / session_turn / generation_report payloads carry
 *     the same id (lifted to `sessionId` by the read-model).
 *   - `turn_id`    — the finer within-session join.
 *   - artifact refs — wikilinks / vault paths in the event body (e.g.
 *     `apply-evidence`'s `artifact`, write-session's `target`) matched
 *     against a record's `sourceRefs[].id` / `.path` (or the record id
 *     itself when the body links a continuity id directly).
 *
 * Read-only and fail-soft by construction: it composes `readLogDay`
 * (tolerant shard merge) and `loadNormalizedContinuityRecords` (schema
 * dispatch + masking policy), so it inherits their guarantees — malformed
 * rows are skipped, unknown kinds stay readable, and `private` records
 * are dropped unless explicitly kept. It never writes to either surface.
 */

import {
  UNFILTERED_ARTIFACT_REFS,
  everyArtifactRefView,
  type ArtifactRefView,
} from "./artifact-ref-view.ts";
import { ownerScopeView } from "./owner-scope-view.ts";
import { logEntryAtReach } from "./log-events-at-reach.ts";
import type { BrainLogEntry, BrainLogEntryPayload } from "./log.ts";
import { loadNormalizedContinuityRecords } from "./continuity/read-model.ts";
import type { NormalizedContinuityRecord } from "./continuity/read-model.ts";
import { validateIsoDate } from "./paths.ts";
import { BRAIN_LOG_EVENT_KIND_SET, type BrainLogEventKind } from "./types.ts";
import { logDayReader } from "./log-days.ts";

/**
 * A selector-validation failure: a bad `--date` / `--at` / `--kind`, detected
 * BEFORE any IO. Entry points map this to a usage error (CLI exit 2 / MCP
 * `INVALID_PARAMS`); ANY OTHER throw from {@link resolveLogEventTraces} is a
 * runtime IO failure (e.g. an existing-but-unreadable log dir: EACCES / EIO /
 * ENOTDIR) and must surface as a runtime error (CLI exit 1 / MCP
 * `INTERNAL_ERROR`), never as a usage error. (t_27ea0daa)
 */
export class EventTraceSelectorError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "EventTraceSelectorError";
  }
}

/** Why a continuity record was attached to a given log event. */
export type TraceJoinReason = "session" | "turn" | "artifact";

/** Body keys whose values are treated as artifact references. */
const ARTIFACT_BODY_KEYS = Object.freeze([
  "artifact",
  "target",
  "preference",
  "signal",
  "source",
  "note_ref",
  "ref",
]);

const WIKILINK_RE = /\[\[([^\]|#]+)(?:[#|][^\]]*)?\]\]/g;

export interface EventTraceSelector {
  /** Log day to read (`YYYY-MM-DD`, UTC). Defaults to today when omitted. */
  readonly date?: string;
  /** Pin a single event by its `HH:MM:SS` UTC stamp. */
  readonly at?: string;
  /** Restrict to one event kind. */
  readonly kind?: BrainLogEventKind;
  /** Restrict to events bound to this session id. */
  readonly sessionId?: string;
  /** Cap the number of events returned (after filtering). */
  readonly limit?: number;
  /** Keep continuity records flagged `private` (default: drop them). */
  readonly keepPrivate?: boolean;
  /**
   * Owner scope the trace is filtered against
   * (a-label-is-not-a-boundary, U3). Absent / `null` filters nothing.
   *
   * An event's `body` is echoed VERBATIM, so no allowlist of payload keys
   * can bound what it discloses - `path` alone is outside
   * {@link ARTIFACT_BODY_KEYS} and carried a preference path in the sweep
   * that found this. Every string in the body is therefore asked about,
   * and one hidden reference drops the whole event: a log line about an
   * artifact this caller may not see is a log line about that artifact.
   */
  readonly ownerScope?: string | null;
  /**
   * A second reference view every event must also pass, typically the
   * caller's reach (`reachView`). Asked over the same references as the
   * owner scope, BEFORE the cap, so a withheld event is never counted and
   * never takes a slot an absent one would leave free. An attached trace
   * whose `handoffRef` the view hides is dropped from that event. Absent
   * filters nothing.
   */
  readonly view?: ArtifactRefView;
}

/** One continuity record attached to a log event, with the join provenance. */
export interface AttachedTrace {
  readonly id: string;
  readonly kind: string;
  readonly createdAt: string;
  /** Distinct join reasons that matched, in fixed order session→turn→artifact. */
  readonly joinedBy: ReadonlyArray<TraceJoinReason>;
  readonly sessionId?: string;
  readonly turnId?: string;
  readonly handoffKind?: string;
  readonly handoffRef?: string;
  readonly sourceCount: number;
  readonly private: boolean;
  readonly redacted: boolean;
}

/** Correlation ids lifted out of a log event body. */
export interface EventCorrelation {
  readonly sessionId?: string;
  readonly turnId?: string;
  /** Distinct artifact identifiers (wikilink targets + path/id-shaped values). */
  readonly artifacts: ReadonlyArray<string>;
}

export interface LogEventTrace {
  readonly event: {
    readonly timestamp: string;
    readonly eventType: string;
    readonly agent?: string;
    readonly sessionId?: string;
    readonly turnId?: string;
    readonly artifacts: ReadonlyArray<string>;
    readonly body: BrainLogEntryPayload;
  };
  readonly traces: ReadonlyArray<AttachedTrace>;
  readonly traceCount: number;
}

/**
 * Extract the join keys from a single log entry body. Pure and
 * defensive: it never throws on an odd payload shape.
 */
export function extractEventCorrelation(event: BrainLogEntry): EventCorrelation {
  const body = event.body;
  const sessionId = readBodyString(body["session_id"]);
  const turnId = readBodyString(body["turn_id"]);
  const artifacts = new Set<string>();
  for (const key of ARTIFACT_BODY_KEYS) {
    collectArtifacts(body[key], artifacts);
  }
  return {
    ...(sessionId !== undefined ? { sessionId } : {}),
    ...(turnId !== undefined ? { turnId } : {}),
    artifacts: Object.freeze([...artifacts]),
  };
}

/**
 * Compute the continuity records attached to one event, given the
 * already-normalized store. Returned records are sorted by
 * (createdAt, id) — the same stable order the store guarantees.
 */
export function attachTracesToEvent(
  records: ReadonlyArray<NormalizedContinuityRecord>,
  correlation: EventCorrelation,
): ReadonlyArray<AttachedTrace> {
  const artifactSet = new Set(correlation.artifacts);
  const attached: AttachedTrace[] = [];
  for (const record of records) {
    const reasons = joinReasons(record, correlation, artifactSet);
    if (reasons.length === 0) continue;
    attached.push({
      id: record.id,
      kind: record.kind,
      createdAt: record.createdAt,
      joinedBy: reasons,
      ...(record.sessionId !== undefined ? { sessionId: record.sessionId } : {}),
      ...(record.turnId !== undefined ? { turnId: record.turnId } : {}),
      ...(record.handoffKind !== undefined ? { handoffKind: record.handoffKind } : {}),
      ...(record.handoffRef !== undefined ? { handoffRef: record.handoffRef } : {}),
      sourceCount: record.sourceRefs.length,
      private: record.private,
      redacted: record.redacted,
    });
  }
  attached.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
  return Object.freeze(attached);
}

/**
 * Resolve logged events for `selector.date` and attach the continuity
 * trace to each. Events are returned in log order (timestamp, then
 * shard/line) after filtering; an event with no attached records is
 * still returned with an empty `traces` list so the operator sees that
 * the join produced nothing rather than that the event is missing.
 */
export function resolveLogEventTraces(
  vault: string,
  selector: EventTraceSelector = {},
): ReadonlyArray<LogEventTrace> {
  const date = selector.date !== undefined ? validateSelectorDate(selector.date) : todayUtc();
  if (selector.at !== undefined && !/^\d{2}:\d{2}:\d{2}$/.test(selector.at)) {
    throw new EventTraceSelectorError(
      `event-trace: --at must be HH:MM:SS (UTC); got ${JSON.stringify(selector.at)}`,
    );
  }
  if (selector.kind !== undefined && !BRAIN_LOG_EVENT_KIND_SET.has(selector.kind)) {
    throw new EventTraceSelectorError(`event-trace: unknown event kind '${selector.kind}'`);
  }

  // The day file, or the store's log events of that day once switched.
  const { entries } = logDayReader(vault).day(date);
  const view = everyArtifactRefView(
    ownerScopeView(vault, selector.ownerScope ?? null),
    selector.view ?? UNFILTERED_ARTIFACT_REFS,
  );
  const records = loadNormalizedContinuityRecords(
    vault,
    selector.keepPrivate === true ? { keepPrivate: true } : {},
  );

  const wantStamp = selector.at !== undefined ? `${date}T${selector.at}Z` : undefined;
  // Cap is evaluated BEFORE the push, so `limit: 0` yields an empty list and a
  // limit of N never collects N+1 events (the cap is the count returned, not
  // the count plus one).
  const cap = selector.limit !== undefined ? Math.max(0, Math.floor(selector.limit)) : undefined;
  const results: LogEventTrace[] = [];
  for (const logged of entries) {
    if (selector.kind !== undefined && logged.eventType !== selector.kind) continue;
    // A dream shared with a withheld record is kept with its readable
    // transitions only, and its correlation is read from that form, so
    // neither the body nor the artifacts name the withheld record; each
    // record id is asked under its pref- and ret- spellings, so evidence
    // logged before a reserved record was retired is dropped too.
    const entry = logEntryAtReach(view, logged);
    if (entry === null) continue;
    if (wantStamp !== undefined && entry.timestamp !== wantStamp) continue;
    const correlation = extractEventCorrelation(entry);
    if (selector.sessionId !== undefined && correlation.sessionId !== selector.sessionId) continue;
    if (!view.row(...correlation.artifacts, ...bodyStrings(entry.body))) continue;
    if (cap !== undefined && results.length >= cap) break;
    const traces = attachTracesToEvent(records, correlation).filter((trace) =>
      view.row(trace.handoffRef),
    );
    results.push({
      event: {
        timestamp: entry.timestamp,
        eventType: entry.eventType,
        ...(entry.agent !== undefined ? { agent: entry.agent } : {}),
        ...(correlation.sessionId !== undefined ? { sessionId: correlation.sessionId } : {}),
        ...(correlation.turnId !== undefined ? { turnId: correlation.turnId } : {}),
        artifacts: correlation.artifacts,
        body: entry.body,
      },
      traces,
      traceCount: traces.length,
    });
  }
  return Object.freeze(results);
}

// ----- internals ------------------------------------------------------------

/**
 * Every string an event body would print, scalars and array items alike.
 *
 * Deliberately not keyed on {@link ARTIFACT_BODY_KEYS}: that list bounds
 * which keys the CORRELATION reads, while the body is echoed whole, so a
 * key nobody thought to add to the list still reaches the caller.
 */
function bodyStrings(body: BrainLogEntryPayload): ReadonlyArray<string> {
  const out: string[] = [];
  for (const value of Object.values(body)) {
    for (const item of Array.isArray(value) ? value : [value]) {
      if (typeof item === "string" && item.length > 0) out.push(item);
    }
  }
  return out;
}

function joinReasons(
  record: NormalizedContinuityRecord,
  correlation: EventCorrelation,
  artifactSet: ReadonlySet<string>,
): ReadonlyArray<TraceJoinReason> {
  const reasons: TraceJoinReason[] = [];
  if (correlation.sessionId !== undefined && record.sessionId === correlation.sessionId) {
    reasons.push("session");
  }
  if (correlation.turnId !== undefined && record.turnId === correlation.turnId) {
    reasons.push("turn");
  }
  if (artifactSet.size > 0 && recordMatchesArtifact(record, artifactSet)) {
    reasons.push("artifact");
  }
  return reasons;
}

function recordMatchesArtifact(
  record: NormalizedContinuityRecord,
  artifactSet: ReadonlySet<string>,
): boolean {
  if (artifactSet.has(record.id)) return true;
  for (const ref of record.sourceRefs) {
    const id = ref["id"];
    if (typeof id === "string" && artifactSet.has(id)) return true;
    const path = ref["path"];
    if (typeof path === "string" && artifactSet.has(path)) return true;
  }
  return false;
}

function collectArtifacts(value: unknown, out: Set<string>): void {
  if (typeof value === "string") {
    addArtifactToken(value, out);
  } else if (Array.isArray(value)) {
    for (const item of value) {
      if (typeof item === "string") addArtifactToken(item, out);
    }
  }
}

function addArtifactToken(raw: string, out: Set<string>): void {
  const value = raw.trim();
  if (value.length === 0) return;
  let sawWikilink = false;
  for (const match of value.matchAll(WIKILINK_RE)) {
    const inner = match[1]?.trim();
    if (inner) {
      out.add(inner);
      // A wikilink target may itself be a vault path (`Brain/foo.md`);
      // its basename without extension is the artifact id most readers use.
      const base = basenameNoExt(inner);
      if (base !== inner) out.add(base);
      sawWikilink = true;
    }
  }
  if (sawWikilink) return;
  // Bare path or id-shaped value (no wikilink syntax). Record both the
  // raw value and its basename so a `target: Brain/x.md` body joins a
  // sourceRef carrying either form.
  out.add(value);
  const base = basenameNoExt(value);
  if (base !== value) out.add(base);
}

function basenameNoExt(value: string): string {
  const slash = value.lastIndexOf("/");
  const tail = slash >= 0 ? value.slice(slash + 1) : value;
  return tail.endsWith(".md") ? tail.slice(0, -3) : tail;
}

function readBodyString(value: unknown): string | undefined {
  if (typeof value !== "string") return undefined;
  const trimmed = value.trim();
  return trimmed.length > 0 ? trimmed : undefined;
}

function todayUtc(): string {
  return new Date().toISOString().slice(0, 10);
}

/**
 * Validate the `--date` selector. `validateIsoDate` throws a generic `Error`;
 * re-tag a bad date as a selector error so callers route it to the usage path,
 * not the runtime-failure path. (t_27ea0daa)
 */
function validateSelectorDate(date: string): string {
  try {
    return validateIsoDate(date);
  } catch (err) {
    throw new EventTraceSelectorError((err as Error).message);
  }
}