nlm-memory 0.20.1 → 0.21.12

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

@@ -1,8 +1,5 @@
 #!/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;
@@ -194,16 +191,159 @@ function recentConversationContext(transcriptPath, opts = {}) {
 
 // src/core/hook/hook-log.ts
 import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+// src/core/tenancy/tenant-state-path.ts
+import { createHash } from "node:crypto";
 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");
+import { join } from "node:path";
+
+// src/core/tenancy/default-team.ts
+var DEFAULT_TEAM_ID = "team_local";
+
+// src/core/tenancy/tenant-state-path.ts
+var TENANTS_DIRNAME = "tenants";
+var SAFE_TENANT_ID = /^[A-Za-z0-9_-]+$/;
+function sanitizeTenantId(tenantId) {
+  if (SAFE_TENANT_ID.test(tenantId)) return tenantId;
+  const sanitized = tenantId.replace(/[^A-Za-z0-9_-]/g, "_") || "unknown";
+  const hash = createHash("sha256").update(tenantId).digest("hex").slice(0, 8);
+  return `${sanitized}_${hash}`;
+}
+function stateRoot() {
+  return process.env["NLM_STATE_ROOT"] || join(homedir(), ".nlm");
+}
+function tenantStatePath(tenantId, ...segments) {
+  const base = stateRoot();
+  if (tenantId === DEFAULT_TEAM_ID) return join(base, ...segments);
+  return join(base, TENANTS_DIRNAME, sanitizeTenantId(tenantId), ...segments);
+}
+
+// package.json
+var package_default = {
+  name: "nlm-memory",
+  version: "0.21.12",
+  description: "Local-first non-linear memory operating system for AI operators.",
+  type: "module",
+  license: "Apache-2.0",
+  engines: {
+    node: ">=22.0.0"
+  },
+  repository: {
+    type: "git",
+    url: "git+https://github.com/pbmagnet4/nlm-memory.git"
+  },
+  homepage: "https://github.com/pbmagnet4/nlm-memory#readme",
+  bugs: {
+    url: "https://github.com/pbmagnet4/nlm-memory/issues"
+  },
+  keywords: [
+    "ai",
+    "memory",
+    "mcp",
+    "claude-code",
+    "codex",
+    "hermes",
+    "local-first",
+    "recall",
+    "session-memory"
+  ],
+  files: [
+    "dist",
+    "migrations",
+    "fixtures",
+    "templates",
+    "plugin",
+    "plugin-hermes-agent",
+    "nlm",
+    "assets",
+    "LICENSE",
+    "README.md"
+  ],
+  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",
+    "verify:codex-release": "node scripts/verify-codex-release.mjs",
+    build: "npm run build:server && npm run build:ui && npm run build:codex-plugin",
+    prepare: "[ -d src ] && npm run build || true",
+    "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",
+    "test:pg": "vitest run .pg.test.ts --test-timeout=20000",
+    typecheck: "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json && tsc -p tsconfig.scripts.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:fact-recall": "tsx scripts/eval/fact-recall-eval.ts",
+    "eval:recall-impact-replay": "tsx scripts/eval/recall-impact-replay.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",
+    "eval:rederiv-sample": "tsx scripts/eval/re-derivation-sample.ts",
+    "eval:rederiv-label": "tsx scripts/eval/re-derivation-label.ts",
+    "eval:rederiv-calibrate": "tsx scripts/eval/re-derivation-calibrate.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": "^13.0.1",
+    commander: "^15.0.0",
+    hono: "^4.6.0",
+    pg: "^8.21.0",
+    pgvector: "^0.3.0",
+    "sqlite-vec": "^0.1.6",
+    yaml: "^2.9.0",
+    zod: "^4.4.3"
+  },
+  devDependencies: {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.10.0",
+    "@types/pg": "^8.20.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.2",
+    esbuild: "^0.28.0",
+    react: "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-router-dom": "^6.30.3",
+    "tsc-alias": "^1.8.17",
+    tsx: "^4.19.0",
+    typescript: "^6.0.3",
+    vite: "^8.0.16",
+    vitest: "^4.1.8"
+  }
+};
+
+// src/shared/version.ts
+var NLM_VERSION = package_default.version;
+
+// src/core/hook/hook-log.ts
+function logPath(tenantId) {
+  if (tenantId === DEFAULT_TEAM_ID) {
+    return process.env["NLM_HOOK_LOG"] ?? tenantStatePath(tenantId, "hook-log.jsonl");
+  }
+  return tenantStatePath(tenantId, "hook-log.jsonl");
 }
-function appendHookLog(entry) {
+function appendHookLog(tenantId, entry) {
   try {
-    const path = logPath();
+    const path = logPath(tenantId);
     mkdirSync(dirname(path), { recursive: true });
-    appendFileSync(path, `${JSON.stringify(entry)}
+    appendFileSync(path, `${JSON.stringify({ ...entry, v: NLM_VERSION })}
 `, "utf8");
   } catch {
   }
@@ -219,18 +359,20 @@ import {
   statSync,
   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 stateDir(tenantId) {
+  if (tenantId === DEFAULT_TEAM_ID) {
+    return process.env["NLM_HOOK_STATE_DIR"] ?? tenantStatePath(tenantId, "hook-state");
+  }
+  return tenantStatePath(tenantId, "hook-state");
 }
-function memoPath(conversationId) {
+function memoPath(tenantId, conversationId) {
   const safe = conversationId.replace(/[^A-Za-z0-9_-]/g, "_") || "unknown";
-  return join2(stateDir(), `${safe}.json`);
+  return join2(stateDir(tenantId), `${safe}.json`);
 }
-function loadSurfaced(conversationId) {
+function loadSurfaced(tenantId, conversationId) {
   try {
-    const path = memoPath(conversationId);
+    const path = memoPath(tenantId, conversationId);
     if (!existsSync2(path)) return /* @__PURE__ */ new Set();
     const parsed = JSON.parse(readFileSync(path, "utf8"));
     if (!Array.isArray(parsed)) return /* @__PURE__ */ new Set();
@@ -239,12 +381,12 @@ function loadSurfaced(conversationId) {
     return /* @__PURE__ */ new Set();
   }
 }
-function recordSurfaced(conversationId, ids) {
+function recordSurfaced(tenantId, conversationId, ids) {
   try {
-    const merged = loadSurfaced(conversationId);
+    const merged = loadSurfaced(tenantId, conversationId);
     for (const id of ids) merged.add(id);
-    mkdirSync2(stateDir(), { recursive: true });
-    writeFileSync(memoPath(conversationId), JSON.stringify([...merged]), "utf8");
+    mkdirSync2(stateDir(tenantId), { recursive: true });
+    writeFileSync(memoPath(tenantId, conversationId), JSON.stringify([...merged]), "utf8");
   } catch {
   }
 }
@@ -270,8 +412,8 @@ function truncateSummary(s, max = 200) {
   }
   return window + " ...";
 }
-function formatPointerBlock(hits, facts = [], exemplars = []) {
-  if (hits.length === 0 && facts.length === 0 && exemplars.length === 0) return "";
+function formatPointerBlock(hits, facts = [], exemplars = [], concepts = []) {
+  if (hits.length === 0 && facts.length === 0 && exemplars.length === 0 && concepts.length === 0) return "";
   const out = [];
   if (hits.length > 0) {
     out.push("## Possibly-relevant prior sessions (nlm-memory)");
@@ -300,7 +442,19 @@ function formatPointerBlock(hits, facts = [], exemplars = []) {
       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).";
+  if (concepts.length > 0) {
+    if (out.length > 0) out.push("");
+    out.push("## Learning state (nlm-memory)");
+    for (const c of concepts) {
+      const n = c.attemptCount === 1 ? "1 attempt" : `${c.attemptCount} attempts`;
+      out.push(`- [${c.status}] ${c.concept} (${n})`);
+    }
+    const nextSteps = [...new Set(concepts.map((c) => c.nextStep).filter((s) => !!s))].slice(0, 2);
+    for (const next of nextSteps) {
+      out.push(`Next: ${truncateSummary(next, 120)}`);
+    }
+  }
+  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), learner_summary (concept mastery + next step)." : "NLM tools: recall_sessions (search), get_session (full transcript), recall_facts (prior decisions), get_fact_history (how a decision evolved), learner_summary (concept mastery + next step).";
   out.push(tools);
   return out.join("\n");
 }
@@ -312,10 +466,10 @@ function medianScore(hits) {
   return sorted[Math.floor(sorted.length / 2)] ?? 0;
 }
 function selectHits(params) {
-  const { hits, surfaced, scoreThreshold, perFireCap, perConversationCap, relativeFloor = 0 } = params;
-  const relCut = relativeFloor > 0 ? relativeFloor * medianScore(hits) : 0;
+  const { hits, surfaced, scoreThreshold: scoreThreshold2, perFireCap, perConversationCap, relativeFloor: relativeFloor2 = 0 } = params;
+  const relCut = relativeFloor2 > 0 ? relativeFloor2 * medianScore(hits) : 0;
   const eligible = hits.filter(
-    (h) => h.matchScore >= scoreThreshold && h.matchScore >= relCut && !surfaced.has(h.id)
+    (h) => h.matchScore >= scoreThreshold2 && h.matchScore >= relCut && !surfaced.has(h.id)
   );
   const budget = Math.max(0, perConversationCap - surfaced.size);
   const limit = Math.min(perFireCap, budget);
@@ -324,7 +478,7 @@ function selectHits(params) {
 
 // src/llm/env-autoload.ts
 import { readFileSync as readFileSync2, existsSync as existsSync3 } from "node:fs";
-import { homedir as homedir3 } from "node:os";
+import { homedir as homedir2 } from "node:os";
 import { resolve } from "node:path";
 var DEFAULT_SEARCH_PATHS = [
   "~/.nlm/.env",
@@ -333,7 +487,7 @@ var DEFAULT_SEARCH_PATHS = [
   "../../.env"
 ];
 function expandHome(p) {
-  if (p.startsWith("~/")) return resolve(homedir3(), p.slice(2));
+  if (p.startsWith("~/")) return resolve(homedir2(), p.slice(2));
   return p;
 }
 function autoloadEnv(extraPaths = []) {
@@ -515,6 +669,18 @@ function extractRecallQuery(prompt) {
 }
 
 // src/hook/hook-helpers.ts
+import { appendFileSync as appendFileSync2, mkdirSync as mkdirSync3, realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+function isMainModule(metaUrl, argv1) {
+  if (!argv1) return false;
+  let resolved;
+  try {
+    resolved = realpathSync(argv1);
+  } catch {
+    return false;
+  }
+  return metaUrl === pathToFileURL(resolved).href;
+}
 function readStdin() {
   return new Promise((resolve2) => {
     let data = "";
@@ -537,29 +703,46 @@ function hookModeFromEnv() {
   return process.env["NLM_HOOK_MODE"] === "live" ? "live" : "shadow";
 }
 
+// src/shared/net.ts
+var DEFAULT_NLM_PORT = "3940";
+
 // src/hook/recall-over-http.ts
 var RECALL_LIMIT = 5;
-var RECALL_TIMEOUT_MS = 2e3;
-async function recallOverHttp(prompt, runtime, conversationId, mode = "keyword") {
+function parseRecallTimeout(raw) {
+  if (raw === void 0) return 4e3;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : 4e3;
+}
+function recallTimeoutMs() {
+  return parseRecallTimeout(process.env["NLM_HOOK_RECALL_TIMEOUT_MS"]);
+}
+var emptyResult = (outcome) => ({
+  hits: [],
+  facts: [],
+  exemplars: [],
+  concepts: [],
+  outcome
+});
+async function recallOverHttp(prompt, runtime, conversationId, mode = "keyword", source = "hook") {
   const query = extractRecallQuery(prompt);
-  if (query === null) return { hits: [], facts: [], exemplars: [] };
-  const portValue = process.env["NLM_PORT"] ?? "3940";
+  if (query === null) return emptyResult("skipped");
+  const portValue = process.env["NLM_PORT"] ?? DEFAULT_NLM_PORT;
   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)}` : "")
+    `http://127.0.0.1:${portValue}/api/recall?q=${encodeURIComponent(query)}&mode=${mode}&limit=${RECALL_LIMIT}&withFacts=true&withExemplars=true&withConcepts=true` + (conversationId ? `&conversation_id=${encodeURIComponent(conversationId)}` : "")
   );
   try {
-    const extra = { "x-recall-source": "hook" };
+    const extra = { "x-recall-source": source };
     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: [] };
+    const res = await fetchWithTimeout(url, { headers: hookAuthHeaders(extra) }, recallTimeoutMs());
+    if (!res.ok) return emptyResult("http-error");
     let body;
     try {
       body = await res.json();
     } catch {
-      return { hits: [], facts: [], exemplars: [] };
+      return emptyResult("http-error");
     }
     const hits = (body.results ?? []).map((r) => ({
       id: r.id,
@@ -580,9 +763,16 @@ async function recallOverHttp(prompt, runtime, conversationId, mode = "keyword")
       repo: e.repo,
       taskContext: e.taskContext
     }));
-    return { hits, facts, exemplars };
-  } catch {
-    return { hits: [], facts: [], exemplars: [] };
+    const concepts = (body.relatedConcepts ?? []).map((c) => ({
+      concept: c.concept,
+      status: c.status,
+      attemptCount: c.attemptCount,
+      nextStep: c.nextStep
+    }));
+    return { hits, facts, exemplars, concepts, outcome: "ok" };
+  } catch (err) {
+    const aborted = err instanceof Error && err.name === "AbortError";
+    return emptyResult(aborted ? "timeout" : "unreachable");
   }
 }
 
@@ -649,17 +839,19 @@ ${candidate}` }
 }
 
 // src/hook/prompt-recall-hook.ts
-var SCORE_THRESHOLD = parseScoreFloor(process.env["NLM_RECALL_SCORE_FLOOR"]);
-var RELATIVE_FLOOR = parseRelativeFloor(process.env["NLM_RECALL_REL_FLOOR"], 0.9);
+var scoreThreshold = () => parseScoreFloor(process.env["NLM_RECALL_SCORE_FLOOR"]);
+var relativeFloor = () => 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;
+function parseHookDeadline(raw, defaultMs = 4e3) {
+  if (raw === void 0) return defaultMs;
   const n = Number(raw);
-  return Number.isFinite(n) && n > 0 ? n : 4e3;
+  return Number.isFinite(n) && n > 0 ? n : defaultMs;
+}
+function hookDeadlineMs() {
+  return parseHookDeadline(process.env["NLM_HOOK_DEADLINE_MS"], 6e3);
 }
-var HOOK_DEADLINE_MS = parseHookDeadline(process.env["NLM_HOOK_DEADLINE_MS"]);
 async function withDeadline(p, ms, fallback) {
   if (ms <= 0) return fallback;
   let timer;
@@ -697,7 +889,7 @@ async function runHook(input, deps) {
   const gate = classifyPrompt(input.prompt);
   const preview = input.prompt.slice(0, PROMPT_PREVIEW_CHARS);
   if (gate === "generative" || gate === "skip") {
-    appendHookLog({
+    appendHookLog(DEFAULT_TEAM_ID, {
       ts: (/* @__PURE__ */ new Date()).toISOString(),
       conversationId: input.conversationId,
       promptPreview: preview,
@@ -709,22 +901,26 @@ async function runHook(input, deps) {
     });
     return "";
   }
-  const deadline = Date.now() + (deps.deadlineMs ?? HOOK_DEADLINE_MS);
-  let fetched = { hits: [], facts: [] };
+  const deadline = Date.now() + (deps.deadlineMs ?? hookDeadlineMs());
+  let fetched = { hits: [], facts: [], outcome: "timeout" };
   try {
     fetched = normalizeRecall(
-      await withDeadline(deps.recall(buildRecallQuery(input)), deadline - Date.now(), { hits: [], facts: [] })
+      await withDeadline(
+        deps.recall(buildRecallQuery(input)),
+        deadline - Date.now(),
+        { hits: [], facts: [], outcome: "timeout" }
+      )
     );
   } catch {
-    fetched = { hits: [], facts: [] };
+    fetched = { hits: [], facts: [], outcome: "unreachable" };
   }
   const hits = fetched.hits;
-  const surfaced = loadSurfaced(input.conversationId);
+  const surfaced = loadSurfaced(DEFAULT_TEAM_ID, input.conversationId);
   const selected = selectHits({
     hits,
     surfaced,
-    scoreThreshold: SCORE_THRESHOLD,
-    relativeFloor: RELATIVE_FLOOR,
+    scoreThreshold: scoreThreshold(),
+    relativeFloor: relativeFloor(),
     perFireCap: PER_FIRE_CAP,
     perConversationCap: PER_CONVERSATION_CAP
   });
@@ -750,9 +946,9 @@ ${h.summary ?? ""}`) }))),
       injected = selected.filter((h) => !drop.has(h.id));
     }
   }
-  const block = formatPointerBlock(injected, fetched.facts, fetched.exemplars);
+  const block = formatPointerBlock(injected, fetched.facts, fetched.exemplars, fetched.concepts ?? []);
   const estTokens = Math.ceil(block.length / 4);
-  appendHookLog({
+  appendHookLog(DEFAULT_TEAM_ID, {
     ts: (/* @__PURE__ */ new Date()).toISOString(),
     conversationId: input.conversationId,
     promptPreview: preview,
@@ -761,10 +957,11 @@ ${h.summary ?? ""}`) }))),
     wouldInject: injected.map((h) => h.id),
     estTokens,
     mode: deps.mode,
+    ...fetched.outcome ? { recallOutcome: fetched.outcome } : {},
     ...gateDecisions ? { gateDecisions } : {}
   });
   if (deps.mode === "live" && injected.length > 0) {
-    recordSurfaced(input.conversationId, injected.map((h) => h.id));
+    recordSurfaced(DEFAULT_TEAM_ID, input.conversationId, injected.map((h) => h.id));
     return block;
   }
   return "";
@@ -796,11 +993,12 @@ async function main() {
   } catch {
   }
 }
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isMainModule(import.meta.url, process.argv[1])) {
   void main();
 }
 export {
   buildRecallQuery,
+  hookDeadlineMs,
   hookRuntimeFromEnv,
   parseHookDeadline,
   promptRecallEnabled,