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.7 KB
Raw Blame
import {
  isRecallChannel,
  isRecallTelemetryMode,
  isRecallTelemetryStatus,
  listRecallTelemetry,
  RECALL_CHANNELS,
  RECALL_TELEMETRY_MODES,
  RECALL_TELEMETRY_STATUSES,
  summarizeRecallTelemetry,
  type RecallTelemetryFilter,
} from "../../../core/brain/recall-telemetry.ts";
import { computeDeadWeight, DEAD_WEIGHT_MAX_LIMIT } from "../../../core/brain/dead-weight.ts";
import { listGateTelemetry, summarizeGateTelemetry } from "../../../core/brain/gate-telemetry.ts";
import { computeMemoryCostMeter } from "../../../core/brain/memory-cost-meter.ts";
import { CliError, brainVerbContext, parse } from "../helpers.ts";

export async function cmdBrainRecallTelemetry(argv: string[]): Promise<number> {
  const subcommand = argv[0];
  const rest = argv.slice(1);
  if (subcommand === "list") return listTelemetry(rest);
  if (subcommand === "summary") return summarizeTelemetry(rest);
  // Gate-decision telemetry (Workspace Insight Suite, t_65036e02).
  if (subcommand === "gate-list") return listGate(rest);
  if (subcommand === "gate-summary") return summarizeGate(rest);
  // Write-vs-read cost meter (memory cost meter).
  if (subcommand === "cost") return costMeter(rest);
  // Dead-weight utilization fold (recall-quality, t_1ee67e5b). Every
  // aggregate on this tool ships over MCP and CLI alike; this keeps the
  // parity (the MCP op is `dead_weight`).
  if (subcommand === "dead-weight") return deadWeight(rest);
  throw new CliError(
    "brain recall-telemetry: expected list, summary, gate-list, gate-summary, cost, or dead-weight",
  );
}

function listTelemetry(argv: string[]): number {
  const { flags } = parseTelemetryFlags(argv);
  const vault = brainVerbContext(flags).vault;
  const filter = telemetryFilter(flags, "brain recall-telemetry list");
  const records = listRecallTelemetry(vault, filter);

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

  process.stdout.write(`${records.length} recall telemetry record(s):\n`);
  for (const record of records) {
    process.stdout.write(
      `  ${record.createdAt}  ${record.id}  ${record.payload["mode"] ?? "unknown"}  ${record.payload["status"] ?? "unknown"}  results=${record.payload["result_count"] ?? "?"}\n`,
    );
  }
  return 0;
}

function summarizeTelemetry(argv: string[]): number {
  const { flags } = parseTelemetryFlags(argv);
  const vault = brainVerbContext(flags).vault;
  const summary = summarizeRecallTelemetry(
    vault,
    telemetryFilter(flags, "brain recall-telemetry summary"),
  );

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

  process.stdout.write(`records: ${summary.total}\n`);
  process.stdout.write(`total results: ${summary.total_results}\n`);
  process.stdout.write(`empty runs: ${summary.empty_runs}\n`);
  process.stdout.write(`by mode: ${JSON.stringify(summary.by_mode)}\n`);
  process.stdout.write(`by status: ${JSON.stringify(summary.by_status)}\n`);
  process.stdout.write(`by channel: ${JSON.stringify(summary.by_channel)}\n`);
  process.stdout.write(`gaps: ${JSON.stringify(summary.gap_counts)}\n`);
  return 0;
}

function rejectRecallOnlyFlags(
  flags: Record<string, string | boolean | string[] | undefined>,
  command: string,
  alsoReject: ReadonlyArray<string> = [],
): void {
  // Gate records have no mode/status dimensions - dropping these
  // silently would hand back unfiltered results.
  for (const name of ["mode", "status", "channel", ...alsoReject]) {
    if (flags[name] !== undefined) {
      throw new CliError(`${command}: --${name} is not supported for gate telemetry`);
    }
  }
}

function listGate(argv: string[]): number {
  const { flags } = parseTelemetryFlags(argv);
  rejectRecallOnlyFlags(flags, "brain recall-telemetry gate-list");
  const vault = brainVerbContext(flags).vault;
  const filter = telemetryFilter(flags, "brain recall-telemetry gate-list");
  const records = listGateTelemetry(vault, {
    ...(filter.host !== undefined ? { host: filter.host } : {}),
    ...(filter.since !== undefined ? { since: filter.since } : {}),
    ...(filter.until !== undefined ? { until: filter.until } : {}),
    ...(filter.limit !== undefined ? { limit: filter.limit } : {}),
  });
  if (flags["json"]) {
    process.stdout.write(JSON.stringify({ total: records.length, records }, null, 2) + "\n");
    return 0;
  }
  process.stdout.write(`${records.length} gate decision(s):\n`);
  for (const record of records) {
    process.stdout.write(
      `  ${record.createdAt}  ${record.payload["decision"]}  ${record.payload["reason"]}  host=${record.payload["host"] ?? "?"}\n`,
    );
  }
  return 0;
}

function summarizeGate(argv: string[]): number {
  const { flags } = parseTelemetryFlags(argv);
  rejectRecallOnlyFlags(flags, "brain recall-telemetry gate-summary", ["limit"]);
  const vault = brainVerbContext(flags).vault;
  const filter = telemetryFilter(flags, "brain recall-telemetry gate-summary");
  const summary = summarizeGateTelemetry(vault, {
    ...(filter.host !== undefined ? { host: filter.host } : {}),
    ...(filter.since !== undefined ? { since: filter.since } : {}),
    ...(filter.until !== undefined ? { until: filter.until } : {}),
  });
  if (flags["json"]) {
    process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
    return 0;
  }
  process.stdout.write(`decisions: ${summary.total}\n`);
  process.stdout.write(`retrieved: ${summary.retrieved}\n`);
  process.stdout.write(`skipped: ${summary.skipped}\n`);
  process.stdout.write(`by reason: ${JSON.stringify(summary.by_reason)}\n`);
  return 0;
}

function costMeter(argv: string[]): number {
  const { flags } = parseTelemetryFlags(argv);
  // The cost meter is period-based; mode/status/host/limit filter recall
  // records only and have no write-side analogue, so reject them rather
  // than silently ignore.
  for (const name of ["mode", "status", "channel", "host", "limit"]) {
    if (flags[name] !== undefined) {
      throw new CliError(
        `brain recall-telemetry cost: --${name} is not supported for the cost meter`,
      );
    }
  }
  const vault = brainVerbContext(flags).vault;
  const since = trimOrUndefined(flags["since"]);
  const until = trimOrUndefined(flags["until"]);
  // Parse each numeric weight once; the cost meter omits undefined weights
  // so the module applies its own defaults.
  const writeCost = parseNonNegativeNumber(
    trimOrUndefined(flags["write-cost"]),
    "brain recall-telemetry cost",
    "--write-cost",
  );
  const readCost = parseNonNegativeNumber(
    trimOrUndefined(flags["read-cost"]),
    "brain recall-telemetry cost",
    "--read-cost",
  );
  const writeHeavyRatio = parseNonNegativeNumber(
    trimOrUndefined(flags["write-heavy-ratio"]),
    "brain recall-telemetry cost",
    "--write-heavy-ratio",
  );
  const meter = computeMemoryCostMeter(vault, {
    ...(since !== undefined ? { since } : {}),
    ...(until !== undefined ? { until } : {}),
    weights: { write: writeCost, read: readCost },
    ...(writeHeavyRatio !== undefined ? { writeHeavyRatio } : {}),
  });

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

  const ratio = meter.write_read_ratio === null ? "n/a (no reads)" : meter.write_read_ratio;
  process.stdout.write(`writes: ${meter.writes.total}\n`);
  process.stdout.write(`reads: ${meter.reads.total}\n`);
  process.stdout.write(`write/read ratio: ${ratio}\n`);
  process.stdout.write(`write-heavy: ${meter.write_heavy ? "yes" : "no"}\n`);
  process.stdout.write(`by write kind: ${JSON.stringify(meter.writes.by_kind)}\n`);
  process.stdout.write(`by read mode: ${JSON.stringify(meter.reads.by_mode)}\n`);
  process.stdout.write(
    `cost (write=${meter.weights.write}, read=${meter.weights.read}): ` +
      `write=${meter.cost.write} read=${meter.cost.read} total=${meter.cost.total}\n`,
  );
  return 0;
}

/**
 * Dead weight (t_1ee67e5b): pages currently in scope that no recorded
 * recall ever surfaced. The CLI is the owner reach, so the fold is
 * unfiltered by construction - no visibility predicate is passed.
 */
function deadWeight(argv: string[]): number {
  const { flags } = parseTelemetryFlags(argv);
  // Record-only filters have no complement meaning; reject rather than
  // silently ignore, mirroring the cost verb above. `--limit` is the one
  // exception (PR #248 review L10): it bounds the dead preview, which is
  // otherwise pinned at the fold's 50-row default.
  for (const name of ["mode", "status", "channel", "host"]) {
    if (flags[name] !== undefined) {
      throw new CliError(
        `brain recall-telemetry dead-weight: --${name} is not supported for dead weight`,
      );
    }
  }
  const vault = brainVerbContext(flags).vault;
  const since = trimOrUndefined(flags["since"]);
  const until = trimOrUndefined(flags["until"]);
  const rawLimit = parsePositiveInteger(
    trimOrUndefined(flags["limit"]),
    "brain recall-telemetry dead-weight",
    "--limit",
  );
  const report = computeDeadWeight(vault, {
    ...(since !== undefined ? { since } : {}),
    ...(until !== undefined ? { until } : {}),
    ...(rawLimit !== undefined ? { deadLimit: Math.min(rawLimit, DEAD_WEIGHT_MAX_LIMIT) } : {}),
  });

  if (flags["json"]) {
    process.stdout.write(JSON.stringify(report, null, 2) + "\n");
    return 0;
  }
  process.stdout.write(`pages: ${report.pages_total} total, ${report.pages_retrieved} retrieved\n`);
  process.stdout.write(
    `window: ${report.window.since ?? "none"} .. ${report.window.until ?? "none"}\n`,
  );
  process.stdout.write(
    `dead: ${report.dead_count} page(s) never surfaced in recorded recall history\n`,
  );
  if (report.unresolved_ids > 0) {
    process.stdout.write(
      `unresolved ids: ${report.unresolved_ids} surfaced entry(ies) name no walked page\n`,
    );
  }
  for (const row of report.dead) process.stdout.write(`  ${row.path}\n`);
  process.stdout.write(`caveat: ${report.gate_caveat}\n`);
  return 0;
}

function parseTelemetryFlags(argv: string[]): {
  readonly flags: Record<string, string | boolean | string[] | undefined>;
} {
  return parse(argv, {
    vault: { type: "string" },
    json: { type: "boolean" },
    mode: { type: "string" },
    status: { type: "string" },
    channel: { type: "string" },
    host: { type: "string" },
    since: { type: "string" },
    until: { type: "string" },
    limit: { type: "string" },
    "write-cost": { type: "string" },
    "read-cost": { type: "string" },
    "write-heavy-ratio": { type: "string" },
  });
}

function parseNonNegativeNumber(
  value: string | undefined,
  label: string,
  flag: string,
): number | undefined {
  if (value === undefined) return undefined;
  const parsed = Number(value);
  if (!Number.isFinite(parsed) || parsed < 0) {
    throw new CliError(`${label}: ${flag} must be a non-negative number`);
  }
  return parsed;
}

/**
 * Every filter flag parsed EXACTLY ONCE.
 *
 * The conditional-spread idiom used to call each parser twice - once to
 * test for undefined and once to take the value - so every validating
 * parser ran its checks and raised its errors twice for one flag. Binding
 * first makes each flag one call, and makes adding a seventh flag a
 * two-line change rather than a four-line one.
 */
function telemetryFilter(
  flags: Record<string, string | boolean | string[] | undefined>,
  label: string,
): RecallTelemetryFilter {
  const mode = modeFlag(flags["mode"], label);
  const status = statusFlag(flags["status"], label);
  const channel = channelFlag(flags["channel"], label);
  const host = trimOrUndefined(flags["host"]);
  const since = trimOrUndefined(flags["since"]);
  const until = trimOrUndefined(flags["until"]);
  const limit = parsePositiveInteger(trimOrUndefined(flags["limit"]), label, "--limit");
  return {
    ...(mode !== undefined ? { mode } : {}),
    ...(status !== undefined ? { status } : {}),
    ...(channel !== undefined ? { channel } : {}),
    ...(host !== undefined ? { host } : {}),
    ...(since !== undefined ? { since } : {}),
    ...(until !== undefined ? { until } : {}),
    ...(limit !== undefined ? { limit } : {}),
  };
}

function modeFlag(raw: string | boolean | string[] | undefined, label: string) {
  const value = trimOrUndefined(raw);
  if (value === undefined) return undefined;
  // Rendered from the frozen member list, never restated in prose: three
  // hand-written copies of this sentence went stale when `query` landed.
  if (!isRecallTelemetryMode(value)) {
    throw new CliError(`${label}: --mode must be one of ${RECALL_TELEMETRY_MODES.join(", ")}`);
  }
  return value;
}

function statusFlag(raw: string | boolean | string[] | undefined, label: string) {
  const value = trimOrUndefined(raw);
  if (value === undefined) return undefined;
  if (!isRecallTelemetryStatus(value)) {
    throw new CliError(`${label}: --status must be one of ${RECALL_TELEMETRY_STATUSES.join(", ")}`);
  }
  return value;
}

function channelFlag(raw: string | boolean | string[] | undefined, label: string) {
  const value = trimOrUndefined(raw);
  if (value === undefined) return undefined;
  if (!isRecallChannel(value)) {
    throw new CliError(`${label}: --channel must be one of ${RECALL_CHANNELS.join(", ")}`);
  }
  return value;
}

function parsePositiveInteger(
  value: string | undefined,
  label: string,
  flag: string,
): number | undefined {
  if (value === undefined) return undefined;
  if (!/^[0-9]+$/.test(value)) {
    throw new CliError(`${label}: ${flag} must be a positive integer`);
  }
  const parsed = Number.parseInt(value, 10);
  if (parsed < 1) throw new CliError(`${label}: ${flag} must be a positive integer`);
  return parsed;
}

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;
}