nlm-memory 0.19.0 → 0.20.1

package/migrations/pg/025_workstreams.sql

@@ -0,0 +1,34 @@
+-- migrations/pg/025_workstreams.sql
+-- PG parity for SQLite migration 025 (workstreams). Auto-applied by the
+-- version-gated runner (runMigrationsPg). Idempotent: every DDL statement uses
+-- IF NOT EXISTS or ADD COLUMN IF NOT EXISTS, so re-applying on an existing
+-- schema is a no-op. Mirrors migrations/025_workstreams.sql.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS workstreams (
+  id              TEXT PRIMARY KEY,
+  label           TEXT NOT NULL,
+  status          TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','merged','retired')),
+  merged_into     TEXT REFERENCES workstreams(id),
+  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  last_session_at TIMESTAMPTZ
+);
+
+CREATE TABLE IF NOT EXISTS workstream_entities (
+  workstream_id    TEXT NOT NULL REFERENCES workstreams(id) ON DELETE CASCADE,
+  entity_canonical TEXT NOT NULL REFERENCES entities(canonical),
+  session_count    INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (workstream_id, entity_canonical)
+);
+
+CREATE INDEX IF NOT EXISTS idx_workstream_entities_entity ON workstream_entities(entity_canonical);
+
+ALTER TABLE sessions ADD COLUMN IF NOT EXISTS workstream_id TEXT REFERENCES workstreams(id);
+ALTER TABLE sessions ADD COLUMN IF NOT EXISTS binding_source TEXT;
+ALTER TABLE sessions ADD COLUMN IF NOT EXISTS binding_confidence DOUBLE PRECISION;
+
+CREATE INDEX IF NOT EXISTS idx_sessions_workstream ON sessions(workstream_id);
+
+COMMIT;

package/migrations/pg/026_embedding_config.sql

@@ -0,0 +1,12 @@
+-- Records which embedder produced the stored vectors, per lane.
+-- lane 'prose' covers session chunks and fact embeddings (same embedder);
+-- lane 'code' covers code exemplar embeddings.
+-- Absence of a row means pre-tracking corpus: reconcile treats the running
+-- embedder as canonical and records it.
+CREATE TABLE IF NOT EXISTS embedding_config (
+  lane       TEXT PRIMARY KEY CHECK (lane IN ('prose', 'code')),
+  provider   TEXT NOT NULL,
+  model      TEXT NOT NULL,
+  dim        INTEGER NOT NULL,
+  updated_at TEXT NOT NULL
+);

package/migrations/pg/028_classifier_provenance.sql

@@ -0,0 +1,5 @@
+-- Which classifier produced this session's classification. NULL = classified
+-- before provenance tracking; nlm reprocess treats NULL as eligible.
+ALTER TABLE sessions ADD COLUMN IF NOT EXISTS classifier_provider TEXT;
+ALTER TABLE sessions ADD COLUMN IF NOT EXISTS classifier_model TEXT;
+ALTER TABLE sessions ADD COLUMN IF NOT EXISTS classifier_confidence REAL;

package/migrations/pg/029_entity_variants.sql

@@ -0,0 +1,9 @@
+-- Entity variant alias table. Tracks merged surface forms so re-ingest of an
+-- old spelling binds to the canonical entity instead of resurrecting the source.
+CREATE TABLE IF NOT EXISTS entity_variants (
+  variant           TEXT PRIMARY KEY,
+  canonical         TEXT NOT NULL REFERENCES entities(canonical) ON DELETE CASCADE,
+  source_session_id TEXT REFERENCES sessions(id) ON DELETE SET NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_entity_variants_canonical ON entity_variants(canonical);

package/nlm/index.js

@@ -181,30 +181,55 @@ var STOPWORDS = /* @__PURE__ */ new Set([
 ]);
 var MIN_CONTENT_WORDS = 2;
 var MIN_WORD_LEN = 3;
+var SYSTEM_MESSAGE_PREFIX = /^<(task-notification|command-name|command-message|command-args|local-command-stdout|local-command-caveat|output-file|system-reminder)\b/;
 function extractRecallQuery(prompt) {
+  if (SYSTEM_MESSAGE_PREFIX.test(prompt.trim())) return null;
   const tokens = prompt.trim().split(/\s+/).map((t) => t.replace(/^[^\w-]+|[^\w-]+$/g, "")).filter((t) => t.length >= MIN_WORD_LEN);
   const contentWords = tokens.filter((t) => !STOPWORDS.has(t.toLowerCase()));
   if (contentWords.length < MIN_CONTENT_WORDS) return null;
   return contentWords.join(" ");
 }
 
+// src/hook/hook-helpers.ts
+function readStdin() {
+  return new Promise((resolve2) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => data += chunk);
+    process.stdin.on("end", () => resolve2(data));
+    process.stdin.on("error", () => resolve2(data));
+  });
+}
+async function fetchWithTimeout(url, init, ms) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ms);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function hookModeFromEnv() {
+  return process.env["NLM_HOOK_MODE"] === "live" ? "live" : "shadow";
+}
+
 // src/hook/recall-over-http.ts
 var RECALL_LIMIT = 5;
 var RECALL_TIMEOUT_MS = 2e3;
-async function recallOverHttp(prompt, runtime, conversationId) {
+async function recallOverHttp(prompt, runtime, conversationId, mode = "keyword") {
   const query = extractRecallQuery(prompt);
   if (query === null) return { hits: [], facts: [], exemplars: [] };
   const portValue = process.env["NLM_PORT"] ?? "3940";
-  const url = `http://localhost:${portValue}/api/recall?q=${encodeURIComponent(query)}&mode=keyword&limit=${RECALL_LIMIT}&withFacts=true&withExemplars=true` + (conversationId ? `&conversation_id=${encodeURIComponent(conversationId)}` : "");
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), RECALL_TIMEOUT_MS);
+  const url = (
+    // 127.0.0.1, not localhost: each hook is a fresh process with no connection
+    // reuse, and Node resolves localhost to IPv6 ::1 first — a measured ~50-300ms
+    // per-fire connect penalty vs ~3ms on the explicit IPv4 loopback.
+    `http://127.0.0.1:${portValue}/api/recall?q=${encodeURIComponent(query)}&mode=${mode}&limit=${RECALL_LIMIT}&withFacts=true&withExemplars=true` + (conversationId ? `&conversation_id=${encodeURIComponent(conversationId)}` : "")
+  );
   try {
     const extra = { "x-recall-source": "hook" };
     if (runtime) extra["x-recall-runtime"] = runtime;
-    const res = await fetch(url, {
-      headers: hookAuthHeaders(extra),
-      signal: controller.signal
-    });
+    const res = await fetchWithTimeout(url, { headers: hookAuthHeaders(extra) }, RECALL_TIMEOUT_MS);
     if (!res.ok) return { hits: [], facts: [], exemplars: [] };
     let body;
     try {
@@ -232,8 +257,8 @@ async function recallOverHttp(prompt, runtime, conversationId) {
       taskContext: e.taskContext
     }));
     return { hits, facts, exemplars };
-  } finally {
-    clearTimeout(timer);
+  } catch {
+    return { hits: [], facts: [], exemplars: [] };
   }
 }
 
@@ -243,14 +268,192 @@ 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;
+var HARNESS_TAGS = [
+  "ide_selection",
+  "ide_opened_file",
+  "ide_closed_file",
+  "ide_diagnostics",
+  "ide_recently_modified_file",
+  "task-notification",
+  "system-reminder",
+  "command-name",
+  "command-message",
+  "command-args",
+  "local-command-stdout",
+  "local-command-stderr"
+];
+var HARNESS_BLOCK = new RegExp(
+  `<(${HARNESS_TAGS.join("|")})\\b[^>]*>[\\s\\S]*?(?:</\\1>|$)`,
+  "gi"
+);
+var ACK_ONLY = /^(yes|yep|yeah|sure|ok|okay|k|thanks|thank you|ty|done|nice|cool|great|perfect|continue|next|go|go ahead|do it|yes please|sounds good|good|got it|right|correct)\W*$/i;
+function contentWordCount(s) {
+  const m = s.match(/[A-Za-z0-9]{2,}/g);
+  return m ? m.length : 0;
+}
 function classifyPrompt(prompt) {
-  let p = prompt.trim();
+  let p = prompt.replace(HARNESS_BLOCK, " ").replace(/\s+/g, " ").trim();
+  if (contentWordCount(p) === 0) return "skip";
+  if (ACK_ONLY.test(p)) return "skip";
   for (let i = 0; i < 3 && LEADING_FILLER.test(p); i++) {
     p = p.replace(LEADING_FILLER, "");
   }
+  p = p.trim();
+  if (contentWordCount(p) === 0) return "skip";
   return GENERATIVE_OPENER.test(p) ? "generative" : "evaluate";
 }
 
+// src/hook/recent-context.ts
+import { closeSync, existsSync as existsSync2, fstatSync, openSync, readSync } from "node:fs";
+var DEFAULT_MAX_TURNS = 3;
+var DEFAULT_MAX_BYTES = 64 * 1024;
+var DEFAULT_PER_TURN_CHARS = 400;
+var STOPWORDS2 = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "and",
+  "or",
+  "but",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "do",
+  "does",
+  "did",
+  "doing",
+  "you",
+  "your",
+  "i",
+  "we",
+  "our",
+  "it",
+  "its",
+  "this",
+  "that",
+  "these",
+  "those",
+  "what",
+  "which",
+  "how",
+  "why",
+  "when",
+  "where",
+  "who",
+  "can",
+  "could",
+  "would",
+  "should",
+  "will",
+  "shall",
+  "may",
+  "might",
+  "must",
+  "please",
+  "to",
+  "of",
+  "in",
+  "on",
+  "for",
+  "with",
+  "so",
+  "now",
+  "then",
+  "here",
+  "there",
+  "just",
+  "also",
+  "as",
+  "at",
+  "by",
+  "if",
+  "my",
+  "me",
+  "us",
+  "ok",
+  "okay",
+  "yes",
+  "no",
+  "not",
+  "up",
+  "out",
+  "go",
+  "get",
+  "got",
+  "make",
+  "made",
+  "give",
+  "tell",
+  "want",
+  "need",
+  "think",
+  "know",
+  "let",
+  "lets",
+  "about",
+  "from",
+  "into"
+]);
+function topicalWordCount(s) {
+  const tokens = s.toLowerCase().match(/[a-z0-9]{2,}/g) ?? [];
+  return tokens.filter((t) => !STOPWORDS2.has(t)).length;
+}
+function textOf(message) {
+  if (typeof message !== "object" || message === null) return "";
+  const content = message.content;
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content.filter(
+      (b) => typeof b === "object" && b !== null && b.type === "text"
+    ).map((b) => b.text).join(" ");
+  }
+  return "";
+}
+function tailRead(path, maxBytes) {
+  const fd = openSync(path, "r");
+  try {
+    const size = fstatSync(fd).size;
+    const start = size > maxBytes ? size - maxBytes : 0;
+    const len = size - start;
+    if (len <= 0) return "";
+    const buf = Buffer.alloc(len);
+    readSync(fd, buf, 0, len, start);
+    return buf.toString("utf8");
+  } finally {
+    closeSync(fd);
+  }
+}
+function recentConversationContext(transcriptPath, opts = {}) {
+  try {
+    if (!transcriptPath || !existsSync2(transcriptPath)) return "";
+    const maxTurns = opts.maxTurns ?? DEFAULT_MAX_TURNS;
+    const perTurnChars = opts.perTurnChars ?? DEFAULT_PER_TURN_CHARS;
+    const lines = tailRead(transcriptPath, opts.maxBytes ?? DEFAULT_MAX_BYTES).split("\n");
+    const turns = [];
+    for (let i = lines.length - 1; i >= 0 && turns.length < maxTurns; i--) {
+      const line = lines[i].trim();
+      if (!line) continue;
+      let evt;
+      try {
+        evt = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (evt.type !== "user" && evt.type !== "assistant") continue;
+      const text = textOf(evt.message).trim();
+      if (!text) continue;
+      turns.unshift(text.slice(0, perTurnChars));
+    }
+    return turns.join(" ").trim();
+  } catch {
+    return "";
+  }
+}
+
 // src/core/hook/hook-log.ts
 import { appendFileSync, mkdirSync } from "node:fs";
 import { homedir as homedir2 } from "node:os";
@@ -269,7 +472,15 @@ function appendHookLog(entry) {
 }
 
 // src/core/hook/memo.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync, writeFileSync } from "node:fs";
+import {
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync2,
+  readdirSync,
+  readFileSync as readFileSync2,
+  rmSync,
+  statSync,
+  writeFileSync
+} from "node:fs";
 import { homedir as homedir3 } from "node:os";
 import { join as join2 } from "node:path";
 function stateDir() {
@@ -282,7 +493,7 @@ function memoPath(conversationId) {
 function loadSurfaced(conversationId) {
   try {
     const path = memoPath(conversationId);
-    if (!existsSync2(path)) return /* @__PURE__ */ new Set();
+    if (!existsSync3(path)) return /* @__PURE__ */ new Set();
     const parsed = JSON.parse(readFileSync2(path, "utf8"));
     if (!Array.isArray(parsed)) return /* @__PURE__ */ new Set();
     return new Set(parsed.filter((x) => typeof x === "string"));
@@ -301,6 +512,26 @@ function recordSurfaced(conversationId, ids) {
 }
 
 // src/core/hook/pointer-block.ts
+function truncateSummary(s, max = 200) {
+  if (s.length <= max) return s;
+  const window = s.slice(0, max);
+  const last = window[window.length - 1];
+  if ((last === "." || last === "!" || last === "?") && window.length - 1 >= 60) {
+    return window;
+  }
+  for (let i = window.length - 2; i >= 60; i--) {
+    const c = window[i];
+    if ((c === "." || c === "!" || c === "?") && window[i + 1] === " ") {
+      return s.slice(0, i + 1);
+    }
+  }
+  for (let i = window.length - 1; i >= 60; i--) {
+    if (window[i] === " ") {
+      return s.slice(0, i) + " ...";
+    }
+  }
+  return window + " ...";
+}
 function formatPointerBlock(hits, facts = [], exemplars = []) {
   if (hits.length === 0 && facts.length === 0 && exemplars.length === 0) return "";
   const out = [];
@@ -309,7 +540,7 @@ function formatPointerBlock(hits, facts = [], exemplars = []) {
     for (const h of hits) {
       const datePart = h.startedAt.slice(0, 10);
       if (h.summary) {
-        out.push(`- ${h.id} \xB7 ${h.label} (${datePart}) \u2014 ${h.summary.slice(0, 120)}`);
+        out.push(`- ${h.id} \xB7 ${h.label} (${datePart}) \u2014 ${truncateSummary(h.summary)}`);
       } else {
         out.push(`- ${h.id} \xB7 ${h.label} (${datePart})`);
       }
@@ -328,7 +559,7 @@ function formatPointerBlock(hits, facts = [], exemplars = []) {
     out.push("## Related code exemplars (nlm-memory)");
     for (const e of exemplars) {
       const langPart = e.lang ? `${e.lang} \xB7 ` : "";
-      out.push(`- [${e.outcome}] ${langPart}${e.repo} - ${e.taskContext.slice(0, 120)}`);
+      out.push(`- [${e.outcome}] ${langPart}${e.repo} - ${truncateSummary(e.taskContext)}`);
     }
   }
   const tools = exemplars.length > 0 ? "NLM tools: recall_sessions (search), get_session (full transcript), recall_facts (prior decisions), get_fact_history (how a decision evolved), recall_code (pull the full code for a related exemplar)." : "NLM tools: recall_sessions (search), get_session (full transcript), recall_facts (prior decisions), get_fact_history (how a decision evolved).";
@@ -337,25 +568,125 @@ function formatPointerBlock(hits, facts = [], exemplars = []) {
 }
 
 // src/core/hook/select.ts
+function medianScore(hits) {
+  if (hits.length === 0) return 0;
+  const sorted = hits.map((h) => h.matchScore).sort((a, b) => a - b);
+  return sorted[Math.floor(sorted.length / 2)] ?? 0;
+}
 function selectHits(params) {
-  const { hits, surfaced, scoreThreshold, perFireCap, perConversationCap } = params;
+  const { hits, surfaced, scoreThreshold, perFireCap, perConversationCap, relativeFloor = 0 } = params;
+  const relCut = relativeFloor > 0 ? relativeFloor * medianScore(hits) : 0;
   const eligible = hits.filter(
-    (h) => h.matchScore >= scoreThreshold && !surfaced.has(h.id)
+    (h) => h.matchScore >= scoreThreshold && h.matchScore >= relCut && !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/score-floor.ts
+function parseScoreFloor(raw) {
+  if (raw === void 0) return 0;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) return 0;
+  return parsed;
+}
+function parseRelativeFloor(raw, fallback) {
+  if (raw === void 0) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) return fallback;
+  return parsed;
+}
+
+// src/hook/recall-gate.ts
+var RECALL_GATE_MODEL = "qwen3.5:4b";
+var RECALL_GATE_SYSTEM = `You are a recall GATE protecting against off-topic memory injection. Given a USER PROMPT and a CANDIDATE prior-session context, answer irrelevant ONLY when the candidate is CLEARLY about a completely different topic, project, or task than the prompt (e.g. the prompt is about debugging a website and the candidate is about a trading pipeline). If there is ANY plausible topical connection, or you are at all unsure, answer relevant. Dropping a useful memory is worse than keeping a marginal one. You do NOT see the assistant's answer. Output {"gate":"relevant"|"irrelevant"}.`;
+var GATE_FORMAT = { type: "object", properties: { gate: { type: "string", enum: ["relevant", "irrelevant"] } }, required: ["gate"] };
+var GATE_OPTS = { temperature: 0, top_p: 1, top_k: 0, presence_penalty: 0, frequency_penalty: 0 };
+function parseRecallGateMode(env = process.env) {
+  const v = env["NLM_HOOK_RECALL_GATE"]?.trim();
+  return v === "shadow" || v === "live" ? v : void 0;
+}
+var GATE_TIMEOUT_MS = 4e3;
+function makeOllamaGate(url, model = RECALL_GATE_MODEL, timeoutMs = GATE_TIMEOUT_MS) {
+  return async (prompt, candidate) => {
+    try {
+      const r = await fetchWithTimeout(
+        `${url}/api/chat`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            model,
+            stream: false,
+            think: false,
+            // Keep the gate model resident between fires so only the first fire
+            // pays the cold-load; subsequent gates are ~1 judge call.
+            keep_alive: "15m",
+            format: GATE_FORMAT,
+            options: GATE_OPTS,
+            messages: [
+              { role: "system", content: RECALL_GATE_SYSTEM },
+              { role: "user", content: `USER PROMPT:
+${prompt}
+
+CANDIDATE CONTEXT:
+${candidate}` }
+            ]
+          })
+        },
+        timeoutMs
+      );
+      const d = await r.json();
+      const v = JSON.parse(d.message?.content ?? "{}").gate;
+      return v === "irrelevant" ? "irrelevant" : "relevant";
+    } catch {
+      return "relevant";
+    }
+  };
+}
+
 // src/hook/prompt-recall-hook.ts
-var SCORE_THRESHOLD = 0;
+var SCORE_THRESHOLD = parseScoreFloor(process.env["NLM_RECALL_SCORE_FLOOR"]);
+var RELATIVE_FLOOR = parseRelativeFloor(process.env["NLM_RECALL_REL_FLOOR"], 0.9);
 var PER_FIRE_CAP = 3;
 var PER_CONVERSATION_CAP = 10;
 var PROMPT_PREVIEW_CHARS = 200;
+function parseHookDeadline(raw) {
+  if (raw === void 0) return 4e3;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : 4e3;
+}
+var HOOK_DEADLINE_MS = parseHookDeadline(process.env["NLM_HOOK_DEADLINE_MS"]);
+async function withDeadline(p, ms, fallback) {
+  if (ms <= 0) return fallback;
+  let timer;
+  const timeout = new Promise((resolve2) => {
+    timer = setTimeout(() => resolve2(fallback), ms);
+  });
+  try {
+    return await Promise.race([p, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
 function hookRuntimeFromEnv(env = process.env) {
   const raw = env["NLM_HOOK_RUNTIME"]?.trim();
   return raw ? raw : "claude-code";
 }
+function promptRecallEnabled(env = process.env) {
+  const raw = env["NLM_HOOK_PROMPT_RECALL"]?.trim();
+  if (raw === void 0 || raw === "") return false;
+  return raw.toLowerCase() !== "off";
+}
+function buildRecallQuery(input, env = process.env) {
+  if (env["NLM_HOOK_CONTEXT_RECALL"] !== "1") return input.prompt;
+  if (!input.transcriptPath) return input.prompt;
+  const minWords = Number.parseInt(env["NLM_HOOK_CONTEXT_MIN_WORDS"] ?? "3", 10);
+  if (topicalWordCount(input.prompt) >= minWords) return input.prompt;
+  const context = recentConversationContext(input.transcriptPath);
+  return context ? `${context} ${input.prompt}` : input.prompt;
+}
 function normalizeRecall(raw) {
   if (Array.isArray(raw)) return { hits: raw, facts: [] };
   return raw;
@@ -363,7 +694,7 @@ function normalizeRecall(raw) {
 async function runHook(input, deps) {
   const gate = classifyPrompt(input.prompt);
   const preview = input.prompt.slice(0, PROMPT_PREVIEW_CHARS);
-  if (gate === "generative") {
+  if (gate === "generative" || gate === "skip") {
     appendHookLog({
       ts: (/* @__PURE__ */ new Date()).toISOString(),
       conversationId: input.conversationId,
@@ -376,9 +707,12 @@ async function runHook(input, deps) {
     });
     return "";
   }
+  const deadline = Date.now() + (deps.deadlineMs ?? HOOK_DEADLINE_MS);
   let fetched = { hits: [], facts: [] };
   try {
-    fetched = normalizeRecall(await deps.recall(input.prompt));
+    fetched = normalizeRecall(
+      await withDeadline(deps.recall(buildRecallQuery(input)), deadline - Date.now(), { hits: [], facts: [] })
+    );
   } catch {
     fetched = { hits: [], facts: [] };
   }
@@ -388,10 +722,33 @@ async function runHook(input, deps) {
     hits,
     surfaced,
     scoreThreshold: SCORE_THRESHOLD,
+    relativeFloor: RELATIVE_FLOOR,
     perFireCap: PER_FIRE_CAP,
     perConversationCap: PER_CONVERSATION_CAP
   });
-  const block = formatPointerBlock(selected, fetched.facts, fetched.exemplars);
+  let gateDecisions;
+  let injected = selected;
+  if (deps.recallGate && selected.length > 0) {
+    const g = deps.recallGate;
+    const toGate = g.maxCandidates ? selected.slice(0, g.maxCandidates) : selected;
+    const remaining = deadline - Date.now();
+    const gateFallback = toGate.map((h) => ({ id: h.id, gate: "relevant" }));
+    if (remaining <= 0) {
+      gateDecisions = gateFallback;
+    } else {
+      gateDecisions = await withDeadline(
+        Promise.all(toGate.map(async (h) => ({ id: h.id, gate: await g.judge(input.prompt, `${h.label}
+${h.summary ?? ""}`) }))),
+        remaining,
+        gateFallback
+      );
+    }
+    if (g.mode === "live") {
+      const drop = new Set(gateDecisions.filter((d) => d.gate === "irrelevant").map((d) => d.id));
+      injected = selected.filter((h) => !drop.has(h.id));
+    }
+  }
+  const block = formatPointerBlock(injected, fetched.facts, fetched.exemplars);
   const estTokens = Math.ceil(block.length / 4);
   appendHookLog({
     ts: (/* @__PURE__ */ new Date()).toISOString(),
@@ -399,25 +756,17 @@ async function runHook(input, deps) {
     promptPreview: preview,
     gate,
     hits: hits.map((h) => ({ id: h.id, score: h.matchScore })),
-    wouldInject: selected.map((h) => h.id),
+    wouldInject: injected.map((h) => h.id),
     estTokens,
-    mode: deps.mode
+    mode: deps.mode,
+    ...gateDecisions ? { gateDecisions } : {}
   });
-  if (deps.mode === "live" && selected.length > 0) {
-    recordSurfaced(input.conversationId, selected.map((h) => h.id));
+  if (deps.mode === "live" && injected.length > 0) {
+    recordSurfaced(input.conversationId, injected.map((h) => h.id));
     return block;
   }
   return "";
 }
-function readStdin() {
-  return new Promise((resolve2) => {
-    let data = "";
-    process.stdin.setEncoding("utf8");
-    process.stdin.on("data", (chunk) => data += chunk);
-    process.stdin.on("end", () => resolve2(data));
-    process.stdin.on("error", () => resolve2(data));
-  });
-}
 async function main() {
   try {
     autoloadEnv();
@@ -425,12 +774,21 @@ async function main() {
     const payload = JSON.parse(raw);
     const prompt = typeof payload.prompt === "string" ? payload.prompt : "";
     const conversationId = typeof payload.session_id === "string" ? payload.session_id : "unknown";
+    const transcriptPath = typeof payload.transcript_path === "string" ? payload.transcript_path : void 0;
     if (!prompt) return;
-    const mode = process.env["NLM_HOOK_MODE"] === "live" ? "live" : "shadow";
+    if (!promptRecallEnabled()) return;
+    const mode = hookModeFromEnv();
     const runtime = hookRuntimeFromEnv();
+    const gateMode = parseRecallGateMode();
+    const gateUrl = process.env["OLLAMA_URL"] ?? "http://127.0.0.1:11434";
+    const gateTopN = Math.max(1, Number.parseInt(process.env["NLM_HOOK_RECALL_GATE_TOPN"] ?? "1", 10) || 1);
     const out = await runHook(
-      { prompt, conversationId },
-      { mode, recall: (q) => recallOverHttp(q, runtime, conversationId === "unknown" ? void 0 : conversationId) }
+      { prompt, conversationId, ...transcriptPath ? { transcriptPath } : {} },
+      {
+        mode,
+        recall: (q) => recallOverHttp(q, runtime, conversationId === "unknown" ? void 0 : conversationId),
+        ...gateMode ? { recallGate: { mode: gateMode, judge: makeOllamaGate(gateUrl), maxCandidates: gateTopN } } : {}
+      }
     );
     if (out) process.stdout.write(out);
   } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nlm-memory",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "description": "Local-first non-linear memory operating system for AI operators.",
   "type": "module",
   "license": "Apache-2.0",
@@ -29,6 +29,8 @@
   "files": [
     "dist",
     "migrations",
+    "fixtures",
+    "templates",
     "plugin",
     "plugin-hermes-agent",
     "nlm",
@@ -52,16 +54,24 @@
     "test:watch": "vitest",
     "test:unit": "vitest run tests/unit",
     "test:integration": "vitest run tests/integration",
+    "test:pg": "vitest run --no-file-parallelism .pg.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
     "bench:longmemeval": "tsx scripts/longmemeval/run-harness.ts",
     "bench:classifier": "tsx scripts/longmemeval/run-harness.ts --classifier",
     "bench:compare": "tsx scripts/longmemeval/compare-classifiers.ts",
     "eval:signals": "tsx scripts/eval/signals-eval.ts",
-    "eval:classifier": "tsx scripts/eval/classifier-eval.ts"
+    "eval:classifier": "tsx scripts/eval/classifier-eval.ts",
+    "eval:fact-recall": "tsx scripts/eval/fact-recall-eval.ts",
+    "eval:code-exemplar": "tsx scripts/eval/code-exemplar-eval.ts",
+    "eval:reranker": "tsx scripts/eval/reranker-ablation.ts",
+    "eval:floor": "tsx scripts/eval/floor-calibration.ts",
+    "eval:matcher": "tsx scripts/eval/tune-matcher.ts",
+    "eval:naming": "tsx scripts/eval/tune-naming.ts"
   },
   "dependencies": {
     "@clack/prompts": "^1.4.0",
     "@hono/node-server": "^2.0.3",
+    "@huggingface/transformers": "4.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@toon-format/toon": "^2.3.0",
     "better-sqlite3": "^12.10.0",