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
6.5 KB
Raw Blame
import { RECALL_CHANNEL, type RecallChannel } from "../brain/recall-telemetry.ts";
import {
  assertMeasuredQuality,
  computeSurfacingKey,
  SURFACING_TIER,
  type SurfacingTier,
} from "./surfacing-key.ts";

export type SurfacingGateReason =
  | "explicit"
  | "duplicate"
  | "empty"
  | "slash_command"
  | "shell_command"
  | "default_retrieve";

export interface SurfacingGateInput {
  readonly prompt: string;
  readonly previousPrompt?: string | null;
  readonly explicit?: boolean;
  /**
   * The transport asking, as {@link RecallChannel}. The STRUCTURAL
   * decision above is channel-independent by construction and never reads
   * this; only {@link evaluateGradedSurfacing} reads it, to calibrate the
   * measured admission. Absent means the gate's own production channel.
   */
  readonly channel?: RecallChannel;
  /**
   * The retrieval's absolute match quality (`RecallResultSet.idfWeightedCoverage`
   * or the adequacy pair's `match_quality`), when a measurement exists.
   * Only {@link evaluateGradedSurfacing} reads this: the structural gate
   * fails open on prompt structure alone and never sees retrieval state.
   * Absent = no measurement was offered; `null` = a measured report that
   * nothing was measurable.
   */
  readonly matchQuality?: number | null;
}

export interface SurfacingGateDecision {
  readonly retrieve: boolean;
  readonly reason: SurfacingGateReason;
}

/** The gate's production channel, assumed when a caller sends none. */
export const SURFACING_GATE_DEFAULT_CHANNEL = RECALL_CHANNEL.mcp;

/**
 * The graded decision: the structural verdict composed with the shared
 * admission key (`surfacing-key.ts`), one shape `{ key, tier, admit,
 * reason }` for every consumer. `reason` is the gate's own vocabulary on
 * the structural outcomes and the tier vocabulary on the measured ones.
 */
export interface GradedSurfacingDecision {
  readonly key: number | null;
  readonly tier: SurfacingTier;
  readonly admit: boolean;
  readonly reason: SurfacingGateReason | SurfacingTier;
}

const SHELL_COMMANDS = new Set([
  "awk",
  "bun",
  "cat",
  "cd",
  "chmod",
  "cp",
  "curl",
  "find",
  "git",
  "grep",
  "ls",
  "mkdir",
  "mv",
  "npm",
  "pnpm",
  "python",
  "rg",
  "rm",
  "sed",
  "touch",
  "yarn",
]);

function normalizePrompt(prompt: string): string {
  return prompt.trim().replace(/\s+/gu, " ").toLocaleLowerCase();
}

function isSlashCommand(normalized: string): boolean {
  return normalized.startsWith("/") && !normalized.includes(" ");
}

/** A line break (LF or CR) inside the trimmed raw prompt. */
const LINE_BREAK = /[\n\r]/u;

/**
 * Whether the raw prompt spans more than one line. Tested on the raw
 * prompt because normalisation collapses every whitespace run, line
 * breaks included, into one space.
 */
function isMultiLinePrompt(prompt: string): boolean {
  return LINE_BREAK.test(prompt.trim());
}

function isShellOnlyPrompt(normalized: string, multiLine: boolean): boolean {
  if (multiLine || normalized.includes("?")) return false;
  const firstToken = normalized.replace(/^\$\s*/u, "").split(/\s+/u)[0] ?? "";
  return SHELL_COMMANDS.has(firstToken);
}

/**
 * Decide whether a prompt should trigger memory retrieval.
 *
 * Language-agnostic by construction: the gate never inspects prompt
 * words against any natural-language vocabulary, so a prompt in any
 * language is treated identically. Only structural signals suppress
 * retrieval — an empty prompt, a verbatim repeat of the previous one, a
 * slash command, or a one-line shell command (command names, not human
 * language). Everything else FAILS OPEN: we retrieve and let ranking
 * decide relevance, because a missed recall is worse than a cheap
 * no-result search.
 */
export function evaluateSurfacingGate(input: SurfacingGateInput): SurfacingGateDecision {
  if (input.explicit === true) return Object.freeze({ retrieve: true, reason: "explicit" });

  const normalized = normalizePrompt(input.prompt);
  if (normalized.length === 0) return Object.freeze({ retrieve: false, reason: "empty" });

  const previous = input.previousPrompt ? normalizePrompt(input.previousPrompt) : null;
  if (previous !== null && previous === normalized) {
    return Object.freeze({ retrieve: false, reason: "duplicate" });
  }
  if (isSlashCommand(normalized))
    return Object.freeze({ retrieve: false, reason: "slash_command" });
  if (isShellOnlyPrompt(normalized, isMultiLinePrompt(input.prompt))) {
    return Object.freeze({ retrieve: false, reason: "shell_command" });
  }
  return Object.freeze({ retrieve: true, reason: "default_retrieve" });
}

/**
 * The graded projection: the structural short-circuits first, then the
 * shared channel-calibrated admission key over the measured quality.
 *
 * Tiering: an explicit request admits (`explicit`); a structural
 * suppression refuses (`suppressed`, structural reason preserved) and is
 * never ranked, so its key stays null; otherwise the measured quality
 * decides (`admitted` | `below_floor` | `unmeasurable_quality`). With no
 * measurement offered at all, the structural projection's fail-open
 * stands and `reason` records `default_retrieve` so a default admission
 * is never mistaken for a measured one. The binary
 * {@link SurfacingGateDecision} projects out of this shape: `admit` is
 * `retrieve`, `reason` is the same field.
 */
export function evaluateGradedSurfacing(input: SurfacingGateInput): GradedSurfacingDecision {
  const structural = evaluateSurfacingGate(input);
  if (structural.reason === "explicit") {
    // Both "no measurement offered" and "measured, nothing was
    // measurable" grade as null keys on the default branch; the explicit
    // branch treats them the same instead of handing a legitimate null
    // report to the validator as a shape violation.
    const key =
      input.matchQuality === undefined || input.matchQuality === null
        ? null
        : assertMeasuredQuality(input.matchQuality);
    return Object.freeze({
      key,
      tier: SURFACING_TIER.explicit,
      admit: true,
      reason: "explicit",
    });
  }
  if (structural.reason !== "default_retrieve") {
    return Object.freeze({
      key: null,
      tier: SURFACING_TIER.suppressed,
      admit: false,
      reason: structural.reason,
    });
  }
  if (input.matchQuality === undefined) {
    return Object.freeze({
      key: null,
      tier: SURFACING_TIER.admitted,
      admit: true,
      reason: "default_retrieve",
    });
  }
  return computeSurfacingKey({
    matchQuality: input.matchQuality,
    channel: input.channel ?? SURFACING_GATE_DEFAULT_CHANNEL,
  });
}