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
8.7 KB
Raw Blame
/**
 * Recall-gate telemetry (Workspace Insight Suite, t_65036e02).
 *
 * Records every automatic-recall gate decision as a `gate_telemetry`
 * continuity record so the skip/retrieve behaviour becomes observable
 * and tunable. Privacy invariant: the RAW PROMPT is never stored -
 * continuity records sync with the vault, so only a SHA-256 prefix
 * (enough for duplicate analysis) and the prompt length land on disk.
 *
 * Default OFF: the `brain_recall_gate` handler emits only when the
 * `recall_gate_telemetry` config key is on, keeping the gate's
 * pure-diagnostic contract byte-identical otherwise. Reuses the
 * continuity-record kernel rather than inventing a new sink.
 *
 * The same handler's second observation lives here too: the typed
 * negative-recall verdict (silence-is-not-an-answer, U2), written as a
 * `negative_recall` record under the SAME opt-in. It is the same
 * surface's telemetry and shares the prompt-hashing invariant, so a
 * separate module would have duplicated both.
 */

import { createHash } from "node:crypto";

import { isSurfacingTier, type SurfacingTier } from "../search/surfacing-key.ts";
import { appendContinuityRecord, listContinuityRecords } from "./continuity/store.ts";
import { CONTINUITY_TURN_ID_KEY, type ContinuityRecord } from "./continuity/types.ts";
import type { NegativeRecallVerdict } from "./negative-recall.ts";
import type { RecallChannel } from "./recall-telemetry.ts";

export interface GateTelemetryInput {
  readonly host: string;
  readonly prompt: string;
  readonly retrieve: boolean;
  readonly reason: string;
  readonly sessionId?: string;
  /** The caller's turn correlation id, recorded under {@link CONTINUITY_TURN_ID_KEY}. */
  readonly turnId?: string;
  readonly createdAt?: string;
  /**
   * The graded surfacing key (t_107a3249), recorded only when the call
   * carried a measured quality - an unmeasured structural verdict is
   * already described by `decision` and `reason`. Numbers and closed
   * values only; `key` is null exactly where the graded admission key is
   * null: where nothing was measurable, or where a structural outcome
   * (`suppressed`, `explicit`) decided the call without grading the
   * carried measurement.
   */
  readonly surfacing?: {
    readonly key: number | null;
    readonly tier: SurfacingTier;
  };
  /**
   * The transport the decision arrived over, recorded only on MEASURED
   * decisions: the channel calibrates the measured admission, and an
   * unmeasured structural verdict is already described by `decision` and
   * `reason`.
   */
  readonly channel?: RecallChannel;
  /**
   * The adequacy verdict and the caller's advisory decision-model
   * probability, recorded only when the call carried `decision_answerable`
   * and the `answerable` use is not off (issue #213, Part 8). Numbers and
   * closed values only.
   */
  readonly decisionAnswerable?: {
    readonly level: string;
    readonly probability: number;
    readonly disagrees: boolean;
  };
}

export interface GateTelemetryFilter {
  readonly host?: string;
  readonly since?: string;
  readonly until?: string;
  readonly limit?: number;
}

export interface GateTelemetrySummary {
  readonly total: number;
  readonly retrieved: number;
  readonly skipped: number;
  readonly by_reason: Record<string, number>;
  /** Counts by graded admission tier (t_107a3249); measured calls only. */
  readonly by_tier: Record<string, number>;
}

export function hashPrompt(prompt: string): string {
  return createHash("sha256").update(prompt).digest("hex").slice(0, 16);
}

/** Record one gate decision. Never stores the raw prompt. */
export function emitGateTelemetry(vault: string, input: GateTelemetryInput): ContinuityRecord {
  return appendContinuityRecord(vault, {
    kind: "gate_telemetry",
    createdAt: input.createdAt ?? new Date().toISOString(),
    sourceRefs: [],
    payload: {
      host: input.host,
      ...(input.sessionId !== undefined ? { session_id: input.sessionId } : {}),
      ...(input.turnId !== undefined ? { [CONTINUITY_TURN_ID_KEY]: input.turnId } : {}),
      decision: input.retrieve ? "retrieve" : "skip",
      reason: input.reason,
      prompt_hash: hashPrompt(input.prompt),
      prompt_chars: input.prompt.length,
      ...(input.channel !== undefined ? { channel: input.channel } : {}),
      ...(input.surfacing !== undefined
        ? { key: input.surfacing.key, tier: input.surfacing.tier }
        : {}),
      ...(input.decisionAnswerable !== undefined
        ? {
            adequacy_level: input.decisionAnswerable.level,
            decision_answerable: {
              probability: input.decisionAnswerable.probability,
              disagrees: input.decisionAnswerable.disagrees,
            },
          }
        : {}),
    },
  });
}

/** One typed negative-recall verdict, as the gate observed it. */
export interface NegativeRecallTelemetryInput {
  readonly prompt: string;
  readonly verdict: NegativeRecallVerdict;
  readonly sessionId?: string;
  readonly createdAt?: string;
}

/**
 * Record one negative-recall verdict (silence-is-not-an-answer, U2).
 *
 * Same sink, same privacy invariant and the same `recall_gate_telemetry`
 * opt-in as {@link emitGateTelemetry} - one config decision governs the
 * whole feature rather than one per surface.
 *
 * The coverage receipt rides along in the reduced form that is safe to
 * replicate: the digest, the counts, the searched roots and the gap.
 * `index_path` is deliberately dropped. It is a host filesystem path,
 * not vault content, and continuity records sync between devices; the
 * digest already binds it, so nothing is lost that an audit needs.
 */
export function emitNegativeRecallTelemetry(
  vault: string,
  input: NegativeRecallTelemetryInput,
): ContinuityRecord {
  const { verdict } = input;
  const coverage = verdict.coverage;
  return appendContinuityRecord(vault, {
    kind: "negative_recall",
    createdAt: input.createdAt ?? new Date().toISOString(),
    sourceRefs: [],
    payload: {
      ...(input.sessionId !== undefined ? { session_id: input.sessionId } : {}),
      state: verdict.state,
      complete: verdict.complete,
      ...(verdict.unknown_reason !== undefined ? { unknown_reason: verdict.unknown_reason } : {}),
      reason: verdict.reason,
      ...(coverage !== undefined
        ? {
            coverage_digest: coverage.digest,
            documents: coverage.documents,
            chunks: coverage.chunks,
            schema_version: coverage.schema_version,
            embedding_signature: coverage.embedding_signature,
            last_indexed_at: coverage.last_indexed_at,
            scope: coverage.scope,
            unindexed_roots: coverage.unindexed_roots,
          }
        : {}),
      prompt_hash: hashPrompt(input.prompt),
      prompt_chars: input.prompt.length,
    },
  });
}

/** Gate decisions, newest first. */
export function listGateTelemetry(
  vault: string,
  filter: GateTelemetryFilter = {},
): ReadonlyArray<ContinuityRecord> {
  let records = listContinuityRecords(vault, {
    kind: "gate_telemetry",
    ...(filter.since !== undefined ? { since: filter.since } : {}),
    ...(filter.until !== undefined ? { until: filter.until } : {}),
  }).filter((record) => filter.host === undefined || record.payload["host"] === filter.host);
  records = records.toReversed();
  if (filter.limit !== undefined) records = records.slice(0, Math.max(0, Math.floor(filter.limit)));
  return Object.freeze(records);
}

/** Aggregate decisions by outcome, reason and graded tier. */
export function summarizeGateTelemetry(
  vault: string,
  filter: GateTelemetryFilter = {},
): GateTelemetrySummary {
  return summarizeGateTelemetryRecords(listGateTelemetry(vault, filter));
}

/**
 * The summary fold over an already-listed set of gate records. Split from
 * {@link summarizeGateTelemetry} for the same reason its recall-telemetry
 * sibling is: a reader that must drop withheld records BEFORE the counts
 * folds those counts over the filtered set without re-reading disk.
 */
export function summarizeGateTelemetryRecords(
  records: ReadonlyArray<ContinuityRecord>,
): GateTelemetrySummary {
  let retrieved = 0;
  const byReason: Record<string, number> = {};
  const byTier: Record<string, number> = {};
  for (const record of records) {
    if (record.payload["decision"] === "retrieve") retrieved += 1;
    const reason = record.payload["reason"];
    if (typeof reason === "string" && reason !== "") {
      byReason[reason] = (byReason[reason] ?? 0) + 1;
    }
    const tier = record.payload["tier"];
    if (isSurfacingTier(tier)) {
      byTier[tier] = (byTier[tier] ?? 0) + 1;
    }
  }
  return Object.freeze({
    total: records.length,
    retrieved,
    skipped: records.length - retrieved,
    by_reason: Object.freeze(byReason),
    by_tier: Object.freeze(byTier),
  });
}