nlm-memory 0.4.0

package/src/hook/prompt-recall-hook.ts

@@ -0,0 +1,174 @@
+/**
+ * Claude Code UserPromptSubmit hook entrypoint for NLM recall.
+ *
+ * runHook is the testable orchestration; main() is the thin process wrapper
+ * (stdin / stdout / fetch / env). Every path is fail-open: any error yields
+ * no output and a clean exit, so the hook can never block or fail a prompt.
+ *
+ * Mode is read from NLM_HOOK_MODE (default "shadow"). In shadow mode the
+ * hook logs what it would inject and emits nothing; in live mode it emits a
+ * pointer block and records the per-conversation memo.
+ */
+
+import { pathToFileURL } from "node:url";
+import { classifyPrompt } from "@core/hook/gate.js";
+import { appendHookLog } from "@core/hook/hook-log.js";
+import { loadSurfaced, recordSurfaced } from "@core/hook/memo.js";
+import { formatPointerBlock } from "@core/hook/pointer-block.js";
+import { selectHits, type RecallHitInput } from "@core/hook/select.js";
+
+// Keyword recall returns raw BM25 scores (unbounded, not the 0..1 hybrid
+// scale). FTS5 MATCH already gates relevance — only lexically-matching
+// sessions come back — so the floor starts at 0 and a real cutoff is
+// calibrated from the shadow log's score distribution.
+const SCORE_THRESHOLD = 0;
+const PER_FIRE_CAP = 3;
+const PER_CONVERSATION_CAP = 10;
+const RECALL_LIMIT = 5; // fetch more than PER_FIRE_CAP to absorb score-filter + dedup
+const RECALL_TIMEOUT_MS = 2000; // keyword recall is ~400ms warm, ~1.4s cold
+const PROMPT_PREVIEW_CHARS = 200;
+
+export type HookMode = "shadow" | "live";
+
+export interface HookInput {
+  readonly prompt: string;
+  readonly conversationId: string;
+}
+
+export interface RunHookDeps {
+  readonly mode: HookMode;
+  readonly recall: (prompt: string) => Promise<ReadonlyArray<RecallHitInput>>;
+}
+
+/** Orchestration. Returns the text to emit on stdout ("" for nothing). */
+export async function runHook(input: HookInput, deps: RunHookDeps): Promise<string> {
+  const gate = classifyPrompt(input.prompt);
+  const preview = input.prompt.slice(0, PROMPT_PREVIEW_CHARS);
+
+  if (gate === "generative") {
+    appendHookLog({
+      ts: new Date().toISOString(),
+      conversationId: input.conversationId,
+      promptPreview: preview,
+      gate,
+      hits: [],
+      wouldInject: [],
+      estTokens: 0,
+      mode: deps.mode,
+    });
+    return "";
+  }
+
+  let hits: ReadonlyArray<RecallHitInput> = [];
+  try {
+    hits = await deps.recall(input.prompt);
+  } catch {
+    hits = [];
+  }
+
+  const surfaced = loadSurfaced(input.conversationId);
+  const selected = selectHits({
+    hits,
+    surfaced,
+    scoreThreshold: SCORE_THRESHOLD,
+    perFireCap: PER_FIRE_CAP,
+    perConversationCap: PER_CONVERSATION_CAP,
+  });
+  const block = formatPointerBlock(selected);
+  const estTokens = Math.ceil(block.length / 4);
+
+  appendHookLog({
+    ts: new Date().toISOString(),
+    conversationId: input.conversationId,
+    promptPreview: preview,
+    gate,
+    hits: hits.map((h) => ({ id: h.id, score: h.matchScore })),
+    wouldInject: selected.map((h) => h.id),
+    estTokens,
+    mode: deps.mode,
+  });
+
+  if (deps.mode === "live" && selected.length > 0) {
+    recordSurfaced(input.conversationId, selected.map((h) => h.id));
+    return block;
+  }
+  return "";
+}
+
+function readStdin(): Promise<string> {
+  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 recallOverHttp(prompt: string): Promise<ReadonlyArray<RecallHitInput>> {
+  const portValue = process.env["NLM_PORT"] ?? "3940";
+  // keyword (FTS5) not hybrid: hybrid's Ollama embedding round-trip takes
+  // ~5s, far too slow for a hook that blocks prompt submission.
+  const url =
+    `http://localhost:${portValue}/api/recall` +
+    `?q=${encodeURIComponent(prompt)}&mode=keyword&limit=${RECALL_LIMIT}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), RECALL_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      headers: { "x-recall-source": "hook" },
+      signal: controller.signal,
+    });
+    if (!res.ok) return [];
+    type RecallBody = {
+      results?: ReadonlyArray<{
+        id: string;
+        label: string;
+        startedAt: string;
+        matchScore: number;
+      }>;
+    };
+    let body: RecallBody;
+    try {
+      body = (await res.json()) as RecallBody;
+    } catch {
+      return [];
+    }
+    return (body.results ?? []).map((r) => ({
+      id: r.id,
+      label: r.label,
+      startedAt: r.startedAt,
+      matchScore: r.matchScore,
+    }));
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function main(): Promise<void> {
+  try {
+    const raw = await readStdin();
+    const payload = JSON.parse(raw) as {
+      prompt?: unknown;
+      session_id?: unknown;
+    };
+    const prompt = typeof payload.prompt === "string" ? payload.prompt : "";
+    const conversationId =
+      typeof payload.session_id === "string" ? payload.session_id : "unknown";
+    if (!prompt) return;
+
+    const mode: HookMode = process.env["NLM_HOOK_MODE"] === "live" ? "live" : "shadow";
+    const out = await runHook(
+      { prompt, conversationId },
+      { mode, recall: recallOverHttp },
+    );
+    if (out) process.stdout.write(out);
+  } catch {
+    // Fail open — never block or fail a prompt.
+  }
+}
+
+// Run main() only when invoked directly as a script, not when imported by tests.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  void main();
+}

package/src/hook/session-end-hook.ts

@@ -0,0 +1,81 @@
+/**
+ * Claude Code SessionEnd hook entrypoint for NLM.
+ *
+ * Fires when a Claude Code session closes. Deletes the per-conversation
+ * memo file written during the session so memo files don't accumulate
+ * indefinitely under ~/.nlm/hook-state/.
+ *
+ * Logs one JSON line per invocation to ~/.nlm/hook-log.jsonl with
+ * `kind: "session-end"` so the daily-digest liveness check can correlate
+ * Claude Code session closes against hook fires the same way it does for
+ * UserPromptSubmit. Fail-open by design: any error yields a clean exit
+ * with no output, so the hook can never block Claude Code shutdown.
+ */
+
+import { pathToFileURL } from "node:url";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { clearSurfaced } from "@core/hook/memo.js";
+import { clearCited } from "@core/hook/cite-memo.js";
+
+export interface SessionEndResult {
+  readonly conversationId: string;
+  readonly cleared: boolean;
+}
+
+export function runSessionEnd(conversationId: string): SessionEndResult {
+  const surfacedCleared = clearSurfaced(conversationId);
+  const citedCleared = clearCited(conversationId);
+  return { conversationId, cleared: surfacedCleared || citedCleared };
+}
+
+function readStdin(): Promise<string> {
+  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));
+  });
+}
+
+function logPath(): string {
+  return process.env["NLM_HOOK_LOG"] ?? join(homedir(), ".nlm", "hook-log.jsonl");
+}
+
+function logSessionEnd(result: SessionEndResult): void {
+  try {
+    const path = logPath();
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(
+      path,
+      `${JSON.stringify({
+        ts: new Date().toISOString(),
+        kind: "session-end",
+        conversationId: result.conversationId,
+        cleared: result.cleared,
+        mode: process.env["NLM_HOOK_MODE"] === "live" ? "live" : "shadow",
+      })}\n`,
+      "utf8",
+    );
+  } catch {
+    // Telemetry failure must never break the hook.
+  }
+}
+
+async function main(): Promise<void> {
+  try {
+    const raw = await readStdin();
+    const payload = JSON.parse(raw) as { session_id?: unknown };
+    const conversationId =
+      typeof payload.session_id === "string" ? payload.session_id : "unknown";
+    logSessionEnd(runSessionEnd(conversationId));
+  } catch {
+    // Fail open — never block Claude Code shutdown.
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  void main();
+}

package/src/hook/session-start-hook.ts

@@ -0,0 +1,165 @@
+/**
+ * Claude Code SessionStart hook entrypoint for NLM recall.
+ *
+ * Fires before any prompt in a new session (including cron-fired and background
+ * agents that never trigger UserPromptSubmit). Surfaces relevant prior context
+ * proactively so cold-start agents aren't recall-blind.
+ *
+ * Query is derived from working_directory + project_name since no user prompt
+ * exists yet — intentionally weaker than prompt-recall, best-effort only.
+ *
+ * Mirrors prompt-recall-hook.ts shape exactly: same pointer-block format, same
+ * memo writes, same NLM_HOOK_MODE semantics.
+ */
+
+import { pathToFileURL } from "node:url";
+import { appendHookLog } from "@core/hook/hook-log.js";
+import { loadSurfaced, recordSurfaced } from "@core/hook/memo.js";
+import { formatPointerBlock } from "@core/hook/pointer-block.js";
+import { selectHits, type RecallHitInput } from "@core/hook/select.js";
+
+const SCORE_THRESHOLD = 0;
+const PER_FIRE_CAP = 3;
+const PER_CONVERSATION_CAP = 10;
+const RECALL_LIMIT = 5;
+const RECALL_TIMEOUT_MS = 2000;
+
+export type HookMode = "shadow" | "live";
+
+export interface SessionStartInput {
+  readonly conversationId: string;
+  readonly query: string;
+}
+
+export interface RunSessionStartDeps {
+  readonly mode: HookMode;
+  readonly recall: (query: string) => Promise<ReadonlyArray<RecallHitInput>>;
+}
+
+/** Orchestration. Returns the text to emit on stdout ("" for nothing). */
+export async function runHook(
+  input: SessionStartInput,
+  deps: RunSessionStartDeps,
+): Promise<string> {
+  let hits: ReadonlyArray<RecallHitInput> = [];
+  try {
+    hits = await deps.recall(input.query);
+  } catch {
+    hits = [];
+  }
+
+  const surfaced = loadSurfaced(input.conversationId);
+  const selected = selectHits({
+    hits,
+    surfaced,
+    scoreThreshold: SCORE_THRESHOLD,
+    perFireCap: PER_FIRE_CAP,
+    perConversationCap: PER_CONVERSATION_CAP,
+  });
+  const block = formatPointerBlock(selected);
+  const estTokens = Math.ceil(block.length / 4);
+
+  appendHookLog({
+    ts: new Date().toISOString(),
+    conversationId: input.conversationId,
+    promptPreview: input.query,
+    gate: "evaluate",
+    hits: hits.map((h) => ({ id: h.id, score: h.matchScore })),
+    wouldInject: selected.map((h) => h.id),
+    estTokens,
+    mode: deps.mode,
+  });
+
+  if (deps.mode === "live" && selected.length > 0) {
+    recordSurfaced(input.conversationId, selected.map((h) => h.id));
+    return block;
+  }
+  return "";
+}
+
+/** Derive a best-effort query from SessionStart payload fields. */
+function buildQuery(workingDirectory: string, projectName: string): string {
+  const dirTail = workingDirectory.split("/").filter(Boolean).at(-1) ?? "";
+  const parts = [dirTail, projectName].filter(Boolean);
+  return parts.join(" ").trim() || "session start";
+}
+
+function readStdin(): Promise<string> {
+  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 recallOverHttp(query: string): Promise<ReadonlyArray<RecallHitInput>> {
+  const portValue = process.env["NLM_PORT"] ?? "3940";
+  const url =
+    `http://localhost:${portValue}/api/recall` +
+    `?q=${encodeURIComponent(query)}&mode=hybrid&limit=${RECALL_LIMIT}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), RECALL_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      headers: { "x-recall-source": "session-start-hook" },
+      signal: controller.signal,
+    });
+    if (!res.ok) return [];
+    type RecallBody = {
+      results?: ReadonlyArray<{
+        id: string;
+        label: string;
+        startedAt: string;
+        matchScore: number;
+      }>;
+    };
+    let body: RecallBody;
+    try {
+      body = (await res.json()) as RecallBody;
+    } catch {
+      return [];
+    }
+    return (body.results ?? []).map((r) => ({
+      id: r.id,
+      label: r.label,
+      startedAt: r.startedAt,
+      matchScore: r.matchScore,
+    }));
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function main(): Promise<void> {
+  try {
+    const raw = await readStdin();
+    const payload = JSON.parse(raw) as {
+      session_id?: unknown;
+      cwd?: unknown;
+      working_directory?: unknown;
+      project_name?: unknown;
+    };
+    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 mode: HookMode = process.env["NLM_HOOK_MODE"] === "live" ? "live" : "shadow";
+    const out = await runHook({ conversationId, query }, { mode, recall: recallOverHttp });
+    if (out) process.stdout.write(out);
+  } catch {
+    // Fail open — never block or fail a session start.
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  void main();
+}

package/src/hook/stop-hook.ts

@@ -0,0 +1,236 @@
+/**
+ * Claude Code Stop hook entrypoint for NLM.
+ *
+ * Fires after the model finishes a response. Scans the last assistant message
+ * in the transcript for substrings matching any session ID the recall hook
+ * surfaced this conversation (via the dedup memo). Each match becomes a
+ * citation event posted to the daemon at POST /api/recall/cite-event.
+ *
+ * Double duty:
+ *  - Per-recall useful_hit_rate metric (was the returned ID actually used?)
+ *  - Training-data substrate for a learned reranker (was_cited per query)
+ *
+ * Fail-open by design: any error yields a clean exit with no output. The
+ * Stop hook can never block Claude Code's response. The smoke test path
+ * succeeds even with missing transcript_path because the hook always logs
+ * a `kind:"stop"` line.
+ */
+
+import { pathToFileURL } from "node:url";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import {
+  detectCitations,
+  type CitationKind,
+} from "@core/hook/citation-detect.js";
+import { loadSurfaced } from "@core/hook/memo.js";
+import { loadCited, recordCited } from "@core/hook/cite-memo.js";
+import {
+  readAllAssistantTurns,
+  type ToolUseBlock,
+} from "@core/hook/transcript.js";
+
+const RESPONSE_PREVIEW_CHARS = 200;
+const POST_TIMEOUT_MS = 1500;
+
+export interface StopHookInput {
+  readonly conversationId: string;
+  readonly transcriptPath: string;
+  readonly stopHookActive: boolean;
+}
+
+export interface CitationEvent {
+  readonly id: string;
+  readonly kind: CitationKind;
+}
+
+export interface StopHookResult {
+  readonly conversationId: string;
+  readonly surfacedCount: number;
+  readonly citations: ReadonlyArray<CitationEvent>;
+  readonly responsePreview: string;
+  readonly skipped: boolean;
+}
+
+export interface RunStopHookDeps {
+  readonly postCitation: (
+    conversationId: string,
+    citedId: string,
+    kind: CitationKind,
+    responsePreview: string,
+  ) => Promise<void>;
+}
+
+export async function runStopHook(
+  input: StopHookInput,
+  deps: RunStopHookDeps,
+): Promise<StopHookResult> {
+  // stop_hook_active=true means Stop is firing again because a prior Stop
+  // hook returned control to the model. Skip to avoid double-counting.
+  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: ToolUseBlock[] = [];
+  const textParts: string[] = [];
+  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));
+
+  // Preview is the LAST turn's prose — that's what Edward saw when Stop
+  // fired. Stable substrate for the citation log even when detection
+  // ranges across earlier turns.
+  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 {
+      // Daemon down or HTTP error — local memo update below still records
+      // the citation so we don't repost on the next Stop fire.
+    }
+  }
+  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(): string {
+  return process.env["NLM_HOOK_LOG"] ?? join(homedir(), ".nlm", "hook-log.jsonl");
+}
+
+function logStopResult(result: StopHookResult): void {
+  try {
+    const path = logPath();
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(
+      path,
+      `${JSON.stringify({
+        ts: 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",
+      })}\n`,
+      "utf8",
+    );
+  } catch {
+    // Telemetry failure must never break the hook.
+  }
+}
+
+function readStdin(): Promise<string> {
+  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: string,
+  citedId: string,
+  kind: CitationKind,
+  responsePreview: string,
+): Promise<void> {
+  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(): Promise<void> {
+  try {
+    const raw = await readStdin();
+    const payload = JSON.parse(raw) as {
+      session_id?: unknown;
+      transcript_path?: unknown;
+      stop_hook_active?: unknown;
+    };
+    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 {
+    // Fail open — never block Claude Code's response.
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  void main();
+}