nlm-memory 0.20.1 → 0.21.12

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

@@ -1,20 +1,163 @@
 #!/usr/bin/env node
 
 // src/hook/session-start-hook.ts
-import { pathToFileURL } from "node:url";
+import { execFileSync } from "node:child_process";
 
 // 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 {
   }
@@ -30,18 +173,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 (!existsSync(path)) return /* @__PURE__ */ new Set();
     const parsed = JSON.parse(readFileSync(path, "utf8"));
     if (!Array.isArray(parsed)) return /* @__PURE__ */ new Set();
@@ -50,12 +195,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 {
   }
 }
@@ -81,8 +226,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)");
@@ -111,7 +256,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");
 }
@@ -123,10 +280,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);
@@ -135,7 +292,7 @@ function selectHits(params) {
 
 // src/llm/env-autoload.ts
 import { readFileSync as readFileSync2, existsSync as existsSync2 } 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",
@@ -144,7 +301,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 = []) {
@@ -340,6 +497,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 = "";
@@ -362,29 +531,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,
@@ -405,37 +591,47 @@ 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");
   }
 }
 
 // src/hook/session-start-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 RECALL_TIMEOUT_MS2 = 2e3;
+var RECALL_TIMEOUT_MS = 2e3;
 async function runHook(input, deps) {
   let hits = [];
+  let recallOutcome = "unreachable";
   try {
-    hits = await deps.recall(input.query, input.conversationId);
+    const fetched = await deps.recall(input.query, input.conversationId);
+    hits = fetched.hits;
+    recallOutcome = fetched.outcome;
   } catch {
     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
   });
   const block = formatPointerBlock(selected);
   const estTokens = Math.ceil(block.length / 4);
-  appendHookLog({
+  appendHookLog(DEFAULT_TEAM_ID, {
     ts: (/* @__PURE__ */ new Date()).toISOString(),
     conversationId: input.conversationId,
     promptPreview: input.query,
@@ -443,10 +639,11 @@ async function runHook(input, deps) {
     hits: hits.map((h) => ({ id: h.id, score: h.matchScore })),
     wouldInject: selected.map((h) => h.id),
     estTokens,
-    mode: deps.mode
+    mode: deps.mode,
+    recallOutcome
   });
   if (deps.mode === "live" && selected.length > 0) {
-    recordSurfaced(input.conversationId, selected.map((h) => h.id));
+    recordSurfaced(DEFAULT_TEAM_ID, input.conversationId, selected.map((h) => h.id));
     return block;
   }
   return "";
@@ -456,12 +653,12 @@ function composeSessionStartOutput(failureModeBlock, recallBlock) {
 }
 async function fetchFailureModeBlock(repo) {
   if (!repo) return "";
-  const portValue = process.env["NLM_PORT"] ?? "3940";
+  const portValue = process.env["NLM_PORT"] ?? DEFAULT_NLM_PORT;
   const url = `http://127.0.0.1:${portValue}/api/signals/failure-modes?repo=${encodeURIComponent(repo)}`;
   try {
     const res = await fetchWithTimeout(url, {
       headers: hookAuthHeaders({ "x-recall-source": "session-start-hook" })
-    }, RECALL_TIMEOUT_MS2);
+    }, RECALL_TIMEOUT_MS);
     if (!res.ok) return "";
     const body = await res.json();
     return typeof body.block === "string" ? body.block : "";
@@ -469,9 +666,29 @@ async function fetchFailureModeBlock(repo) {
     return "";
   }
 }
-function buildQuery(workingDirectory, projectName) {
+var GIT_TIMEOUT_MS = 300;
+var RECENT_COMMITS = 3;
+function git(cwd, args) {
+  try {
+    return execFileSync("git", ["-C", cwd, ...args], {
+      encoding: "utf8",
+      timeout: GIT_TIMEOUT_MS,
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+function readGitContext(workingDirectory) {
+  if (!workingDirectory) return "";
+  const branch = git(workingDirectory, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const subjects = git(workingDirectory, ["log", `-${RECENT_COMMITS}`, "--format=%s"]);
+  const branchWords = branch === "HEAD" ? "" : branch.replace(/[/_-]+/g, " ");
+  return [branchWords, subjects.replace(/\n/g, " ")].filter(Boolean).join(" ");
+}
+function buildQuery(workingDirectory, projectName, gitContext) {
   const dirTail = workingDirectory.split("/").filter(Boolean).at(-1) ?? "";
-  const parts = [dirTail, projectName].filter(Boolean);
+  const parts = [dirTail, projectName, gitContext].filter(Boolean);
   return parts.join(" ").trim() || "session start";
 }
 async function main() {
@@ -482,14 +699,23 @@ async function main() {
     const conversationId = typeof payload.session_id === "string" ? payload.session_id : "unknown";
     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 query = buildQuery(workingDirectory, projectName, readGitContext(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
+          recall: async (q, cid) => {
+            const r = await recallOverHttp(
+              q,
+              "claude-code",
+              cid === "unknown" ? void 0 : cid,
+              "hybrid",
+              "session-start-hook"
+            );
+            return { hits: r.hits, outcome: r.outcome };
+          }
         }
       ),
       mode === "live" ? fetchFailureModeBlock(workingDirectory) : Promise.resolve("")
@@ -499,10 +725,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 {
+  buildQuery,
   composeSessionStartOutput,
+  readGitContext,
   runHook
 };