nlm-memory 0.4.0

package/migrations/005_sources.sql

@@ -0,0 +1,31 @@
+-- Migration 005: sources registry.
+--
+-- Each row represents one transcript source the daemon should scan. The
+-- three hardcoded adapters (claude-code / hermes / pi) become seeded rows
+-- pointing at the same parse logic; future custom JSONL or webhook sources
+-- live alongside them.
+--
+-- Parse config is a JSON blob whose shape depends on `kind`:
+--   - "claude-code" / "hermes" / "pi": preset adapters. parse_config is
+--     reserved but unused — paths come from path_or_url.
+--   - "jsonl-generic": { sessionIdField, textField, startedAtField,
+--     roleField, runtimeLabel, ... }
+--   - "webhook": parse_config is empty; ingest is push-based.
+--
+-- See docs/plans/desktop-product.md (Phase 0).
+
+CREATE TABLE IF NOT EXISTS sources (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  kind          TEXT    NOT NULL CHECK (kind IN ('claude-code', 'hermes', 'pi', 'jsonl-generic', 'webhook')),
+  name          TEXT    NOT NULL UNIQUE,
+  path_or_url   TEXT,
+  runtime_label TEXT    NOT NULL,
+  parse_config  TEXT    NOT NULL DEFAULT '{}',
+  enabled       INTEGER NOT NULL DEFAULT 1,
+  created_at    TEXT    NOT NULL DEFAULT (datetime('now')),
+  updated_at    TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_sources_enabled ON sources(enabled) WHERE enabled = 1;
+
+INSERT OR IGNORE INTO schema_migrations (version, name) VALUES (5, '005_sources');

package/migrations/006_providers.sql

@@ -0,0 +1,33 @@
+-- Migration 006: providers registry.
+--
+-- Each row represents one LLM endpoint configured for classification or
+-- (future) embedding. The classifier reads this table to choose a
+-- provider/model at boot; the UI mutates it through /api/providers.
+--
+-- API key storage. v0 stores keys in the api_key column. This is fine
+-- because the SQLite file already contains the user's transcripts —
+-- anyone with disk access already has everything sensitive. Phase 2
+-- (Tauri shell) migrates keys to the OS keychain and replaces the column
+-- with a keychain reference. The API shape stays the same.
+--
+-- `kind` is the structural family (openai-compatible, ollama,
+-- anthropic-native, deepseek). The classifier+model UI uses it to decide
+-- which client class to instantiate.
+--
+-- See docs/plans/desktop-product.md (Phase 0 task 3).
+
+CREATE TABLE IF NOT EXISTS providers (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  kind          TEXT    NOT NULL CHECK (kind IN ('deepseek', 'ollama', 'openai', 'anthropic', 'openrouter', 'openai-compatible')),
+  name          TEXT    NOT NULL UNIQUE,
+  base_url      TEXT,
+  api_key       TEXT,
+  default_model TEXT,
+  enabled       INTEGER NOT NULL DEFAULT 1,
+  created_at    TEXT    NOT NULL DEFAULT (datetime('now')),
+  updated_at    TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_providers_enabled ON providers(enabled) WHERE enabled = 1;
+
+INSERT OR IGNORE INTO schema_migrations (version, name) VALUES (6, '006_providers');

package/migrations/007_source_tokens.sql

@@ -0,0 +1,17 @@
+-- Migration 007: webhook token on sources.
+--
+-- Webhook sources need a bearer token so external tools (anything that
+-- pushes sessions via POST /api/ingest) can authenticate. The token is
+-- stored alongside the source row so one webhook = one token = one
+-- provenance label.
+--
+-- Storage policy mirrors providers.api_key: column in the canonical
+-- SQLite for v0 (the DB file already holds the user's transcripts,
+-- adding a token doesn't change the threat model). Phase 2 migrates to
+-- OS keychain without changing the API shape.
+--
+-- See docs/plans/desktop-product.md (Phase 0 task 5).
+
+ALTER TABLE sources ADD COLUMN token TEXT;
+
+INSERT OR IGNORE INTO schema_migrations (version, name) VALUES (7, '007_source_tokens');

package/migrations/008_fts_rebuild.sql

@@ -0,0 +1,9 @@
+-- One-time safety rebuild of the sessions_fts external-content FTS5 index.
+-- The virtual table and its sync triggers (sessions_ai / sessions_au /
+-- sessions_ad) were declared in migration 000 and have fired on every write
+-- since, so the index is normally already in sync. This rebuild guarantees
+-- the index matches every existing sessions row before the recall path
+-- starts depending on FTS5 for keyword search. Safe and idempotent.
+INSERT INTO sessions_fts(sessions_fts) VALUES('rebuild');
+
+INSERT OR IGNORE INTO schema_migrations (version, name) VALUES (8, 'fts_rebuild');

package/migrations/009_session_embedding_chunks.sql

@@ -0,0 +1,46 @@
+-- Migration 009: chunk + max-pool semantic index.
+--
+-- Replaces session_embeddings (one vector per session, truncated at
+-- MAX_EMBED_CHARS=8000) with per-chunk vectors. Recall-time score is
+-- max cosine across chunks per session.
+--
+-- The 2026-05-25 LongMemEval-S baseline showed 98% of gold sessions
+-- exceed 8000 chars and were silently truncated. Raising the per-call
+-- cap (#172) hit Ollama 500s on >50% of long inputs. Chunking sidesteps
+-- both: each chunk is well under the Ollama failure cliff, and the full
+-- body becomes searchable. Expected lift: semantic R@5 87.2 → >92,
+-- hybrid R@5 94.6 → >96.
+--
+-- Schema choices:
+--   * Auxiliary columns (+session_id, +chunk_idx) so KNN queries return
+--     session attribution without a join.
+--   * Separate session_chunk_map keyed on session_id supports
+--     `DELETE FROM session_embedding_chunks WHERE chunk_id IN
+--     (SELECT chunk_id FROM session_chunk_map WHERE session_id = ?)`
+--     since vec0 has no documented filtering on aux columns.
+--
+-- session_embeddings (single-vector) is intentionally left in place:
+--   * keeps rollback trivial (revert recall code, old vectors still there)
+--   * avoids forcing a multi-hour re-embed at deploy time; backfill
+--     populates chunks asynchronously
+--   * a future cleanup migration drops it once chunks are validated
+
+CREATE VIRTUAL TABLE IF NOT EXISTS session_embedding_chunks USING vec0(
+  chunk_id   INTEGER PRIMARY KEY,
+  embedding  float[768],
+  +session_id TEXT,
+  +chunk_idx  INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS session_chunk_map (
+  chunk_id   INTEGER PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  chunk_idx  INTEGER NOT NULL,
+  FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_session_chunk_map_session
+  ON session_chunk_map(session_id);
+
+INSERT OR IGNORE INTO schema_migrations (version, name)
+  VALUES (9, '009_session_embedding_chunks');

package/migrations/010_sources_opencode.sql

@@ -0,0 +1,30 @@
+-- Migration 010: add 'opencode' to the sources.kind CHECK constraint.
+--
+-- SQLite does not support ALTER COLUMN to modify CHECK constraints in place.
+-- Standard approach: rename → recreate → copy → drop old.
+
+PRAGMA foreign_keys = OFF;
+
+CREATE TABLE sources_new (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  kind          TEXT    NOT NULL CHECK (kind IN ('claude-code', 'hermes', 'opencode', 'pi', 'jsonl-generic', 'webhook')),
+  name          TEXT    NOT NULL UNIQUE,
+  path_or_url   TEXT,
+  runtime_label TEXT    NOT NULL,
+  parse_config  TEXT    NOT NULL DEFAULT '{}',
+  enabled       INTEGER NOT NULL DEFAULT 1,
+  token         TEXT,
+  created_at    TEXT    NOT NULL DEFAULT (datetime('now')),
+  updated_at    TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+INSERT INTO sources_new SELECT id, kind, name, path_or_url, runtime_label, parse_config, enabled, token, created_at, updated_at FROM sources;
+
+DROP TABLE sources;
+ALTER TABLE sources_new RENAME TO sources;
+
+CREATE INDEX IF NOT EXISTS idx_sources_enabled ON sources(enabled) WHERE enabled = 1;
+
+PRAGMA foreign_keys = ON;
+
+INSERT OR IGNORE INTO schema_migrations (version, name) VALUES (10, '010_sources_opencode');

package/migrations/011_sources_hermes_agent.sql

@@ -0,0 +1,30 @@
+-- Migration 011: add 'hermes-agent' to the sources.kind CHECK constraint.
+--
+-- SQLite does not support ALTER COLUMN to modify CHECK constraints in place.
+-- Standard approach: rename → recreate → copy → drop old.
+
+PRAGMA foreign_keys = OFF;
+
+CREATE TABLE sources_new (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  kind          TEXT    NOT NULL CHECK (kind IN ('claude-code', 'hermes', 'hermes-agent', 'opencode', 'pi', 'jsonl-generic', 'webhook')),
+  name          TEXT    NOT NULL UNIQUE,
+  path_or_url   TEXT,
+  runtime_label TEXT    NOT NULL,
+  parse_config  TEXT    NOT NULL DEFAULT '{}',
+  enabled       INTEGER NOT NULL DEFAULT 1,
+  token         TEXT,
+  created_at    TEXT    NOT NULL DEFAULT (datetime('now')),
+  updated_at    TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+INSERT INTO sources_new SELECT id, kind, name, path_or_url, runtime_label, parse_config, enabled, token, created_at, updated_at FROM sources;
+
+DROP TABLE sources;
+ALTER TABLE sources_new RENAME TO sources;
+
+CREATE INDEX IF NOT EXISTS idx_sources_enabled ON sources(enabled) WHERE enabled = 1;
+
+PRAGMA foreign_keys = ON;
+
+INSERT OR IGNORE INTO schema_migrations (version, name) VALUES (11, '011_sources_hermes_agent');

package/migrations/012_sources_aider.sql

@@ -0,0 +1,30 @@
+-- Migration 012: add 'aider' to the sources.kind CHECK constraint.
+--
+-- SQLite does not support ALTER COLUMN to modify CHECK constraints in place.
+-- Standard approach: rename → recreate → copy → drop old.
+
+PRAGMA foreign_keys = OFF;
+
+CREATE TABLE sources_new (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  kind          TEXT    NOT NULL CHECK (kind IN ('claude-code', 'hermes', 'hermes-agent', 'aider', 'opencode', 'pi', 'jsonl-generic', 'webhook')),
+  name          TEXT    NOT NULL UNIQUE,
+  path_or_url   TEXT,
+  runtime_label TEXT    NOT NULL,
+  parse_config  TEXT    NOT NULL DEFAULT '{}',
+  enabled       INTEGER NOT NULL DEFAULT 1,
+  token         TEXT,
+  created_at    TEXT    NOT NULL DEFAULT (datetime('now')),
+  updated_at    TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+INSERT INTO sources_new SELECT id, kind, name, path_or_url, runtime_label, parse_config, enabled, token, created_at, updated_at FROM sources;
+
+DROP TABLE sources;
+ALTER TABLE sources_new RENAME TO sources;
+
+CREATE INDEX IF NOT EXISTS idx_sources_enabled ON sources(enabled) WHERE enabled = 1;
+
+PRAGMA foreign_keys = ON;
+
+INSERT OR IGNORE INTO schema_migrations (version, name) VALUES (12, '012_sources_aider');

package/migrations/013_adapter_state_failure_count.sql

@@ -0,0 +1,12 @@
+-- Migration 013: add failure_count to adapter_state.
+--
+-- Tracks consecutive classify/storage failures per source file. The scheduler
+-- skips files whose failure_count has reached the backoff ceiling (default 3)
+-- and whose file_size has not changed since the last attempt. When the file
+-- grows (new content appended), failure_count resets to 0 and the file is
+-- retried. This prevents a single permanently-broken or over-large transcript
+-- from flooding daemon-err.log on every 30-minute tick.
+
+ALTER TABLE adapter_state ADD COLUMN failure_count INTEGER NOT NULL DEFAULT 0;
+
+INSERT OR IGNORE INTO schema_migrations (version, name) VALUES (13, '013_adapter_state_failure_count');

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "nlm-memory",
+  "version": "0.4.0",
+  "description": "Local-first non-linear memory operating system for AI operators.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "nlm": "dist/cli/nlm.js"
+  },
+  "scripts": {
+    "dev": "tsx watch src/cli/nlm.ts start",
+    "start": "node dist/cli/nlm.js start",
+    "build:server": "tsc -p tsconfig.json && tsc-alias -p tsconfig.json",
+    "build:ui": "vite build --config src/ui/vite.config.ts",
+    "build:codex-plugin": "node scripts/build-codex-plugin.mjs",
+    "build": "npm run build:server && npm run build:ui && npm run build:codex-plugin",
+    "ui:dev": "vite --config src/ui/vite.config.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "lint": "eslint src tests"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.4.0",
+    "@hono/node-server": "^2.0.3",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@toon-format/toon": "^2.3.0",
+    "better-sqlite3": "^11.5.0",
+    "commander": "^12.1.0",
+    "hono": "^4.6.0",
+    "sqlite-vec": "^0.1.6",
+    "yaml": "^2.9.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.10.0",
+    "@types/react": "^18.3.28",
+    "@types/react-dom": "^18.3.7",
+    "@vitejs/plugin-react": "^4.7.0",
+    "esbuild": "^0.28.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.30.3",
+    "tsc-alias": "^1.8.17",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vite": "^5.4.21",
+    "vitest": "^2.1.0"
+  }
+}

package/plugin/.codex-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "nlm-memory",
+  "version": "0.3.0",
+  "description": "Local-first persistent memory for AI coding agents. Recalls relevant prior sessions on every prompt; learns which sessions actually get cited. Owner-edited timeline beats append-only memory layers.",
+  "author": {
+    "name": "Edward Chalupa",
+    "url": "https://github.com/pbmagnet4"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/pbmagnet4/nlm-memory-ts",
+  "repository": "https://github.com/pbmagnet4/nlm-memory-ts",
+  "keywords": [
+    "memory",
+    "context",
+    "recall",
+    "agent",
+    "rag",
+    "session"
+  ],
+  "mcpServers": "./.mcp.json",
+  "hooks": "./hooks/hooks.json"
+}

package/plugin/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "nlm-memory": {
+      "command": "nlm",
+      "args": ["mcp"]
+    }
+  }
+}

package/plugin/README.md

@@ -0,0 +1,51 @@
+# nlm-memory Codex plugin
+
+This directory is the Codex plugin distribution surface for nlm-memory. The
+repo root acts as a Codex marketplace (`codex plugin marketplace add
+pbmagnet4/nlm-memory-ts`), and this directory is the plugin Codex installs.
+
+## Install
+
+Prerequisite: `npm install -g nlm-memory` (puts `nlm` on PATH; the MCP server
+spawns `nlm mcp`).
+
+```bash
+codex plugin marketplace add pbmagnet4/nlm-memory-ts
+codex plugin add nlm-memory@nlm-memory-ts
+```
+
+Or use the wrapper: `nlm connect codex`.
+
+## What ships
+
+- **MCP server** (`.mcp.json`) — `recall_sessions`, `get_session`,
+  `recall_facts`, `get_fact_history`. Spawns `nlm mcp` over stdio.
+- **UserPromptSubmit hook** — injects up to 3 relevant prior sessions per
+  fire, capped at 10 per conversation. Fail-open: any error yields no
+  output, never blocks a prompt.
+- **Stop hook** — scans the assistant turn for cited session IDs and posts
+  citation events to the local daemon for learned reranking.
+
+## What doesn't
+
+Codex has no `SessionEnd` equivalent (CC does). The CC adapter uses
+SessionEnd to clean up per-conversation memo files in
+`~/.nlm/hook-state/`. The local daemon's `MemoSweepScheduler` (running every
+5m, 24h threshold) cleans those up regardless of runtime, so the absence is
+not a correctness issue — just a slight delay before stale memos are
+collected.
+
+## Hook trust
+
+Codex requires per-hash trust before any plugin hook executes. On first
+`codex` invocation after install, you'll be prompted to review and trust the
+hook scripts in `scripts/`. Approve them once; trust persists per script
+hash. Re-prompted whenever a new release ships new script hashes.
+
+## Codex Desktop fallback
+
+[openai/codex#16430](https://github.com/openai/codex/issues/16430) — Codex
+Desktop builds currently do not dispatch plugin-local hooks. MCP tools still
+work. If you're on Desktop, run `nlm connect codex --with-hooks` to write
+absolute paths to `~/.codex/hooks.json` as a fallback. Remove the fallback
+once #16430 ships.

package/plugin/hooks/hooks.json

@@ -0,0 +1,25 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/prompt-recall-hook.mjs\"",
+            "statusMessage": "nlm-memory: recalling prior sessions"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/stop-hook.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/scripts/prompt-recall-hook.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+
+// src/hook/prompt-recall-hook.ts
+import { pathToFileURL } from "node:url";
+
+// src/core/hook/gate.ts
+var LEADING_FILLER = /^(please|can you|could you|would you|will you|i need you to|i'd like you to|i want you to|i would like you to|help me|let's|lets|hey|ok|okay)\b[\s,]*/i;
+var GENERATIVE_OPENER = /^(write|draft|create|compose|generate|brainstorm|design|outline|sketch|invent|rename|come up with)\b/i;
+function classifyPrompt(prompt) {
+  let p = prompt.trim();
+  for (let i = 0; i < 3 && LEADING_FILLER.test(p); i++) {
+    p = p.replace(LEADING_FILLER, "");
+  }
+  return GENERATIVE_OPENER.test(p) ? "generative" : "evaluate";
+}
+
+// src/core/hook/hook-log.ts
+import { appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+function logPath() {
+  return process.env["NLM_HOOK_LOG"] ?? join(homedir(), ".nlm", "hook-log.jsonl");
+}
+function appendHookLog(entry) {
+  try {
+    const path = logPath();
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, `${JSON.stringify(entry)}
+`, "utf8");
+  } catch {
+  }
+}
+
+// src/core/hook/memo.ts
+import { existsSync, mkdirSync as mkdirSync2, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join2 } from "node:path";
+function stateDir() {
+  return process.env["NLM_HOOK_STATE_DIR"] ?? join2(homedir2(), ".nlm", "hook-state");
+}
+function memoPath(conversationId) {
+  const safe = conversationId.replace(/[^A-Za-z0-9_-]/g, "_") || "unknown";
+  return join2(stateDir(), `${safe}.json`);
+}
+function loadSurfaced(conversationId) {
+  try {
+    const path = memoPath(conversationId);
+    if (!existsSync(path)) return /* @__PURE__ */ new Set();
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!Array.isArray(parsed)) return /* @__PURE__ */ new Set();
+    return new Set(parsed.filter((x) => typeof x === "string"));
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
+function recordSurfaced(conversationId, ids) {
+  try {
+    const merged = loadSurfaced(conversationId);
+    for (const id of ids) merged.add(id);
+    mkdirSync2(stateDir(), { recursive: true });
+    writeFileSync(memoPath(conversationId), JSON.stringify([...merged]), "utf8");
+  } catch {
+  }
+}
+
+// src/core/hook/pointer-block.ts
+function formatPointerBlock(hits) {
+  if (hits.length === 0) return "";
+  const lines = hits.map(
+    (h) => `- ${h.id} \xB7 ${h.label} (${h.startedAt.slice(0, 10)})`
+  );
+  return [
+    "## Possibly-relevant prior sessions (nlm-memory)",
+    ...lines,
+    "NLM tools: recall_sessions (search), get_session (full transcript), recall_facts (prior decisions), get_fact_history (how a decision evolved)."
+  ].join("\n");
+}
+
+// src/core/hook/select.ts
+function selectHits(params) {
+  const { hits, surfaced, scoreThreshold, perFireCap, perConversationCap } = params;
+  const eligible = hits.filter(
+    (h) => h.matchScore >= scoreThreshold && !surfaced.has(h.id)
+  );
+  const budget = Math.max(0, perConversationCap - surfaced.size);
+  const limit = Math.min(perFireCap, budget);
+  return eligible.slice(0, limit);
+}
+
+// src/hook/prompt-recall-hook.ts
+var SCORE_THRESHOLD = 0;
+var PER_FIRE_CAP = 3;
+var PER_CONVERSATION_CAP = 10;
+var RECALL_LIMIT = 5;
+var RECALL_TIMEOUT_MS = 2e3;
+var PROMPT_PREVIEW_CHARS = 200;
+async function runHook(input, deps) {
+  const gate = classifyPrompt(input.prompt);
+  const preview = input.prompt.slice(0, PROMPT_PREVIEW_CHARS);
+  if (gate === "generative") {
+    appendHookLog({
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      conversationId: input.conversationId,
+      promptPreview: preview,
+      gate,
+      hits: [],
+      wouldInject: [],
+      estTokens: 0,
+      mode: deps.mode
+    });
+    return "";
+  }
+  let hits = [];
+  try {
+    hits = await deps.recall(input.prompt);
+  } catch {
+    hits = [];
+  }
+  const surfaced = loadSurfaced(input.conversationId);
+  const selected = selectHits({
+    hits,
+    surfaced,
+    scoreThreshold: SCORE_THRESHOLD,
+    perFireCap: PER_FIRE_CAP,
+    perConversationCap: PER_CONVERSATION_CAP
+  });
+  const block = formatPointerBlock(selected);
+  const estTokens = Math.ceil(block.length / 4);
+  appendHookLog({
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    conversationId: input.conversationId,
+    promptPreview: preview,
+    gate,
+    hits: hits.map((h) => ({ id: h.id, score: h.matchScore })),
+    wouldInject: selected.map((h) => h.id),
+    estTokens,
+    mode: deps.mode
+  });
+  if (deps.mode === "live" && selected.length > 0) {
+    recordSurfaced(input.conversationId, selected.map((h) => h.id));
+    return block;
+  }
+  return "";
+}
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => data += chunk);
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", () => resolve(data));
+  });
+}
+async function recallOverHttp(prompt) {
+  const portValue = process.env["NLM_PORT"] ?? "3940";
+  const url = `http://localhost:${portValue}/api/recall?q=${encodeURIComponent(prompt)}&mode=keyword&limit=${RECALL_LIMIT}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), RECALL_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      headers: { "x-recall-source": "hook" },
+      signal: controller.signal
+    });
+    if (!res.ok) return [];
+    let body;
+    try {
+      body = await res.json();
+    } catch {
+      return [];
+    }
+    return (body.results ?? []).map((r) => ({
+      id: r.id,
+      label: r.label,
+      startedAt: r.startedAt,
+      matchScore: r.matchScore
+    }));
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function main() {
+  try {
+    const raw = await readStdin();
+    const payload = JSON.parse(raw);
+    const prompt = typeof payload.prompt === "string" ? payload.prompt : "";
+    const conversationId = typeof payload.session_id === "string" ? payload.session_id : "unknown";
+    if (!prompt) return;
+    const mode = process.env["NLM_HOOK_MODE"] === "live" ? "live" : "shadow";
+    const out = await runHook(
+      { prompt, conversationId },
+      { mode, recall: recallOverHttp }
+    );
+    if (out) process.stdout.write(out);
+  } catch {
+  }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  void main();
+}
+export {
+  runHook
+};