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.5 KB
Raw Blame
import {
  EventTraceSelectorError,
  resolveLogEventTraces,
  type AttachedTrace,
  type LogEventTrace,
} from "../../../core/brain/event-trace.ts";
import { BRAIN_LOG_EVENT_KIND_SET, type BrainLogEventKind } from "../../../core/brain/types.ts";
import { brainVerbContext, fail, parse, usageError } from "../helpers.ts";

/**
 * `o2b brain event-trace` — given one or more logged Brain events,
 * resolve and display the continuity records (recall telemetry, context
 * receipts, generation reports, …) attached to each via shared
 * correlation ids. The integrated "why did the agent do this?" reader:
 * one surface joining the event log to the served-context trace.
 */
export async function cmdBrainEventTrace(argv: string[]): Promise<number> {
  const { flags } = parse(argv, {
    vault: { type: "string" },
    json: { type: "boolean" },
    date: { type: "string" },
    at: { type: "string" },
    kind: { type: "string" },
    "session-id": { type: "string" },
    limit: { type: "string" },
    "keep-private": { type: "boolean" },
  });

  const kindRaw = trimOrUndefined(flags["kind"]);
  if (kindRaw !== undefined && !BRAIN_LOG_EVENT_KIND_SET.has(kindRaw)) {
    // Bad flag value is a usage error (exit 2, plain stderr), not a runtime
    // failure (exit 1). Same for --limit and the resolver's selector checks.
    return usageError(`brain event-trace: unknown event kind '${kindRaw}'`);
  }
  const limitRaw = trimOrUndefined(flags["limit"]);
  if (limitRaw !== undefined && (!/^[0-9]+$/.test(limitRaw) || Number.parseInt(limitRaw, 10) < 1)) {
    return usageError(`brain event-trace: --limit must be a positive integer`);
  }
  const limit = limitRaw !== undefined ? Number.parseInt(limitRaw, 10) : undefined;
  const vault = brainVerbContext(flags).vault;

  let results: ReadonlyArray<LogEventTrace>;
  try {
    results = resolveLogEventTraces(vault, {
      ...(trimOrUndefined(flags["date"]) !== undefined
        ? { date: trimOrUndefined(flags["date"])! }
        : {}),
      ...(trimOrUndefined(flags["at"]) !== undefined ? { at: trimOrUndefined(flags["at"])! } : {}),
      ...(kindRaw !== undefined ? { kind: kindRaw as BrainLogEventKind } : {}),
      ...(trimOrUndefined(flags["session-id"]) !== undefined
        ? { sessionId: trimOrUndefined(flags["session-id"])! }
        : {}),
      ...(limit !== undefined ? { limit } : {}),
      ...(flags["keep-private"] === true ? { keepPrivate: true } : {}),
    });
  } catch (err) {
    // A selector-validation error (bad --date/--at/--kind, checked before any
    // IO) is a usage error: exit 2. ANY OTHER throw is a runtime failure - e.g.
    // an existing-but-unreadable log dir (EACCES/EIO/ENOTDIR) from the shard
    // reader - and must be the runtime exit-1 path, not a usage error.
    if (err instanceof EventTraceSelectorError) {
      return usageError(`brain event-trace: ${err.message}`);
    }
    return fail(`brain event-trace: ${(err as Error).message}`);
  }

  if (flags["json"]) {
    process.stdout.write(
      JSON.stringify({ total: results.length, events: results }, null, 2) + "\n",
    );
    return 0;
  }

  const totalTraces = results.reduce((sum, r) => sum + r.traceCount, 0);
  process.stdout.write(
    `${results.length} logged event(s), ${totalTraces} attached context trace(s):\n`,
  );
  for (const result of results) {
    const e = result.event;
    const stamp = e.timestamp.slice(11, 19);
    const tags = [
      e.sessionId ? `session=${e.sessionId}` : null,
      e.turnId ? `turn=${e.turnId}` : null,
      e.agent ? `agent=${e.agent}` : null,
    ].filter(Boolean);
    process.stdout.write(
      `\n${stamp}  ${e.eventType}${tags.length > 0 ? "  " + tags.join("  ") : ""}\n`,
    );
    if (result.traceCount === 0) {
      process.stdout.write("    (no attached context trace)\n");
      continue;
    }
    for (const trace of result.traces) {
      process.stdout.write(`    ${formatTrace(trace)}\n`);
    }
  }
  return 0;
}

function formatTrace(trace: AttachedTrace): string {
  const flags: string[] = [`via ${trace.joinedBy.join("+")}`];
  if (trace.handoffRef) flags.push(`handoff=${trace.handoffKind ?? "?"}:${trace.handoffRef}`);
  if (trace.sourceCount > 0) flags.push(`sources=${trace.sourceCount}`);
  if (trace.private) flags.push("private");
  if (trace.redacted) flags.push("redacted");
  return `${trace.createdAt}  ${trace.kind}  ${trace.id}  [${flags.join(", ")}]`;
}

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