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.1 KB
Raw Blame
#!/usr/bin/env -S bun
/**
 * SessionEnd hook: opt-in knowledge-gap promotion and auto-close (theme A,
 * t_67d38036).
 *
 * When `gap_loop_enabled` is set (default OFF), at session end:
 *   1. every recurring recall gap (from the recall-telemetry gap_counts
 *      aggregate, above a tunable threshold) promotes to ONE durable
 *      gap-task note under the Brain area, deduped on a stable gap key so
 *      re-promotion never collides;
 *   2. every open gap task whose topic now recalls with sufficient
 *      confidence auto-closes (a recorded status flip in frontmatter),
 *      mirroring the dream freshness auto-resolve precedent.
 *
 * Gap-task notes are plain durable files; they never touch the Hermes
 * kanban board. Flag off writes nothing (byte-identical no-op). Fail-open:
 * the hook arms the shared process ceiling and exits 0 on every path; a
 * best-effort audit line records the run's counts, and a run that threw
 * records a `gap_loop_failed` line plus a stderr notice instead of
 * vanishing. SessionEnd cannot carry additionalContext, so this hook never
 * writes stdout.
 */

import {
  defaultConfigPath,
  resolveGapLoopEnabled,
  resolveGapLoopThreshold,
} from "../src/core/config.ts";
import { appendAuditRecord } from "../src/core/reliability/audit.ts";
import { hookAuditDir } from "../src/core/brain/paths.ts";
import { gapScopedRecallRetriever } from "../src/core/brain/gaps/gap-recall.ts";
import { autoCloseRecalledGaps, promoteGapsToTasks } from "../src/core/brain/gaps/gap-loop.ts";
import { armProcessCeiling, resolveHookCeilingMs } from "./lib/process-ceiling.ts";
import { asHookPayload, readHookInput } from "./lib/stdin.ts";
import { resolveHookTarget } from "./lib/hook-vault.ts";

/**
 * The vault this run resolved, remembered for the failure path.
 *
 * A failure is only auditable once the vault is known, and the vault is
 * resolved inside the run - so the failure reporter reads it from here
 * rather than re-resolving (which could itself be the thing that threw).
 */
let auditedVault: string | null = null;

function auditRun(vault: string, details: Record<string, unknown>): void {
  try {
    appendAuditRecord(hookAuditDir(vault), {
      timestamp: new Date().toISOString(),
      actor: "gap-promote",
      action: "gap_loop_run",
      target: "SessionEnd",
      ok: true,
      details,
    });
  } catch {
    // best-effort: auditing must never disturb the fail-open contract
  }
}

/**
 * Report a run that threw, on both channels, and never rethrow.
 *
 * Fail-open is about the SESSION, not about the fault: swallowing the
 * throw silently is what let a retriever that ignored its membership rule
 * leave this hook doing nothing at all, run after run, with no trace
 * anywhere - a fallback that quietly does nothing, which this repository
 * does not allow. So the failure lands as its OWN audit action (`ok:
 * false`), never as a `gap_loop_run` row: a run that threw produced no
 * counts, and a counts row with zeros would read as a quiet, healthy
 * no-op - exactly the report this fault already got away with. Stderr
 * carries it too, for the operator who is not reading the audit log.
 *
 * Every step is individually guarded, because this is the last frame
 * before the process exits and there is nothing left to catch it.
 */
function reportRunFailure(exc: unknown): void {
  const kind = exc instanceof Error ? exc.name : typeof exc;
  const message = exc instanceof Error ? exc.message : "";
  try {
    process.stderr.write(`gap-promote: gap loop failed [${kind}] ${message}\n`);
  } catch {
    // a closed stderr must not become the crash the fail-open forbids
  }
  if (auditedVault === null) return;
  try {
    appendAuditRecord(hookAuditDir(auditedVault), {
      timestamp: new Date().toISOString(),
      actor: "gap-promote",
      action: "gap_loop_failed",
      target: "SessionEnd",
      ok: false,
      details: { error: kind, message },
    });
  } catch {
    // best-effort: auditing must never disturb the fail-open contract
  }
}

async function main(): Promise<void> {
  // Fast opt-out FIRST: default OFF means an immediate no-op, no writes.
  if (!resolveGapLoopEnabled()) return;

  const disarm = armProcessCeiling({ ceilingMs: resolveHookCeilingMs() });
  try {
    try {
      asHookPayload(await readHookInput());
    } catch {
      return;
    }

    // With no vault the hook does its store-side part (design D14, task 2.10).
    const target = resolveHookTarget();
    if (target === null) return;
    const vault = target.vault;
    auditedVault = vault;
    const configPath = defaultConfigPath();
    const now = new Date();
    const threshold = resolveGapLoopThreshold(configPath);

    const promotion = promoteGapsToTasks(vault, {
      now,
      ...(threshold !== undefined ? { threshold } : {}),
    });
    const closure = await autoCloseRecalledGaps(
      vault,
      // NOT `defaultRecallRetriever`: that one takes only the query, and a
      // one-parameter function is structurally assignable here, so it
      // compiled while silently ignoring the membership rule - returning
      // the gap-task note itself and making the gate throw on every run.
      gapScopedRecallRetriever(configPath, vault),
      { now },
    );
    auditRun(vault, {
      promoted: promotion.created.length,
      skipped: promotion.skipped.length,
      // Both bounds the run enforces are reported, never dropped: a pruned
      // count explains a shrinking directory, and a non-zero cap refusal is
      // the operator's only signal that gap tasks are being turned away.
      pruned: promotion.pruned.length,
      capped: promotion.capped,
      closed: closure.closed.length,
      kept: closure.kept.length,
      // Why a recall narrowed (a gated query embed, a missing semantic
      // lane) rides this local line only, present only when non-empty.
      ...(closure.retrievalDegraded !== undefined
        ? { retrieval_degraded: closure.retrievalDegraded }
        : {}),
    });
  } finally {
    disarm();
  }
}

main().catch((exc: unknown) => {
  // Never crash the runtime; the session end must proceed regardless -
  // but never fail invisibly either. See `reportRunFailure`.
  reportRunFailure(exc);
});