nlm-memory 0.20.0 → 0.20.1

package/plugin/scripts/session-start-hook.mjs

@@ -21,7 +21,15 @@ function appendHookLog(entry) {
 }
 
 // src/core/hook/memo.ts
-import { existsSync, mkdirSync as mkdirSync2, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync as mkdirSync2,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from "node:fs";
 import { homedir as homedir2 } from "node:os";
 import { join as join2 } from "node:path";
 function stateDir() {
@@ -53,6 +61,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 = [];
@@ -61,7 +89,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})`);
       }
@@ -80,7 +108,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).";
@@ -89,10 +117,16 @@ 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);
@@ -149,12 +183,240 @@ function hookAuthHeaders(extra = {}) {
   return { ...extra, authorization: `Bearer ${token}` };
 }
 
+// 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/core/hook/query-extract.ts
+var STOPWORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "have",
+  "has",
+  "had",
+  "do",
+  "does",
+  "did",
+  "will",
+  "would",
+  "could",
+  "should",
+  "may",
+  "might",
+  "shall",
+  "can",
+  "dare",
+  "ought",
+  "yes",
+  "no",
+  "not",
+  "please",
+  "thank",
+  "thanks",
+  "ok",
+  "okay",
+  "i",
+  "me",
+  "my",
+  "we",
+  "us",
+  "our",
+  "you",
+  "your",
+  "it",
+  "its",
+  "this",
+  "that",
+  "these",
+  "those",
+  "and",
+  "or",
+  "but",
+  "if",
+  "so",
+  "to",
+  "of",
+  "in",
+  "on",
+  "at",
+  "by",
+  "for",
+  "from",
+  "with",
+  "about",
+  "into",
+  "through",
+  "during",
+  "before",
+  "after",
+  "above",
+  "below",
+  "up",
+  "down",
+  "out",
+  "off",
+  "over",
+  "under",
+  "again",
+  "further",
+  "then",
+  "once",
+  "here",
+  "there",
+  "when",
+  "where",
+  "why",
+  "how",
+  "all",
+  "both",
+  "each",
+  "few",
+  "more",
+  "most",
+  "other",
+  "some",
+  "such",
+  "than",
+  "too",
+  "very",
+  "just",
+  "now",
+  "also",
+  "get",
+  "let",
+  "what",
+  "which",
+  "who",
+  "whom",
+  "whose",
+  "any",
+  "much",
+  "many",
+  "sounds",
+  "good",
+  "great",
+  "sure",
+  "right",
+  "well",
+  "done",
+  "nice",
+  "cool",
+  "perfect",
+  "exactly",
+  "proceed",
+  "continue",
+  "go",
+  "ahead",
+  "next",
+  "help"
+]);
+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, mode = "keyword") {
+  const query = extractRecallQuery(prompt);
+  if (query === null) return { hits: [], facts: [], exemplars: [] };
+  const portValue = process.env["NLM_PORT"] ?? "3940";
+  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 fetchWithTimeout(url, { headers: hookAuthHeaders(extra) }, RECALL_TIMEOUT_MS);
+    if (!res.ok) return { hits: [], facts: [], exemplars: [] };
+    let body;
+    try {
+      body = await res.json();
+    } catch {
+      return { hits: [], facts: [], exemplars: [] };
+    }
+    const hits = (body.results ?? []).map((r) => ({
+      id: r.id,
+      label: r.label,
+      startedAt: r.startedAt,
+      matchScore: r.matchScore,
+      ...r.summary !== void 0 ? { summary: r.summary } : {}
+    }));
+    const facts = (body.relatedFacts ?? []).map((f) => ({
+      subject: f.subject,
+      predicate: f.predicate,
+      value: f.value,
+      corroborationCount: f.corroborationCount
+    }));
+    const exemplars = (body.relatedExemplars ?? []).map((e) => ({
+      outcome: e.outcome,
+      lang: e.lang,
+      repo: e.repo,
+      taskContext: e.taskContext
+    }));
+    return { hits, facts, exemplars };
+  } catch {
+    return { hits: [], facts: [], exemplars: [] };
+  }
+}
+
 // src/hook/session-start-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 RECALL_LIMIT = 5;
-var RECALL_TIMEOUT_MS = 2e3;
+var RECALL_TIMEOUT_MS2 = 2e3;
 async function runHook(input, deps) {
   let hits = [];
   try {
@@ -167,6 +429,7 @@ async function runHook(input, deps) {
     hits,
     surfaced,
     scoreThreshold: SCORE_THRESHOLD,
+    relativeFloor: RELATIVE_FLOOR,
     perFireCap: PER_FIRE_CAP,
     perConversationCap: PER_CONVERSATION_CAP
   });
@@ -194,21 +457,16 @@ function composeSessionStartOutput(failureModeBlock, recallBlock) {
 async function fetchFailureModeBlock(repo) {
   if (!repo) return "";
   const portValue = process.env["NLM_PORT"] ?? "3940";
-  const url = `http://localhost:${portValue}/api/signals/failure-modes?repo=${encodeURIComponent(repo)}`;
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), RECALL_TIMEOUT_MS);
+  const url = `http://127.0.0.1:${portValue}/api/signals/failure-modes?repo=${encodeURIComponent(repo)}`;
   try {
-    const res = await fetch(url, {
-      headers: hookAuthHeaders({ "x-recall-source": "session-start-hook" }),
-      signal: controller.signal
-    });
+    const res = await fetchWithTimeout(url, {
+      headers: hookAuthHeaders({ "x-recall-source": "session-start-hook" })
+    }, RECALL_TIMEOUT_MS2);
     if (!res.ok) return "";
     const body = await res.json();
     return typeof body.block === "string" ? body.block : "";
   } catch {
     return "";
-  } finally {
-    clearTimeout(timer);
   }
 }
 function buildQuery(workingDirectory, projectName) {
@@ -216,46 +474,6 @@ function buildQuery(workingDirectory, projectName) {
   const parts = [dirTail, projectName].filter(Boolean);
   return parts.join(" ").trim() || "session start";
 }
-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 recallOverHttp(query, conversationId) {
-  const portValue = process.env["NLM_PORT"] ?? "3940";
-  const url = `http://localhost:${portValue}/api/recall?q=${encodeURIComponent(query)}&mode=hybrid&limit=${RECALL_LIMIT}` + (conversationId ? `&conversation_id=${encodeURIComponent(conversationId)}` : "");
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), RECALL_TIMEOUT_MS);
-  try {
-    const res = await fetch(url, {
-      headers: hookAuthHeaders({
-        "x-recall-source": "session-start-hook",
-        "x-recall-runtime": "claude-code"
-      }),
-      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,
-      ...r.summary !== void 0 ? { summary: r.summary } : {}
-    }));
-  } finally {
-    clearTimeout(timer);
-  }
-}
 async function main() {
   try {
     autoloadEnv();
@@ -265,9 +483,17 @@ async function main() {
     const workingDirectory = typeof payload.cwd === "string" ? payload.cwd : typeof payload.working_directory === "string" ? payload.working_directory : "";
     const projectName = typeof payload.project_name === "string" ? payload.project_name : "";
     const query = buildQuery(workingDirectory, projectName);
-    const mode = process.env["NLM_HOOK_MODE"] === "live" ? "live" : "shadow";
-    const out = await runHook({ conversationId, query }, { mode, recall: (q, cid) => recallOverHttp(q, cid === "unknown" ? void 0 : cid) });
-    const failureModes = mode === "live" ? await fetchFailureModeBlock(workingDirectory) : "";
+    const mode = hookModeFromEnv();
+    const [out, failureModes] = await Promise.all([
+      runHook(
+        { conversationId, query },
+        {
+          mode,
+          recall: async (q, cid) => (await recallOverHttp(q, "claude-code", cid === "unknown" ? void 0 : cid, "hybrid")).hits
+        }
+      ),
+      mode === "live" ? fetchFailureModeBlock(workingDirectory) : Promise.resolve("")
+    ]);
     const combined = composeSessionStartOutput(failureModes, out);
     if (combined) process.stdout.write(combined);
   } catch {

package/plugin/scripts/stop-hook.mjs

@@ -2,9 +2,6 @@
 
 // src/hook/stop-hook.ts
 import { pathToFileURL } from "node:url";
-import { appendFileSync, mkdirSync as mkdirSync3 } from "node:fs";
-import { homedir as homedir5 } from "node:os";
-import { dirname as dirname2, join as join4 } from "node:path";
 
 // src/core/hook/citation-detect.ts
 var MIN_ID_LEN = 6;
@@ -96,7 +93,15 @@ function extractId(input) {
 }
 
 // src/core/hook/memo.ts
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 function stateDir() {
@@ -163,10 +168,10 @@ function isEnabled() {
   if (raw === void 0) return true;
   return raw !== "0" && raw.toLowerCase() !== "false";
 }
-async function appendMisses(entries, logPath2) {
+async function appendMisses(entries, logPath) {
   if (!isEnabled()) return;
   if (entries.length === 0) return;
-  const path = logPath2 ?? defaultLogPath();
+  const path = logPath ?? defaultLogPath();
   try {
     await mkdir(dirname(path), { recursive: true });
     const ts = (/* @__PURE__ */ new Date()).toISOString();
@@ -178,7 +183,7 @@ async function appendMisses(entries, logPath2) {
 }
 
 // src/core/hook/transcript.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
+import { closeSync, existsSync as existsSync3, fstatSync, openSync, readSync } from "node:fs";
 function parseTurn(parsed) {
   if (parsed.type !== "assistant" || !parsed.message) return null;
   const content = parsed.message.content;
@@ -198,10 +203,22 @@ function parseTurn(parsed) {
   if (textParts.length === 0 && toolUses.length === 0) return null;
   return { text: textParts.join("\n"), toolUses };
 }
+var MAX_TRANSCRIPT_BYTES = 256 * 1024;
 function readLines(transcriptPath) {
   if (!transcriptPath || !existsSync3(transcriptPath)) return null;
   try {
-    return readFileSync3(transcriptPath, "utf8").split("\n");
+    const fd = openSync(transcriptPath, "r");
+    try {
+      const size = fstatSync(fd).size;
+      const start = size > MAX_TRANSCRIPT_BYTES ? size - MAX_TRANSCRIPT_BYTES : 0;
+      const len = size - start;
+      if (len <= 0) return [];
+      const buf = Buffer.alloc(len);
+      readSync(fd, buf, 0, len, start);
+      return buf.toString("utf8").split("\n");
+    } finally {
+      closeSync(fd);
+    }
   } catch {
     return null;
   }
@@ -226,7 +243,7 @@ function readAllAssistantTurns(transcriptPath) {
 }
 
 // src/llm/env-autoload.ts
-import { readFileSync as readFileSync4, existsSync as existsSync4 } from "node:fs";
+import { readFileSync as readFileSync3, existsSync as existsSync4 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
 import { resolve } from "node:path";
 var DEFAULT_SEARCH_PATHS = [
@@ -246,7 +263,7 @@ function autoloadEnv(extraPaths = []) {
     const path = expandHome(raw);
     if (!existsSync4(path)) continue;
     try {
-      const content = readFileSync4(path, "utf8");
+      const content = readFileSync3(path, "utf8");
       for (const line of content.split("\n")) {
         const trimmed = line.trim();
         if (!trimmed || trimmed.startsWith("#") || !trimmed.includes("=")) continue;
@@ -275,6 +292,41 @@ function hookAuthHeaders(extra = {}) {
   return { ...extra, authorization: `Bearer ${token}` };
 }
 
+// src/hook/hook-helpers.ts
+import { appendFileSync, mkdirSync as mkdirSync3 } from "node:fs";
+import { homedir as homedir5 } from "node:os";
+import { dirname as dirname2, join as join4 } from "node:path";
+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";
+}
+function appendHookEvent(data) {
+  try {
+    const path = process.env["NLM_HOOK_LOG"] ?? join4(homedir5(), ".nlm", "hook-log.jsonl");
+    mkdirSync3(dirname2(path), { recursive: true });
+    appendFileSync(path, `${JSON.stringify(data)}
+`, "utf8");
+  } catch {
+  }
+}
+
 // src/hook/stop-hook.ts
 var RESPONSE_PREVIEW_CHARS = 200;
 var POST_TIMEOUT_MS = 1500;
@@ -335,12 +387,9 @@ async function runStopHook(input, deps) {
   }
   const lastText = turns[turns.length - 1]?.text ?? "";
   const preview = lastText.slice(0, RESPONSE_PREVIEW_CHARS);
-  for (const c of fresh) {
-    try {
-      await deps.postCitation(input.conversationId, c.id, c.kind, preview);
-    } catch {
-    }
-  }
+  await Promise.allSettled(
+    fresh.map((c) => deps.postCitation(input.conversationId, c.id, c.kind, preview))
+  );
   if (fresh.length > 0) {
     recordCited(input.conversationId, fresh.map((c) => c.id));
   }
@@ -352,60 +401,31 @@ async function runStopHook(input, deps) {
     skipped: false
   };
 }
-function logPath() {
-  return process.env["NLM_HOOK_LOG"] ?? join4(homedir5(), ".nlm", "hook-log.jsonl");
-}
 function logStopResult(result) {
-  try {
-    const path = logPath();
-    mkdirSync3(dirname2(path), { recursive: true });
-    appendFileSync(
-      path,
-      `${JSON.stringify({
-        ts: (/* @__PURE__ */ new Date()).toISOString(),
-        kind: "stop",
-        conversationId: result.conversationId,
-        surfacedCount: result.surfacedCount,
-        citedIds: result.citations.map((c) => c.id),
-        citationKinds: result.citations.map((c) => c.kind),
-        skipped: result.skipped,
-        mode: process.env["NLM_HOOK_MODE"] === "live" ? "live" : "shadow"
-      })}
-`,
-      "utf8"
-    );
-  } catch {
-  }
-}
-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));
+  appendHookEvent({
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    kind: "stop",
+    conversationId: result.conversationId,
+    surfacedCount: result.surfacedCount,
+    citedIds: result.citations.map((c) => c.id),
+    citationKinds: result.citations.map((c) => c.kind),
+    skipped: result.skipped,
+    mode: hookModeFromEnv()
   });
 }
 async function postCitationOverHttp(conversationId, citedId, kind, responsePreview) {
   const port = process.env["NLM_PORT"] ?? "3940";
-  const url = `http://localhost:${port}/api/recall/cite-event`;
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), POST_TIMEOUT_MS);
-  try {
-    await fetch(url, {
-      method: "POST",
-      headers: hookAuthHeaders({ "content-type": "application/json" }),
-      body: JSON.stringify({
-        ...conversationId !== "unknown" ? { conversation_id: conversationId } : {},
-        cited_id: citedId,
-        kind,
-        response_preview: responsePreview
-      }),
-      signal: controller.signal
-    });
-  } finally {
-    clearTimeout(timer);
-  }
+  const url = `http://127.0.0.1:${port}/api/recall/cite-event`;
+  await fetchWithTimeout(url, {
+    method: "POST",
+    headers: hookAuthHeaders({ "content-type": "application/json" }),
+    body: JSON.stringify({
+      ...conversationId !== "unknown" ? { conversation_id: conversationId } : {},
+      cited_id: citedId,
+      kind,
+      response_preview: responsePreview
+    })
+  }, POST_TIMEOUT_MS);
 }
 async function main() {
   try {

package/plugin-hermes-agent/__init__.py

@@ -9,6 +9,7 @@ The daemon must be running for hooks to have effect. If it is unreachable,
 every hook silently returns None so the agent loop is never blocked.
 """
 
+import http.client
 import json
 import os
 import urllib.error
@@ -33,7 +34,7 @@ def _post(path: str, payload: dict[str, Any]) -> dict[str, Any]:
     try:
         with urllib.request.urlopen(req, timeout=5) as resp:
             return json.loads(resp.read())
-    except (urllib.error.URLError, OSError, json.JSONDecodeError):
+    except (urllib.error.URLError, OSError, json.JSONDecodeError, http.client.HTTPException):
         return {}
 
 

package/templates/agent-contract/README.md

@@ -0,0 +1,24 @@
+# Agent Contract Templates
+
+These templates teach an agent the recall contract for working effectively with NLM Memory.
+
+## Variants
+
+- `claude-code.md` - CLAUDE.md-ready markdown section (heading + rules). Drop it into any Claude Code project's CLAUDE.md, or use `nlm init --agent claude-code --write CLAUDE.md`.
+- `generic.md` - Tool-agnostic prose for any agent instruction file. Use `nlm init --agent generic --write <path>`.
+
+## Usage
+
+```sh
+# Print to stdout
+nlm init --agent claude-code
+nlm init --agent generic
+
+# Append to a file (adds begin/end markers; refuses if markers already exist)
+nlm init --agent claude-code --write CLAUDE.md
+
+# Replace the block in place when markers already exist
+nlm init --agent claude-code --write CLAUDE.md --force
+```
+
+The block is delimited by `<!-- nlm-agent-contract:begin -->` and `<!-- nlm-agent-contract:end -->` so re-runs detect it and refuse to duplicate without `--force`.