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
4.5 KB
Raw Blame
#!/usr/bin/env -S bun
/**
 * SessionStart hook: opt-in undistilled backlog nudge (session-mining-economy,
 * t_0358af42).
 *
 * When `backlog_nudge_enabled` is set (default OFF), reports how many
 * imported sessions have never been distilled, as ONE `additionalContext`
 * line, so the agent starts the session aware of the backlog still waiting.
 * The count comes from the vault-side mining census
 * (`src/core/brain/sessions/mining-census.ts`), which reads the import
 * ledger joined to the mining record and never hashes a source log - the
 * honest count is affordable inside this hook's budget.
 *
 * The nudge is change-keyed, not timed: the line is injected when the
 * undistilled count differs from the count injected last (state:
 * hooks/lib/backlog-nudge-state.ts, one overwrite-only file beside the
 * hygiene digest). An unchanged backlog is never re-nagged, and a drained
 * backlog is recorded without being announced - a line that says there is
 * nothing to do is the noise this hook exists to avoid.
 *
 * Under the deadline the hook degrades to silence, never to a fabricated
 * number: the census runs under the process ceiling's cooperative
 * safeguard, and a census that cannot verify its ledgers names the failure
 * on stderr and injects nothing.
 *
 * Flag off is an immediate no-op with zero output, keeping the session
 * preamble byte-identical. Fail-open: the hook arms the shared process
 * ceiling and exits 0 on every path.
 */

import { resolveBacklogNudgeEnabled } from "../src/core/config.ts";
import { isContextEventName } from "./lib/context-events.ts";
import {
  armProcessCeiling,
  ceilingSafeguard,
  resolveHookCeilingMs,
} from "./lib/process-ceiling.ts";
import { backlogNudgeCountMatches, writeBacklogNudgeCount } from "./lib/backlog-nudge-state.ts";
import { asHookPayload, readHookInput } from "./lib/stdin.ts";
import { resolveHookTarget } from "./lib/hook-vault.ts";

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

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

    const hookEventName =
      typeof payload.hook_event_name === "string" && payload.hook_event_name.length > 0
        ? payload.hook_event_name
        : "SessionStart";
    // Default-closed: only an additionalContext-eligible event may emit.
    if (!isContextEventName(hookEventName)) 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;

    // Loaded only here, after every gate: the census and its ledger chain
    // are the one heavy import, and a flag-off session start pays nothing
    // for them (the hygiene-digest hook's lazy-load precedent).
    const { buildMiningCensus } = await import("../src/core/brain/sessions/mining-census.ts");
    let count: number;
    try {
      count = buildMiningCensus(vault, { safeguard: ceilingSafeguard(ceilingMs) }).undistilled;
    } catch (err) {
      // Never block, never guess: a census that cannot verify its ledgers
      // says why and injects nothing.
      process.stderr.write(
        `backlog-nudge: the backlog census failed: ${(err as Error).message ?? String(err)}\n`,
      );
      return;
    }

    // Changed-count gate. A missing or corrupt state file compares unequal,
    // so the next eligible session emits again (lose-not-duplicate).
    if (backlogNudgeCountMatches(vault, count)) return;

    // A drained backlog is recorded, not announced.
    if (count <= 0) {
      writeBacklogNudgeCount(vault, count);
      return;
    }

    const sessions = count === 1 ? "session" : "sessions";
    const line =
      `Open Second Brain session backlog: ${count} imported ${sessions} not yet distilled. ` +
      "Run 'o2b brain import-session --status' for the per-runtime breakdown, or " +
      "'o2b brain import-session --propose-backlog --json' for the next sessions to mine.";
    process.stdout.write(
      JSON.stringify({ hookSpecificOutput: { hookEventName, additionalContext: line } }) + "\n",
    );

    // The state lands AFTER the emit: a crash in between loses the dedupe
    // and the next eligible session emits again, rather than never.
    writeBacklogNudgeCount(vault, count);
  } finally {
    disarm();
  }
}

main().catch(() => {
  // Never crash the runtime; the session start must proceed regardless.
});