nlm-memory 0.5.0 → 0.5.2

package/src/hook/hook-auth.ts

@@ -1,18 +0,0 @@
-/**
- * Shared helper: Bearer token for hook → /api/* HTTP calls.
- *
- * The HTTP daemon's /api/* gate requires either a same-origin browser
- * request (Origin header set by the browser) or a Bearer token. Hooks
- * are CLI processes with no Origin, so they need the token.
- *
- * Reads NLM_MCP_TOKEN from process.env (assumes autoloadEnv() has been
- * called first). Returns an empty headers object when no token is set
- * so legacy installs without a token still work — the daemon's gate
- * also accepts unauthenticated loopback requests when no token is set.
- */
-
-export function hookAuthHeaders(extra: Record<string, string> = {}): Record<string, string> {
-  const token = process.env["NLM_MCP_TOKEN"];
-  if (!token) return { ...extra };
-  return { ...extra, authorization: `Bearer ${token}` };
-}

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

@@ -1,180 +0,0 @@
-/**
- * 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";
-import { autoloadEnv } from "../llm/env-autoload.js";
-import { hookAuthHeaders } from "./hook-auth.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: hookAuthHeaders({ "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 {
-    // Load ~/.nlm/.env so NLM_MCP_TOKEN is available before we hit /api/recall.
-    // Hooks run as short-lived processes spawned by Claude Code with no shell
-    // env beyond what the parent passed — explicit .env load is required.
-    autoloadEnv();
-    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

@@ -1,81 +0,0 @@
-/**
- * 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

@@ -1,168 +0,0 @@
-/**
- * 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";
-import { autoloadEnv } from "../llm/env-autoload.js";
-import { hookAuthHeaders } from "./hook-auth.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: hookAuthHeaders({ "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 {
-    autoloadEnv();
-    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

@@ -1,239 +0,0 @@
-/**
- * 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";
-import { autoloadEnv } from "../llm/env-autoload.js";
-import { hookAuthHeaders } from "./hook-auth.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: hookAuthHeaders({ "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 {
-    autoloadEnv();
-    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();
-}