nlm-memory 0.4.0

package/dist/core/facts/extract-facts.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 type { ClassifyResult } from "../../ports/llm-client.js";
+import type { Fact } from "../../shared/types.js";
+export interface ExtractFactsOptions {
+    /** Generator for fact ids. Defaults to `fact_<randomUUID()>`. */
+    readonly idGenerator?: () => string;
+}
+export declare function extractFacts(result: ClassifyResult, sessionId: string, createdAt: string, opts?: ExtractFactsOptions): Fact[];

package/dist/core/facts/extract-facts.js

@@ -0,0 +1,37 @@
+/**
+ * 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";
+const CONFIDENCE_FLOOR = 0.4;
+export function extractFacts(result, sessionId, createdAt, opts = {}) {
+    if (result.confidence < CONFIDENCE_FLOOR)
+        return [];
+    const genId = opts.idGenerator ?? (() => `fact_${randomUUID()}`);
+    const out = [];
+    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;
+}
+//# sourceMappingURL=extract-facts.js.map

package/dist/core/facts/extract-facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-facts.js","sourceRoot":"","sources":["../../../src/core/facts/extract-facts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAO7B,MAAM,UAAU,YAAY,CAC1B,MAAsB,EACtB,SAAiB,EACjB,SAAiB,EACjB,OAA4B,EAAE;IAE9B,IAAI,MAAM,CAAC,UAAU,GAAG,gBAAgB;QAAE,OAAO,EAAE,CAAC;IACpD,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,UAAU,EAAE,EAAE,CAAC,CAAC;IACjE,MAAM,GAAG,GAAW,EAAE,CAAC;IACvB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAC/B,GAAG,CAAC,IAAI,CAAC;YACP,EAAE,EAAE,KAAK,EAAE;YACX,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,eAAe,EAAE,SAAS;YAC1B,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,IAAI;YACpC,SAAS;YACT,YAAY,EAAE,IAAI;YAClB,UAAU,EAAE,MAAM,CAAC,UAAU;SAC9B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/core/hook/citation-detect.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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";
+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 declare function detectCitations(input: CitationDetectInput): DetectedCitation[];
+/** Back-compat: prose-only detector returning a flat id list. */
+export declare function detectCitedIds(responseText: string, surfacedIds: Iterable<string>): string[];

package/dist/core/hook/citation-detect.js

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+const MIN_ID_LEN = 6;
+export function detectCitations(input) {
+    const surfaced = [];
+    const seen = 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 = new Set();
+    // 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, surfacedIds) {
+    return detectCitations({
+        responseText,
+        toolUses: [],
+        surfacedIds,
+    }).map((c) => c.id);
+}
+function isNlmTool(name) {
+    // 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) {
+    return name.endsWith("__cite_session");
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=citation-detect.js.map

package/dist/core/hook/citation-detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation-detect.js","sourceRoot":"","sources":["../../../src/core/hook/citation-detect.ts"],"names":[],"mappings":"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"}

package/dist/core/hook/cite-memo.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+export declare function loadCited(conversationId: string): Set<string>;
+export declare function recordCited(conversationId: string, ids: ReadonlyArray<string>): void;
+export declare function clearCited(conversationId: string): boolean;

package/dist/core/hook/cite-memo.js

@@ -0,0 +1,68 @@
+/**
+ * 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() {
+    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}.cited.json`);
+}
+export function loadCited(conversationId) {
+    try {
+        const path = memoPath(conversationId);
+        if (!existsSync(path))
+            return new Set();
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (!Array.isArray(parsed))
+            return new Set();
+        return new Set(parsed.filter((x) => typeof x === "string"));
+    }
+    catch {
+        return new Set();
+    }
+}
+export function recordCited(conversationId, ids) {
+    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) {
+    try {
+        const path = memoPath(conversationId);
+        if (!existsSync(path))
+            return false;
+        rmSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=cite-memo.js.map

package/dist/core/hook/cite-memo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cite-memo.js","sourceRoot":"","sources":["../../../src/core/hook/cite-memo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACrF,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,SAAS,QAAQ;IACf,OAAO,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;AACpF,CAAC;AAED,SAAS,QAAQ,CAAC,cAAsB;IACtC,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,IAAI,SAAS,CAAC;IACzE,OAAO,IAAI,CAAC,QAAQ,EAAE,EAAE,GAAG,IAAI,aAAa,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,cAAsB;IAC9C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC;QACtC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,GAAG,EAAE,CAAC;QACxC,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QAC/D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,GAAG,EAAE,CAAC;QAC7C,OAAO,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,GAAG,EAAE,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,cAAsB,EACtB,GAA0B;IAE1B,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAC7B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,SAAS,CAAC,cAAc,CAAC,CAAC;QACzC,KAAK,MAAM,EAAE,IAAI,GAAG;YAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrC,SAAS,CAAC,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,aAAa,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACP,gDAAgD;IAClD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,cAAsB;IAC/C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC;QACtC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QACpC,MAAM,CAAC,IAAI,CAAC,CAAC;QACb,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/core/hook/claude-settings.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function shellQuote(arg: string): string;
+export declare function buildHookCommand(execPath: string, hookJs: string, mode: "shadow" | "live"): string;
+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 declare function smokeTestHookCommand(command: string, hookLogPath: string, timeoutMs?: number): SmokeTestResult;
+export type ClaudeHookEvent = "UserPromptSubmit" | "SessionStart" | "SessionEnd" | "Stop" | "PreCompact" | "SubagentStart" | "PostToolUse" | "PreToolUse";
+export declare function addHook(settingsPath: string, command: string, event?: ClaudeHookEvent): void;
+/**
+ * Remove the NLM-tagged hook entry from one event (default UserPromptSubmit)
+ * or every event when `event === "*"`. Leaves unrelated entries untouched.
+ */
+export declare function removeHook(settingsPath: string, event?: ClaudeHookEvent | "*"): void;

package/dist/core/hook/claude-settings.js

@@ -0,0 +1,117 @@
+/**
+ * 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",
+];
+/**
+ * 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) {
+    return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+export function buildHookCommand(execPath, hookJs, mode) {
+    return `NLM_HOOK_MODE=${mode} ${shellQuote(execPath)} ${shellQuote(hookJs)}`;
+}
+/**
+ * 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, hookLogPath, timeoutMs = 5000) {
+    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 };
+}
+function read(path) {
+    if (!existsSync(path))
+        return {};
+    const parsed = 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;
+}
+function write(path, settings) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+}
+function isNlmEntry(entry) {
+    return entry.hooks.some((h) => HOOK_SCRIPT_MARKERS.some((marker) => h.command.includes(marker)));
+}
+export function addHook(settingsPath, command, event = "UserPromptSubmit") {
+    const settings = read(settingsPath);
+    const hooks = settings.hooks ?? {};
+    const existing = hooks[event] ?? [];
+    const others = existing.filter((e) => !isNlmEntry(e));
+    const next = [
+        ...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, event = "UserPromptSubmit") {
+    if (!existsSync(settingsPath))
+        return;
+    const settings = read(settingsPath);
+    const allHooks = settings.hooks ?? {};
+    const events = event === "*" ? Object.keys(allHooks) : [event];
+    const nextHooks = { ...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 });
+}
+//# sourceMappingURL=claude-settings.js.map

package/dist/core/hook/claude-settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-settings.js","sourceRoot":"","sources":["../../../src/core/hook/claude-settings.ts"],"names":[],"mappings":"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"}

package/dist/core/hook/gate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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";
+export declare function classifyPrompt(prompt: string): PromptClass;

package/dist/core/hook/gate.js

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+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) {
+    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";
+}
+//# sourceMappingURL=gate.js.map

package/dist/core/hook/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../../src/core/hook/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,cAAc,GAClB,wJAAwJ,CAAC;AAE3J,MAAM,iBAAiB,GACrB,uGAAuG,CAAC;AAE1G,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACrD,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC;AAC/D,CAAC"}

package/dist/core/hook/hook-log.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 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";
+}
+export declare function appendHookLog(entry: HookLogEntry): void;

package/dist/core/hook/hook-log.js

@@ -0,0 +1,28 @@
+/**
+ * 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";
+function logPath() {
+    return process.env["NLM_HOOK_LOG"] ?? join(homedir(), ".nlm", "hook-log.jsonl");
+}
+export function appendHookLog(entry) {
+    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.
+    }
+}
+//# sourceMappingURL=hook-log.js.map

package/dist/core/hook/hook-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-log.js","sourceRoot":"","sources":["../../../src/core/hook/hook-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAc1C,SAAS,OAAO;IACd,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAmB;IAC/C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;QACvB,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9C,+EAA+E;QAC/E,cAAc,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,+CAA+C;IACjD,CAAC;AACH,CAAC"}

package/dist/core/hook/memo-sweep.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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.
+ */
+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;
+}
+/**
+ * One-shot sweep. Returns the report; safe to call from tests or one-off
+ * CLI invocations without standing up the scheduler.
+ */
+export declare function sweepMemoDir(opts?: MemoSweepOptions): SweepReport;
+/**
+ * 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 declare class MemoSweepScheduler {
+    private readonly opts;
+    private stopped;
+    private timer;
+    constructor(opts?: MemoSweepOptions);
+    start(): void;
+    stop(): void;
+    tick(): SweepReport;
+    private scheduleNext;
+}