nlm-memory 0.4.2 → 0.5.1

package/src/core/facts/extract-facts.ts

@@ -1,50 +0,0 @@
-/**
- * extractFacts — pure transform from ClassifyResult to Fact[].
- *
- * Lives in core/, has no framework imports, no clock or randomness coupling
- * (id generator and timestamp are injected so tests are deterministic).
- * Phase B.2 — see docs/plans/factstore-design.md Section 3.
- *
- * Confidence policy (Section 3 of the plan): facts inherit the session-level
- * confidence verbatim. Below 0.4 the function returns an empty array — the
- * session still ingests with markers, but its facts are dropped as
- * extraction-quality noise. Between 0.4 and 0.6 facts are written but will
- * be filtered out of recall by the FactStore default `minConfidence: 0.6`.
- */
-
-import { randomUUID } from "node:crypto";
-import type { ClassifyResult } from "@ports/llm-client.js";
-import type { Fact } from "@shared/types.js";
-
-const CONFIDENCE_FLOOR = 0.4;
-
-export interface ExtractFactsOptions {
-  /** Generator for fact ids. Defaults to `fact_<randomUUID()>`. */
-  readonly idGenerator?: () => string;
-}
-
-export function extractFacts(
-  result: ClassifyResult,
-  sessionId: string,
-  createdAt: string,
-  opts: ExtractFactsOptions = {},
-): Fact[] {
-  if (result.confidence < CONFIDENCE_FLOOR) return [];
-  const genId = opts.idGenerator ?? (() => `fact_${randomUUID()}`);
-  const out: Fact[] = [];
-  for (const raw of result.facts) {
-    out.push({
-      id: genId(),
-      kind: raw.kind,
-      subject: raw.subject,
-      predicate: raw.predicate,
-      value: raw.value,
-      sourceSessionId: sessionId,
-      sourceQuote: raw.sourceQuote ?? null,
-      createdAt,
-      supersededBy: null,
-      confidence: result.confidence,
-    });
-  }
-  return out;
-}

package/src/core/hook/citation-detect.ts

@@ -1,124 +0,0 @@
-/**
- * Detects which surfaced recall IDs an assistant turn cited.
- *
- * Two channels, ordered by signal strength:
- *  - tool_use:  the model invoked an MCP NLM tool (get_session, recall_facts,
- *               get_fact_history, recall_sessions) whose input references a
- *               surfaced ID. This is the strong "the model dug into the
- *               surfaced session" signal. Almost no false positives.
- *  - prose:     the surfaced ID appears as a substring in the response text.
- *               Models rarely echo session IDs verbatim, so this channel
- *               fires in practice almost never — kept for completeness.
- *
- * Returns both the union of cited IDs and the per-ID channel so the citation
- * log can carry kind metadata. ID minimum length keeps generic short tokens
- * from false-positiving against either channel.
- *
- * This is the training-data substrate for a future learned reranker.
- */
-
-import type { ToolUseBlock } from "./transcript.js";
-
-const MIN_ID_LEN = 6;
-
-export type CitationKind = "tool_use" | "prose";
-
-export interface CitationDetectInput {
-  readonly responseText: string;
-  readonly toolUses: ReadonlyArray<ToolUseBlock>;
-  readonly surfacedIds: Iterable<string>;
-}
-
-export interface DetectedCitation {
-  readonly id: string;
-  readonly kind: CitationKind;
-}
-
-export function detectCitations(input: CitationDetectInput): DetectedCitation[] {
-  const surfaced: string[] = [];
-  const seen = new Set<string>();
-  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: DetectedCitation[] = [];
-  const claimedByToolUse = new Set<string>();
-
-  // Channel A: tool_use. Two sub-cases:
-  //
-  // A1: cite_session — the model called the explicit citation primitive with
-  //     the session ID in tu.input.id. Strongest possible signal: structured,
-  //     deterministic, zero ambiguity. ID must be a surfaced session ID.
-  //
-  // A2: other NLM tools (get_session, recall_sessions, recall_facts,
-  //     get_fact_history) — stringify the input and substring-scan for surfaced
-  //     IDs. These tools accept ids via top-level fields, so the serialization
-  //     always includes the id when used.
-  for (const tu of input.toolUses) {
-    if (!isNlmTool(tu.name)) continue;
-    if (isCiteSessionTool(tu.name)) {
-      // A1: explicit cite_session call — the MCP server handler already wrote
-      // this citation directly to the citation log (citeSessionHandler →
-      // appendCitation). Detecting it here again would produce a second log
-      // entry for the same model action (double-count). Skip so the Stop hook
-      // only captures implicit citations the MCP handler didn't see.
-      continue;
-    }
-    // A2: other NLM tools — serialize and substring-scan.
-    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);
-      }
-    }
-  }
-
-  // Channel B: prose. Only emit if the tool_use channel didn't already
-  // claim this id — same id shouldn't double-count.
-  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;
-}
-
-/** Back-compat: prose-only detector returning a flat id list. */
-export function detectCitedIds(
-  responseText: string,
-  surfacedIds: Iterable<string>,
-): string[] {
-  return detectCitations({
-    responseText,
-    toolUses: [],
-    surfacedIds,
-  }).map((c) => c.id);
-}
-
-function isNlmTool(name: string): boolean {
-  // Claude Code namespaces MCP tools as `mcp__<server>__<tool>`. The NLM
-  // server name is "nlm-memory" in the user's .mcp.json today; accept any
-  // server name containing "nlm" so future renames stay covered.
-  return /^mcp__[^_]*nlm[^_]*__/.test(name);
-}
-
-function isCiteSessionTool(name: string): boolean {
-  return name.endsWith("__cite_session");
-}
-
-function safeStringify(value: unknown): string {
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return "";
-  }
-}

package/src/core/hook/cite-memo.ts

@@ -1,68 +0,0 @@
-/**
- * Per-conversation dedup memo for the Stop hook's citation detector.
- *
- * The Stop hook scans the full transcript every fire, so a long conversation
- * with repeated Stop firings would otherwise re-detect the same tool_use
- * citations every turn and double-count them in the citation log. This memo
- * holds the set of (conversationId, citedId) pairs already posted, so each
- * citation lands exactly once regardless of how many times Stop fires.
- *
- * Storage parallels the surfaced-memo (`memo.ts`): same state directory
- * (`~/.nlm/hook-state/`, overridable via NLM_HOOK_STATE_DIR), filename suffix
- * `.cited.json` to distinguish from the surfaced memo's `.json`. The existing
- * memo-sweep walks the directory by mtime and cleans both files together.
- *
- * Defensive: a missing or corrupt file yields an empty set; a write failure
- * is swallowed. Telemetry path — must never break the hook.
- */
-
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-function stateDir(): string {
-  return process.env["NLM_HOOK_STATE_DIR"] ?? join(homedir(), ".nlm", "hook-state");
-}
-
-function memoPath(conversationId: string): string {
-  const safe = conversationId.replace(/[^A-Za-z0-9_-]/g, "_") || "unknown";
-  return join(stateDir(), `${safe}.cited.json`);
-}
-
-export function loadCited(conversationId: string): Set<string> {
-  try {
-    const path = memoPath(conversationId);
-    if (!existsSync(path)) return new Set();
-    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
-    if (!Array.isArray(parsed)) return new Set();
-    return new Set(parsed.filter((x): x is string => typeof x === "string"));
-  } catch {
-    return new Set();
-  }
-}
-
-export function recordCited(
-  conversationId: string,
-  ids: ReadonlyArray<string>,
-): void {
-  if (ids.length === 0) return;
-  try {
-    const merged = loadCited(conversationId);
-    for (const id of ids) merged.add(id);
-    mkdirSync(stateDir(), { recursive: true });
-    writeFileSync(memoPath(conversationId), JSON.stringify([...merged]), "utf8");
-  } catch {
-    // Memo write failure must never break the hook.
-  }
-}
-
-export function clearCited(conversationId: string): boolean {
-  try {
-    const path = memoPath(conversationId);
-    if (!existsSync(path)) return false;
-    rmSync(path);
-    return true;
-  } catch {
-    return false;
-  }
-}

package/src/core/hook/claude-settings.ts

@@ -1,166 +0,0 @@
-/**
- * Adds/removes NLM hook entries in a Claude Code settings.json.
- *
- * NLM-owned entries are identified by HOOK_SCRIPT_MARKERS. add is idempotent
- * (replaces any prior NLM entry for the same event); remove strips only NLM
- * entries and preserves everything else.
- */
-
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
-import { spawnSync } from "node:child_process";
-
-// Every NLM hook script ends in `-hook.js`. We tag entries we own by
-// matching the filename suffix against this list. Add new entries here
-// when a new hook script ships.
-const HOOK_SCRIPT_MARKERS = [
-  "prompt-recall-hook.js",
-  "session-end-hook.js",
-  "stop-hook.js",
-  "session-start-hook.js",
-  "pre-compact-hook.js",
-  "subagent-start-hook.js",
-] as const;
-
-/**
- * Single-quote a shell argument so paths with spaces or other shell
- * metacharacters survive `sh -c` tokenization. Without this, a path like
- * `/Users/echalupa/Documents/Coding Projects/...` is split on whitespace
- * and node receives the wrong argv — silent hook bricking.
- */
-export function shellQuote(arg: string): string {
-  return `'${arg.replace(/'/g, "'\\''")}'`;
-}
-
-export function buildHookCommand(
-  execPath: string,
-  hookJs: string,
-  mode: "shadow" | "live",
-): string {
-  return `NLM_HOOK_MODE=${mode} ${shellQuote(execPath)} ${shellQuote(hookJs)}`;
-}
-
-export interface SmokeTestResult {
-  readonly ok: boolean;
-  readonly reason?: string;
-  readonly stderr?: string;
-}
-
-/**
- * Invoke the wired command exactly the way Claude Code does (sh -c with
- * JSON on stdin) and confirm the hook log gained an entry. Catches the
- * class of failures where settings.json looks valid but the hook fails
- * at startup (path tokenization, missing modules, etc.).
- */
-export function smokeTestHookCommand(
-  command: string,
-  hookLogPath: string,
-  timeoutMs = 5000,
-): SmokeTestResult {
-  const sizeBefore = existsSync(hookLogPath) ? statSync(hookLogPath).size : 0;
-  const result = spawnSync("sh", ["-c", command], {
-    input: JSON.stringify({ prompt: "smoke test", session_id: "install-smoke" }),
-    timeout: timeoutMs,
-    encoding: "utf8",
-  });
-  if (result.error) {
-    return { ok: false, reason: `spawn failed: ${result.error.message}` };
-  }
-  if (result.status !== 0) {
-    return {
-      ok: false,
-      reason: `exit code ${result.status ?? "null"}`,
-      stderr: result.stderr,
-    };
-  }
-  const sizeAfter = existsSync(hookLogPath) ? statSync(hookLogPath).size : 0;
-  if (sizeAfter <= sizeBefore) {
-    return {
-      ok: false,
-      reason: `no entry appended to ${hookLogPath}`,
-      stderr: result.stderr,
-    };
-  }
-  return { ok: true };
-}
-
-export type ClaudeHookEvent =
-  | "UserPromptSubmit"
-  | "SessionStart"
-  | "SessionEnd"
-  | "Stop"
-  | "PreCompact"
-  | "SubagentStart"
-  | "PostToolUse"
-  | "PreToolUse";
-
-interface HookCommand {
-  readonly type: string;
-  readonly command: string;
-}
-interface HookEntry {
-  readonly hooks: ReadonlyArray<HookCommand>;
-}
-interface ClaudeSettings {
-  hooks?: Record<string, HookEntry[]>;
-  [key: string]: unknown;
-}
-
-function read(path: string): ClaudeSettings {
-  if (!existsSync(path)) return {};
-  const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
-  if (typeof parsed !== "object" || parsed === null) {
-    throw new Error(`Claude settings at ${path} is not a JSON object`);
-  }
-  return parsed as ClaudeSettings;
-}
-
-function write(path: string, settings: ClaudeSettings): void {
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
-}
-
-function isNlmEntry(entry: HookEntry): boolean {
-  return entry.hooks.some((h) =>
-    HOOK_SCRIPT_MARKERS.some((marker) => h.command.includes(marker)),
-  );
-}
-
-export function addHook(
-  settingsPath: string,
-  command: string,
-  event: ClaudeHookEvent = "UserPromptSubmit",
-): void {
-  const settings = read(settingsPath);
-  const hooks = settings.hooks ?? {};
-  const existing = hooks[event] ?? [];
-  const others = existing.filter((e) => !isNlmEntry(e));
-  const next: HookEntry[] = [
-    ...others,
-    { hooks: [{ type: "command", command }] },
-  ];
-  write(settingsPath, { ...settings, hooks: { ...hooks, [event]: next } });
-}
-
-/**
- * Remove the NLM-tagged hook entry from one event (default UserPromptSubmit)
- * or every event when `event === "*"`. Leaves unrelated entries untouched.
- */
-export function removeHook(
-  settingsPath: string,
-  event: ClaudeHookEvent | "*" = "UserPromptSubmit",
-): void {
-  if (!existsSync(settingsPath)) return;
-  const settings = read(settingsPath);
-  const allHooks = settings.hooks ?? {};
-  const events: string[] = event === "*" ? Object.keys(allHooks) : [event];
-  const nextHooks: Record<string, HookEntry[]> = { ...allHooks };
-  for (const ev of events) {
-    const existing = nextHooks[ev];
-    if (!existing) continue;
-    const kept = existing.filter((e) => !isNlmEntry(e));
-    if (kept.length > 0) nextHooks[ev] = kept;
-    else delete nextHooks[ev];
-  }
-  write(settingsPath, { ...settings, hooks: nextHooks });
-}

package/src/core/hook/gate.ts

@@ -1,25 +0,0 @@
-/**
- * Prompt gate for the recall hook. Pure — no I/O.
- *
- * A conservative generative *excluder*: the default is "evaluate" (query
- * recall); only high-precision generative openers short-circuit to
- * "generative". A false "generative" wrongly skips recall — the exact
- * failure this feature fixes — so the generative set is deliberately tight.
- * It is calibrated further against shadow-mode logs.
- */
-
-export type PromptClass = "generative" | "evaluate";
-
-const 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;
-
-const GENERATIVE_OPENER =
-  /^(write|draft|create|compose|generate|brainstorm|design|outline|sketch|invent|rename|come up with)\b/i;
-
-export function classifyPrompt(prompt: string): PromptClass {
-  let p = prompt.trim();
-  for (let i = 0; i < 3 && LEADING_FILLER.test(p); i++) {
-    p = p.replace(LEADING_FILLER, "");
-  }
-  return GENERATIVE_OPENER.test(p) ? "generative" : "evaluate";
-}

package/src/core/hook/hook-log.ts

@@ -1,41 +0,0 @@
-/**
- * Append-only JSONL log for the recall hook. One line per prompt the hook
- * evaluated. This is the dataset the relevance gate (generative patterns +
- * score threshold) is calibrated against during the shadow window.
- *
- * Path defaults to ~/.nlm/hook-log.jsonl, overridable via NLM_HOOK_LOG.
- * appendHookLog swallows its own errors — telemetry must never break the hook.
- * Uses synchronous I/O: the hook is a short-lived per-prompt process, and an
- * async write could be lost if the process exits before it flushes.
- */
-
-import { appendFileSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import type { PromptClass } from "./gate.js";
-
-export interface HookLogEntry {
-  readonly ts: string;
-  readonly conversationId: string;
-  readonly promptPreview: string;
-  readonly gate: PromptClass;
-  readonly hits: ReadonlyArray<{ readonly id: string; readonly score: number }>;
-  readonly wouldInject: ReadonlyArray<string>;
-  readonly estTokens: number;
-  readonly mode: "shadow" | "live";
-}
-
-function logPath(): string {
-  return process.env["NLM_HOOK_LOG"] ?? join(homedir(), ".nlm", "hook-log.jsonl");
-}
-
-export function appendHookLog(entry: HookLogEntry): void {
-  try {
-    const path = logPath();
-    mkdirSync(dirname(path), { recursive: true });
-    // Sync I/O: hook is a short-lived process — async write could be lost on exit.
-    appendFileSync(path, `${JSON.stringify(entry)}\n`, "utf8");
-  } catch {
-    // Telemetry failure must never break the hook.
-  }
-}

package/src/core/hook/memo-sweep.ts

@@ -1,164 +0,0 @@
-/**
- * Idle sweep for per-conversation hook memo files.
- *
- * The SessionEnd hook is best-effort — Claude Code doesn't fire it on
- * crashes, kill -9, or IDE force-close. Without a backstop, memo files
- * at ~/.nlm/hook-state/<conv>.json accumulate forever for any session
- * that didn't close cleanly.
- *
- * This sweep is the daemon-side backstop. It runs on a timer, scans the
- * state directory, and deletes any memo whose mtime is older than the
- * dormant threshold. Reuses the same `age > day` threshold the dataset
- * builder uses to mark runtimes as "dormant" so the UI/dataset semantics
- * stay consistent across the system.
- *
- * Hooks are fast-path; this is the always-correct backstop.
- */
-
-import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-// Mirrors the dormant threshold in build-dataset.ts:
-//   age <= hour  → "active"
-//   age <= day   → "idle"
-//   age > day    → "dormant"
-// We sweep memos that are dormant.
-const DEFAULT_DORMANT_MS = 24 * 60 * 60 * 1000;
-const DEFAULT_INTERVAL_MS = 5 * 60 * 1000;
-
-export interface MemoSweepOptions {
-  /** Directory holding per-conversation memo files. Defaults to ~/.nlm/hook-state/. */
-  readonly stateDir?: string;
-  /** Age threshold in ms beyond which a memo is swept. Default 24h (dormant). */
-  readonly dormantMs?: number;
-  /** Tick interval in ms. Default 5 min. */
-  readonly intervalMs?: number;
-  /** Defaults to console.error. Set to a noop in tests. */
-  readonly logger?: (msg: string) => void;
-  /** Override for time source — for deterministic tests. */
-  readonly now?: () => number;
-}
-
-export interface SweepReport {
-  readonly scanned: number;
-  readonly deleted: number;
-  readonly kept: number;
-  readonly errors: number;
-}
-
-function defaultStateDir(): string {
-  return process.env["NLM_HOOK_STATE_DIR"] ?? join(homedir(), ".nlm", "hook-state");
-}
-
-/**
- * One-shot sweep. Returns the report; safe to call from tests or one-off
- * CLI invocations without standing up the scheduler.
- */
-export function sweepMemoDir(opts: MemoSweepOptions = {}): SweepReport {
-  const stateDir = opts.stateDir ?? defaultStateDir();
-  const dormantMs = opts.dormantMs ?? DEFAULT_DORMANT_MS;
-  const now = opts.now ?? Date.now;
-  const logger = opts.logger ?? ((msg) => console.error(msg));
-
-  if (!existsSync(stateDir)) {
-    return { scanned: 0, deleted: 0, kept: 0, errors: 0 };
-  }
-
-  let entries: ReadonlyArray<string>;
-  try {
-    entries = readdirSync(stateDir);
-  } catch (e) {
-    logger(`[memo-sweep] readdir failed for ${stateDir}: ${e instanceof Error ? e.message : String(e)}`);
-    return { scanned: 0, deleted: 0, kept: 0, errors: 1 };
-  }
-
-  const cutoff = now() - dormantMs;
-  let deleted = 0;
-  let kept = 0;
-  let errors = 0;
-
-  for (const name of entries) {
-    if (!name.endsWith(".json")) {
-      // Don't touch files we don't own (kept silently, don't even count).
-      continue;
-    }
-    const path = join(stateDir, name);
-    try {
-      const stat = statSync(path);
-      if (stat.mtimeMs < cutoff) {
-        rmSync(path);
-        deleted += 1;
-      } else {
-        kept += 1;
-      }
-    } catch (e) {
-      errors += 1;
-      logger(`[memo-sweep] failed on ${path}: ${e instanceof Error ? e.message : String(e)}`);
-    }
-  }
-
-  return { scanned: deleted + kept + errors, deleted, kept, errors };
-}
-
-/**
- * Periodic sweep loop. Mirrors ScanScheduler's start/stop shape so the
- * daemon can manage it the same way. First tick fires immediately on
- * start() — the daemon picking up after a long downtime should sweep
- * accumulated memos right away, not wait an interval.
- */
-export class MemoSweepScheduler {
-  private readonly opts: Required<Omit<MemoSweepOptions, "stateDir" | "now">> & {
-    readonly stateDir: string | undefined;
-    readonly now: (() => number) | undefined;
-  };
-  private stopped = true;
-  private timer: NodeJS.Timeout | null = null;
-
-  constructor(opts: MemoSweepOptions = {}) {
-    this.opts = {
-      stateDir: opts.stateDir,
-      dormantMs: opts.dormantMs ?? DEFAULT_DORMANT_MS,
-      intervalMs: opts.intervalMs ?? DEFAULT_INTERVAL_MS,
-      logger: opts.logger ?? ((msg) => console.error(msg)),
-      now: opts.now,
-    };
-  }
-
-  start(): void {
-    if (!this.stopped) return;
-    this.stopped = false;
-    this.scheduleNext(0);
-  }
-
-  stop(): void {
-    this.stopped = true;
-    if (this.timer) {
-      clearTimeout(this.timer);
-      this.timer = null;
-    }
-  }
-
-  tick(): SweepReport {
-    return sweepMemoDir({
-      dormantMs: this.opts.dormantMs,
-      logger: this.opts.logger,
-      ...(this.opts.stateDir !== undefined ? { stateDir: this.opts.stateDir } : {}),
-      ...(this.opts.now !== undefined ? { now: this.opts.now } : {}),
-    });
-  }
-
-  private scheduleNext(delayMs: number): void {
-    if (this.stopped) return;
-    this.timer = setTimeout(() => {
-      try {
-        this.tick();
-      } catch (e) {
-        this.opts.logger(`[memo-sweep] tick crashed: ${e instanceof Error ? e.message : String(e)}`);
-      }
-      this.scheduleNext(this.opts.intervalMs);
-    }, delayMs);
-    // Don't keep the event loop alive just for the sweep.
-    if (this.timer && typeof this.timer.unref === "function") this.timer.unref();
-  }
-}