nlm-memory 0.4.0

package/plugin/scripts/stop-hook.mjs

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+
+// src/hook/stop-hook.ts
+import { pathToFileURL } from "node:url";
+import { appendFileSync, mkdirSync as mkdirSync3 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { dirname, join as join3 } from "node:path";
+
+// src/core/hook/citation-detect.ts
+var MIN_ID_LEN = 6;
+function detectCitations(input) {
+  const surfaced = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const id of input.surfacedIds) {
+    if (id.length < MIN_ID_LEN) continue;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    surfaced.push(id);
+  }
+  const cited = [];
+  const claimedByToolUse = /* @__PURE__ */ new Set();
+  for (const tu of input.toolUses) {
+    if (!isNlmTool(tu.name)) continue;
+    if (isCiteSessionTool(tu.name)) {
+      continue;
+    }
+    const serialized = safeStringify(tu.input);
+    if (!serialized) continue;
+    for (const id of surfaced) {
+      if (claimedByToolUse.has(id)) continue;
+      if (serialized.includes(id)) {
+        cited.push({ id, kind: "tool_use" });
+        claimedByToolUse.add(id);
+      }
+    }
+  }
+  if (input.responseText) {
+    for (const id of surfaced) {
+      if (claimedByToolUse.has(id)) continue;
+      if (input.responseText.includes(id)) {
+        cited.push({ id, kind: "prose" });
+      }
+    }
+  }
+  return cited;
+}
+function isNlmTool(name) {
+  return /^mcp__[^_]*nlm[^_]*__/.test(name);
+}
+function isCiteSessionTool(name) {
+  return name.endsWith("__cite_session");
+}
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "";
+  }
+}
+
+// src/core/hook/memo.ts
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function stateDir() {
+  return process.env["NLM_HOOK_STATE_DIR"] ?? join(homedir(), ".nlm", "hook-state");
+}
+function memoPath(conversationId) {
+  const safe = conversationId.replace(/[^A-Za-z0-9_-]/g, "_") || "unknown";
+  return join(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();
+  }
+}
+
+// src/core/hook/cite-memo.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join2 } from "node:path";
+function stateDir2() {
+  return process.env["NLM_HOOK_STATE_DIR"] ?? join2(homedir2(), ".nlm", "hook-state");
+}
+function memoPath2(conversationId) {
+  const safe = conversationId.replace(/[^A-Za-z0-9_-]/g, "_") || "unknown";
+  return join2(stateDir2(), `${safe}.cited.json`);
+}
+function loadCited(conversationId) {
+  try {
+    const path = memoPath2(conversationId);
+    if (!existsSync2(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"));
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
+function recordCited(conversationId, ids) {
+  if (ids.length === 0) return;
+  try {
+    const merged = loadCited(conversationId);
+    for (const id of ids) merged.add(id);
+    mkdirSync2(stateDir2(), { recursive: true });
+    writeFileSync2(memoPath2(conversationId), JSON.stringify([...merged]), "utf8");
+  } catch {
+  }
+}
+
+// src/core/hook/transcript.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
+function parseTurn(parsed) {
+  if (parsed.type !== "assistant" || !parsed.message) return null;
+  const content = parsed.message.content;
+  if (typeof content === "string") {
+    return content ? { text: content, toolUses: [] } : null;
+  }
+  if (!Array.isArray(content)) return null;
+  const textParts = [];
+  const toolUses = [];
+  for (const block of content) {
+    if (block.type === "text" && typeof block.text === "string") {
+      textParts.push(block.text);
+    } else if (block.type === "tool_use" && typeof block.name === "string") {
+      toolUses.push({ name: block.name, input: block.input });
+    }
+  }
+  if (textParts.length === 0 && toolUses.length === 0) return null;
+  return { text: textParts.join("\n"), toolUses };
+}
+function readLines(transcriptPath) {
+  if (!transcriptPath || !existsSync3(transcriptPath)) return null;
+  try {
+    return readFileSync3(transcriptPath, "utf8").split("\n");
+  } catch {
+    return null;
+  }
+}
+function readAllAssistantTurns(transcriptPath) {
+  const lines = readLines(transcriptPath);
+  if (!lines) return [];
+  const turns = [];
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const turn = parseTurn(parsed);
+    if (turn) turns.push(turn);
+  }
+  return turns;
+}
+
+// src/hook/stop-hook.ts
+var RESPONSE_PREVIEW_CHARS = 200;
+var POST_TIMEOUT_MS = 1500;
+async function runStopHook(input, deps) {
+  if (input.stopHookActive) {
+    return {
+      conversationId: input.conversationId,
+      surfacedCount: 0,
+      citations: [],
+      responsePreview: "",
+      skipped: true
+    };
+  }
+  const surfaced = loadSurfaced(input.conversationId);
+  if (surfaced.size === 0) {
+    return {
+      conversationId: input.conversationId,
+      surfacedCount: 0,
+      citations: [],
+      responsePreview: "",
+      skipped: false
+    };
+  }
+  const turns = readAllAssistantTurns(input.transcriptPath);
+  if (turns.length === 0) {
+    return {
+      conversationId: input.conversationId,
+      surfacedCount: surfaced.size,
+      citations: [],
+      responsePreview: "",
+      skipped: false
+    };
+  }
+  const allToolUses = [];
+  const textParts = [];
+  for (const turn of turns) {
+    if (turn.text) textParts.push(turn.text);
+    for (const tu of turn.toolUses) allToolUses.push(tu);
+  }
+  const unionText = textParts.join("\n");
+  const detected = detectCitations({
+    responseText: unionText,
+    toolUses: allToolUses,
+    surfacedIds: surfaced
+  });
+  const alreadyCited = loadCited(input.conversationId);
+  const fresh = detected.filter((c) => !alreadyCited.has(c.id));
+  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 {
+    }
+  }
+  if (fresh.length > 0) {
+    recordCited(input.conversationId, fresh.map((c) => c.id));
+  }
+  return {
+    conversationId: input.conversationId,
+    surfacedCount: surfaced.size,
+    citations: fresh,
+    responsePreview: preview,
+    skipped: false
+  };
+}
+function logPath() {
+  return process.env["NLM_HOOK_LOG"] ?? join3(homedir3(), ".nlm", "hook-log.jsonl");
+}
+function logStopResult(result) {
+  try {
+    const path = logPath();
+    mkdirSync3(dirname(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((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 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: { "content-type": "application/json" },
+      body: JSON.stringify({
+        conversation_id: conversationId,
+        cited_id: citedId,
+        kind,
+        response_preview: responsePreview
+      }),
+      signal: controller.signal
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function main() {
+  try {
+    const raw = await readStdin();
+    const payload = JSON.parse(raw);
+    const conversationId = typeof payload.session_id === "string" ? payload.session_id : "unknown";
+    const transcriptPath = typeof payload.transcript_path === "string" ? payload.transcript_path : "";
+    const stopHookActive = payload.stop_hook_active === true;
+    const result = await runStopHook(
+      { conversationId, transcriptPath, stopHookActive },
+      { postCitation: postCitationOverHttp }
+    );
+    logStopResult(result);
+  } catch {
+  }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  void main();
+}
+export {
+  runStopHook
+};

package/plugin-hermes-agent/README.md

@@ -0,0 +1,49 @@
+# nlm-memory Hermes Agent plugin
+
+This directory is the [NousResearch Hermes Agent](https://github.com/NousResearch/hermes-agent) plugin distribution surface for nlm-memory.
+
+## Install
+
+Prerequisite: `npm install -g nlm-memory` (puts `nlm` on PATH; the MCP server spawns `nlm mcp`).
+
+```bash
+# Recommended — uses nlm connect to copy the plugin and enable it
+nlm connect hermes-agent
+
+# Or manually
+cp -r plugin-hermes-agent ~/.hermes/plugins/nlm-memory
+hermes plugins enable nlm-memory
+nlm connect hermes          # also writes the MCP server entry to ~/.hermes/config.yaml
+```
+
+## What this ships
+
+- **`plugin.yaml`** — Hermes plugin manifest (name: `nlm-memory`, kind: `memory`)
+- **`__init__.py`** — Python shim that registers 6 lifecycle hooks; all delegate to the local nlm daemon at `http://localhost:3940`
+
+## How it works
+
+| Hermes hook | Action |
+|---|---|
+| `pre_llm_call` | Keyword-recalls up to 3 relevant prior sessions; injects them as context above the user message |
+| `post_llm_call` | Scans the assistant response for cited session IDs and logs prose citation events |
+| `on_session_start` | No-op (memo is created lazily on first recall hit) |
+| `on_session_end` | Clears the per-session surfaced-ID memo |
+| `on_session_finalize` | Clears the per-session surfaced-ID memo |
+| `on_session_reset` | Clears the per-session surfaced-ID memo |
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `NLM_DAEMON_PORT` | `3940` | Port the nlm daemon listens on |
+
+## Daemon required
+
+The plugin delegates entirely to the nlm daemon. Start it with `nlm start` or `nlm install` (macOS LaunchAgent). If the daemon is unreachable, every hook silently returns `None` — the agent loop is never blocked.
+
+## Uninstall
+
+```bash
+nlm disconnect hermes-agent
+```

package/plugin-hermes-agent/__init__.py

@@ -0,0 +1,75 @@
+"""
+nlm-memory Hermes Agent plugin.
+
+Wires 6 Hermes lifecycle hooks to the local nlm-memory daemon
+(http://localhost:3940 by default). All calls are fire-and-forget
+except pre_llm_call, which returns a context string for injection.
+
+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 json
+import os
+import urllib.error
+import urllib.request
+from typing import Any
+
+
+def _base_url() -> str:
+    port = os.environ.get("NLM_DAEMON_PORT", "3940")
+    return f"http://localhost:{port}"
+
+
+def _post(path: str, payload: dict[str, Any]) -> dict[str, Any]:
+    url = f"{_base_url()}/api/{path}"
+    data = json.dumps(payload).encode()
+    req = urllib.request.Request(
+        url,
+        data=data,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            return json.loads(resp.read())
+    except (urllib.error.URLError, OSError, json.JSONDecodeError):
+        return {}
+
+
+def register(ctx: Any) -> None:
+    def pre_llm_call(
+        session_id: str,
+        user_message: str,
+        is_first_turn: bool = False,
+        **kwargs: Any,
+    ) -> str | None:
+        result = _post(
+            "hook/hermes-agent/pre-turn",
+            {"session_id": session_id, "user_message": user_message, "is_first_turn": is_first_turn},
+        )
+        context = result.get("context")
+        return context if isinstance(context, str) and context else None
+
+    def post_llm_call(
+        session_id: str,
+        assistant_response: str,
+        **kwargs: Any,
+    ) -> None:
+        _post(
+            "hook/hermes-agent/post-turn",
+            {"session_id": session_id, "assistant_response": assistant_response},
+        )
+
+    def _session_event(event: str, session_id: str | None, **kwargs: Any) -> None:
+        _post(
+            "hook/hermes-agent/session-lifecycle",
+            {"event": event, "session_id": session_id},
+        )
+
+    ctx.register_hook("pre_llm_call", pre_llm_call)
+    ctx.register_hook("post_llm_call", post_llm_call)
+    ctx.register_hook("on_session_start", lambda session_id, **kw: _session_event("start", session_id, **kw))
+    ctx.register_hook("on_session_end", lambda session_id, **kw: _session_event("end", session_id, **kw))
+    ctx.register_hook("on_session_finalize", lambda session_id=None, **kw: _session_event("finalize", session_id, **kw))
+    ctx.register_hook("on_session_reset", lambda session_id, **kw: _session_event("reset", session_id, **kw))

package/plugin-hermes-agent/plugin.yaml

@@ -0,0 +1,15 @@
+name: nlm-memory
+version: 0.1.0
+description: Non-linear memory for Hermes — surfaces relevant prior sessions at each turn via keyword recall
+kind: memory
+author: pbmagnet4
+provides_hooks:
+  - pre_llm_call
+  - post_llm_call
+  - on_session_start
+  - on_session_end
+  - on_session_finalize
+  - on_session_reset
+requires_env:
+  - name: NLM_DAEMON_PORT
+    description: "Port the nlm-memory daemon listens on (default: 3940)"

package/scripts/build-codex-plugin.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * Bundles each hook entry under src/hook/ as a single-file .mjs into
+ * plugin/scripts/, ready for Codex to invoke via ${CLAUDE_PLUGIN_ROOT}.
+ *
+ * Why single-file bundles: Codex plugins are content-addressed by file hash
+ * for the trust system. Shipping a tree of imports would force the user to
+ * re-trust every release across dozens of files. One file per hook keeps
+ * the trust footprint minimal.
+ *
+ * Why esbuild not tsc: tsc emits a tree of files with relative imports; the
+ * plugin would have to ship `dist/` plus its dependency tree. esbuild flattens
+ * to one .mjs per entry with all internal deps inlined. node builtins are
+ * left as-is (node:*) and zero runtime deps are bundled because the hook
+ * scripts only talk to the daemon over HTTP — no native bindings required.
+ */
+
+import { build } from "esbuild";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { mkdirSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, "..");
+const OUT_DIR = resolve(REPO_ROOT, "plugin/scripts");
+
+const ENTRIES = [
+  "src/hook/prompt-recall-hook.ts",
+  "src/hook/stop-hook.ts",
+];
+
+mkdirSync(OUT_DIR, { recursive: true });
+
+const results = await Promise.all(
+  ENTRIES.map(async (entry) => {
+    const entryPath = resolve(REPO_ROOT, entry);
+    const outName = entry.split("/").pop().replace(/\.ts$/, ".mjs");
+    const outFile = resolve(OUT_DIR, outName);
+    const result = await build({
+      entryPoints: [entryPath],
+      outfile: outFile,
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      target: "node20",
+      minify: false,
+      sourcemap: false,
+      legalComments: "none",
+      logLevel: "warning",
+      banner: { js: "#!/usr/bin/env node" },
+      tsconfig: resolve(REPO_ROOT, "tsconfig.json"),
+    });
+    return { entry, outFile, warnings: result.warnings.length };
+  }),
+);
+
+for (const r of results) {
+  process.stdout.write(`bundled ${r.entry} -> ${r.outFile.replace(REPO_ROOT + "/", "")}`);
+  if (r.warnings > 0) process.stdout.write(` (${r.warnings} warnings)`);
+  process.stdout.write("\n");
+}

package/scripts/deepseek-probe.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// Direct DeepSeek probe — calls the API with the same prompt + a known-failing
+// session body and dumps everything: raw choice content, finish_reason, usage.
+
+import { readFileSync } from "node:fs";
+import Database from "better-sqlite3";
+
+const envContent = readFileSync(`${process.env.HOME}/.nlm/.env`, "utf8");
+const apiKey = envContent.split("\n").find((l) => l.startsWith("DEEPSEEK_API_KEY="))?.split("=")[1]?.trim();
+if (!apiKey) {
+  console.error("no DEEPSEEK_API_KEY in ~/.nlm/.env");
+  process.exit(1);
+}
+
+const db = new Database(`${process.env.HOME}/.nlm/canonical.sqlite`, { readonly: true });
+const targets = process.argv.slice(2);
+if (targets.length === 0) {
+  console.error("usage: deepseek-probe.mjs <session-id> [more ids...]");
+  process.exit(1);
+}
+
+// Pull the actual classifier prompt from the build
+const promptModule = await import("/Users/echalupa/Documents/Coding Projects/nlm-memory-ts/src/core/classifier/prompt.ts");
+
+for (const sid of targets) {
+  const row = db.prepare("SELECT body FROM sessions WHERE id = ?").get(sid);
+  if (!row?.body) {
+    console.log(`\n=== ${sid}: no body ===`);
+    continue;
+  }
+  const userPrompt = promptModule.buildUserPrompt(row.body, "");
+  console.log(`\n=== ${sid} (body ${row.body.length} chars, prompt ${userPrompt.length} chars) ===`);
+
+  const res = await fetch("https://api.deepseek.com/v1/chat/completions", {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+    body: JSON.stringify({
+      model: "deepseek-v4-flash",
+      messages: [
+        { role: "system", content: promptModule.CLASSIFIER_SYSTEM_PROMPT },
+        { role: "user", content: userPrompt },
+      ],
+      response_format: { type: "json_object" },
+      temperature: 0.1,
+      max_tokens: 8192,
+      stream: false,
+    }),
+  });
+  if (!res.ok) {
+    console.log(`HTTP ${res.status}: ${(await res.text()).slice(0, 500)}`);
+    continue;
+  }
+  const data = await res.json();
+  const choice = data.choices?.[0];
+  console.log(`finish_reason: ${choice?.finish_reason}`);
+  console.log(`usage: ${JSON.stringify(data.usage)}`);
+  const content = choice?.message?.content ?? "";
+  console.log(`content (${content.length} chars):`);
+  console.log(content);
+  console.log("--- end content ---");
+  try {
+    JSON.parse(content.replace(/^```(?:json)?\s*|\s*```$/gm, "").trim());
+    console.log("JSON.parse: OK");
+  } catch (e) {
+    console.log(`JSON.parse: FAILED — ${e.message}`);
+  }
+}