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.6 KB
Raw Blame
#!/usr/bin/env -S bun
/**
 * Stop hook: surfaces pending Brain hygiene findings as ONE line,
 * once per change, behind the opt-in `hygiene_digest_enabled` flag
 * (context-injection-pipeline, lane B, task B3).
 *
 * The line folds the default detector sweep plus the index-backed
 * dangling-link count into counts per detector (composer:
 * hooks/lib/hygiene-digest-text.ts). Silence is the steady state: zero
 * eligible findings, an unmeasurable scan, a state the vault-level
 * hash ledger already emitted, or a runtime with no non-blocking
 * channel all exit 0 with no output.
 *
 * Gates, in cost order:
 *
 *   1. Unreadable payload -> silent.
 *   2. `stop_hook_active === true` -> silent (the once-per-turn guard;
 *      this hook never continues a turn itself, and a continued turn
 *      must not re-run the sweep).
 *   3. Flag off -> silent. Checked BEFORE vault resolution, and before
 *      the heavy imports: the detectors and the search index load
 *      lazily after every gate, so a default-off run pays one config
 *      read (reground-deliver precedent).
 *   4. Runtime without a non-blocking Stop channel -> silent. Only
 *      Claude Code gets the line: its Stop feedback renders as
 *      non-blocking "Stop hook feedback". Everywhere else a Stop block
 *      (`decision: "block"`) is a forced continuation turn, and an
 *      opt-in digest must never buy one - so Codex, Grok Build and
 *      unrecognised runtimes exit here, before any transcript work.
 *   5. No transcript, unreadable transcript, or a turn that wrote no
 *      artifact -> silent. "Once per change" means once per
 *      artifact-writing turn (`summarizeTurn` hadArtifact, the
 *      stop-log-guardrail gate) - an artifact write anywhere, code
 *      included, counts; the sweep is not vault-scoped.
 *   6. `resolveHookVault()` null -> silent.
 *
 * Change detection is a hash ledger,
 * `<vault>/.open-second-brain/hygiene-digest.hash`
 * (hooks/lib/hygiene-digest-state.ts): hash differs -> emit, then
 * write; hash equal -> exit 0. The write lands AFTER the emit, so a
 * crash in between loses the dedupe and the next eligible turn emits
 * again - lose-not-duplicate.
 *
 * Output shape: `hookSpecificOutput.additionalContext` on the Stop
 * event - non-error "Stop hook feedback", not the red block shape. The
 * per-runtime helper this file once shipped is gone with the runtimes
 * it served: the only emitting runtime left is the one whose channel
 * is additive. The Stop guardrail (hooks/stop-log-guardrail.ts) keeps
 * its portable block shape - it is always-on and its continuation is
 * the point.
 *
 * Crashes exit 0 - never deadlock.
 */

import { writeSync } from "node:fs";

import { resolveHygieneDigestEnabled } from "../src/core/config.ts";
import { detectHookRuntime, summarizeTurn } from "./lib/detect.ts";
import { composeHygieneDigest } from "./lib/hygiene-digest-text.ts";
import {
  computeHygieneDigestHash,
  hygieneDigestHashMatches,
  writeHygieneDigestHash,
} from "./lib/hygiene-digest-state.ts";
import { asHookPayload, readHookInput } from "./lib/stdin.ts";
import { readTranscript } from "./lib/transcript.ts";
import { resolveHookVault } from "./lib/hook-vault.ts";

async function main(): Promise<void> {
  let payload;
  try {
    payload = asHookPayload(await readHookInput());
  } catch {
    return;
  }

  if (payload.stop_hook_active === true) return;

  // Off is the default and this runs after every turn: one config read,
  // no vault resolution, no heavy imports.
  if (!resolveHygieneDigestEnabled()) return;

  // Claude Code only: its Stop `additionalContext` is non-blocking
  // feedback. On every other runtime a Stop block forces a continuation
  // turn, and an opt-in digest must never do that. Payload-shape
  // detection only, so a silent runtime pays nothing further.
  if (detectHookRuntime(payload) !== "claudecode") return;

  const transcriptPath = payload.transcript_path;
  if (typeof transcriptPath !== "string" || transcriptPath.length === 0) return;

  let signal;
  try {
    signal = readTranscript(transcriptPath);
  } catch {
    return;
  }

  const summary = summarizeTurn(signal.toolCalls, signal.bashCommands);
  if (!summary.hadArtifact) return;

  const vault = resolveHookVault();
  if (vault === null) return;

  // Heavy imports, only past every gate: the detector sweep and the
  // search index are the whole cost of this hook.
  const { runHygieneScan } = await import("../src/core/brain/hygiene/scan.ts");
  const { resolveSearchConfig } = await import("../src/core/search/index.ts");
  const { measureFromIndex } = await import("../src/core/search/link-ratchet.ts");
  // The ledger is machine state: the vault before the switch, the
  // device-local state once store-only (nothing written into the vault).
  const { machineStateRoot } = await import("../src/core/state/machine-state.ts");

  const report = runHygieneScan(vault, { now: new Date() });
  // The dangling-link measurement must never fail the digest: resolving
  // the search config itself can throw (a bad `search_chunk_size` env or
  // config value), and an index that cannot be measured is unmeasured.
  // Both degrade to `null` here, never flattened into a zero - the same
  // composition the hygiene tool makes (measured:false with a reason).
  let danglingLinks: number | null = null;
  try {
    const measurement = await measureFromIndex(resolveSearchConfig({ vault }));
    danglingLinks = measurement.measurable ? measurement.dangling : null;
  } catch {
    // Absorbed: the count is unmeasured, the findings still surface.
  }

  const line = composeHygieneDigest({ findings: report.findings, danglingLinks });
  if (line === null) return;

  const hash = computeHygieneDigestHash({ findings: report.findings, danglingLinks });
  const stateRoot = machineStateRoot(vault);
  if (hygieneDigestHashMatches(stateRoot, hash)) return;

  // One blocking write to fd 1, not process.stdout.write: a write error
  // must surface HERE, before the ledger write below. Bun and Node
  // deliver stdout errors asynchronously, which would resolve main,
  // record this state as emitted while the line never landed, and crash
  // with a stderr banner. The synchronous write throws into main's
  // fail-soft catch instead and the next eligible turn re-emits - the
  // lose-not-duplicate order made real, not just ordered.
  writeSync(
    1,
    `${JSON.stringify({ hookSpecificOutput: { hookEventName: "Stop", additionalContext: line } })}\n`,
  );
  // Lose-not-duplicate: the ledger records the state only after the
  // emit, so a crash in between re-emits rather than going silent.
  writeHygieneDigestHash(stateRoot, hash);
}

main().catch(() => {
  // Never deadlock on a hook crash.
});