nlm-memory 0.4.0

package/dist/core/recall/useful-scan.js

@@ -0,0 +1,300 @@
+/**
+ * Batch scanner for the useful_hit_rate metric.
+ *
+ * Joins hook-log.jsonl (recall events) against Claude Code conversation
+ * transcripts, writes one useful-hit-log.jsonl entry per recall event,
+ * and returns aggregate counts.
+ *
+ * A recall is "useful" when ≥1 of the surfaced session IDs appears in the
+ * text or tool_use inputs of the next NEXT_TURNS_LIMIT assistant turns after
+ * the hook fired. Entries with no matching transcript get useful=null
+ * (unmeasurable).
+ *
+ * Probe entries (promptPreview matching PROBE_PATTERNS) are excluded from
+ * the scan to keep the metric clean.
+ */
+import { readFile, appendFile, stat, mkdir, readdir } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+const NEXT_TURNS_LIMIT = 3;
+const PROBE_PATTERNS = [
+    /concurrency probe/i,
+    /test probe/i,
+    /path test/i,
+    /recall test/i,
+    /smoke/i,
+    /cutover/i,
+];
+export function defaultUsefulHitLogPath() {
+    return process.env["NLM_USEFUL_HIT_LOG"] ?? join(homedir(), ".nlm", "useful-hit-log.jsonl");
+}
+function defaultHookLogPath() {
+    return process.env["NLM_HOOK_LOG"] ?? join(homedir(), ".nlm", "hook-log.jsonl");
+}
+function defaultTranscriptsDir() {
+    return join(homedir(), ".claude", "projects");
+}
+export function isProbe(promptPreview) {
+    return PROBE_PATTERNS.some((re) => re.test(promptPreview));
+}
+async function findTranscriptPath(conversationId, transcriptsDir) {
+    let names;
+    try {
+        names = await readdir(transcriptsDir);
+    }
+    catch {
+        return null;
+    }
+    for (const name of names) {
+        const candidate = join(transcriptsDir, name, `${conversationId}.jsonl`);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Read assistant turns from a Claude Code transcript JSONL that have a
+ * timestamp >= afterTs. Returns up to `limit` turns, each as a single
+ * concatenated string of text + serialized tool_use inputs.
+ */
+export function extractAssistantTurnsAfter(transcriptPath, afterTs, limit) {
+    let raw;
+    try {
+        raw = readFileSync(transcriptPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const turns = [];
+    let pastCutoff = false;
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (!pastCutoff) {
+            const tsRaw = entry["timestamp"];
+            if (typeof tsRaw === "string") {
+                const ts = Date.parse(tsRaw);
+                if (Number.isFinite(ts) && ts >= afterTs)
+                    pastCutoff = true;
+            }
+            if (!pastCutoff)
+                continue;
+        }
+        if (entry["type"] !== "assistant")
+            continue;
+        const message = entry["message"];
+        if (!message)
+            continue;
+        const content = message["content"];
+        const parts = [];
+        if (typeof content === "string") {
+            if (content)
+                parts.push(content);
+        }
+        else if (Array.isArray(content)) {
+            for (const block of content) {
+                if (block["type"] === "text" && typeof block["text"] === "string") {
+                    parts.push(block["text"]);
+                }
+                else if (block["type"] === "tool_use") {
+                    parts.push(JSON.stringify(block["input"]));
+                }
+            }
+        }
+        if (parts.length > 0) {
+            turns.push(parts.join(" "));
+            if (turns.length >= limit)
+                break;
+        }
+    }
+    return turns;
+}
+export function findMatchedId(ids, turns) {
+    const haystack = turns.join(" ");
+    for (const id of ids) {
+        if (haystack.includes(id))
+            return id;
+    }
+    return null;
+}
+async function readHookRecalls(hookLogPath, cutoff) {
+    let raw;
+    try {
+        raw = await readFile(hookLogPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        // Skip stop-hook entries (they have a "kind" field)
+        if (typeof entry["kind"] === "string")
+            continue;
+        const ts = typeof entry["ts"] === "string" ? entry["ts"] : null;
+        if (!ts)
+            continue;
+        const tsMs = Date.parse(ts);
+        if (!Number.isFinite(tsMs) || tsMs < cutoff)
+            continue;
+        const wouldInject = Array.isArray(entry["wouldInject"])
+            ? entry["wouldInject"].filter((x) => typeof x === "string")
+            : [];
+        if (wouldInject.length === 0)
+            continue;
+        const conversationId = typeof entry["conversationId"] === "string" ? entry["conversationId"] : null;
+        if (!conversationId)
+            continue;
+        const promptPreview = typeof entry["promptPreview"] === "string" ? entry["promptPreview"] : "";
+        if (isProbe(promptPreview))
+            continue;
+        results.push({ ts, conversationId, promptPreview, wouldInject });
+    }
+    return results;
+}
+async function readScannedKeys(usefulHitLogPath) {
+    const seen = new Set();
+    try {
+        await stat(usefulHitLogPath);
+    }
+    catch {
+        return seen;
+    }
+    let raw;
+    try {
+        raw = await readFile(usefulHitLogPath, "utf8");
+    }
+    catch {
+        return seen;
+    }
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        const ts = typeof entry["ts"] === "string" ? entry["ts"] : null;
+        const convId = typeof entry["conversationId"] === "string" ? entry["conversationId"] : null;
+        if (ts && convId)
+            seen.add(`${ts}:${convId}`);
+    }
+    return seen;
+}
+export async function scanUsefulHits(opts) {
+    const days = opts.days ?? 1;
+    const hookLogPath = opts.hookLogPath ?? defaultHookLogPath();
+    const usefulHitLogPath = opts.usefulHitLogPath ?? defaultUsefulHitLogPath();
+    const transcriptsDir = opts.transcriptsDir ?? defaultTranscriptsDir();
+    const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+    const recalls = await readHookRecalls(hookLogPath, cutoff);
+    const scannedKeys = await readScannedKeys(usefulHitLogPath);
+    let total = 0;
+    let measurable = 0;
+    let useful = 0;
+    const newEntries = [];
+    for (const recall of recalls) {
+        total += 1;
+        const key = `${recall.ts}:${recall.conversationId}`;
+        if (scannedKeys.has(key))
+            continue;
+        const transcriptPath = await findTranscriptPath(recall.conversationId, transcriptsDir);
+        const hookTs = Date.parse(recall.ts);
+        let usefulVal = null;
+        let matchedId = null;
+        if (transcriptPath !== null && Number.isFinite(hookTs)) {
+            const turns = extractAssistantTurnsAfter(transcriptPath, hookTs, NEXT_TURNS_LIMIT);
+            if (turns.length > 0) {
+                measurable += 1;
+                matchedId = findMatchedId(recall.wouldInject, turns);
+                usefulVal = matchedId !== null;
+                if (usefulVal)
+                    useful += 1;
+            }
+        }
+        newEntries.push({
+            ts: recall.ts,
+            source: "hook",
+            conversationId: recall.conversationId,
+            returnedIds: recall.wouldInject,
+            useful: usefulVal,
+            matchedId,
+            scannedAt: new Date().toISOString(),
+        });
+    }
+    if (!opts.dryRun && newEntries.length > 0) {
+        await mkdir(dirname(usefulHitLogPath), { recursive: true });
+        await appendFile(usefulHitLogPath, newEntries.map((e) => JSON.stringify(e)).join("\n") + "\n", "utf8");
+    }
+    return { total, measurable, useful, appended: opts.dryRun ? 0 : newEntries.length };
+}
+/**
+ * Compute useful_hit_rate from an existing useful-hit-log.jsonl over a
+ * rolling window. Returns null if the log is absent or has no measurable
+ * entries in the window.
+ */
+export async function readUsefulHitRate(usefulHitLogPath = defaultUsefulHitLogPath(), days = 1) {
+    try {
+        await stat(usefulHitLogPath);
+    }
+    catch {
+        return null;
+    }
+    let raw;
+    try {
+        raw = await readFile(usefulHitLogPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+    let measurable = 0;
+    let useful = 0;
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        const tsRaw = typeof entry["ts"] === "string" ? entry["ts"] : null;
+        if (!tsRaw)
+            continue;
+        const ts = Date.parse(tsRaw);
+        if (!Number.isFinite(ts) || ts < cutoff)
+            continue;
+        if (entry["useful"] === null || entry["useful"] === undefined)
+            continue;
+        measurable += 1;
+        if (entry["useful"] === true)
+            useful += 1;
+    }
+    return measurable === 0 ? null : Math.round((useful / measurable) * 1000) / 1000;
+}
+//# sourceMappingURL=useful-scan.js.map

package/dist/core/recall/useful-scan.js.map

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

package/dist/core/recall-facts/fact-query-log.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Fact query log + stats. The measurement surface for "are agents actually
+ * using the FactStore" — mirrors core/recall/query-log.ts but for fact
+ * recall. Every /api/recall/facts call appends one line; /api/recall/facts/
+ * stats reads it back.
+ *
+ * Telemetry path — never raises. File format: one JSON object per line at
+ * $NLM_FACT_QUERY_LOG or ~/.nlm/fact_query_log.jsonl. Append-only.
+ *
+ * Without this, the FactStore is a write-only system: facts go in via
+ * ingest + backfill, but there's no signal on whether anything reads them.
+ */
+import type { FactKind, RecallMode } from "../../shared/types.js";
+export interface FactLogEntry {
+    readonly source: string;
+    readonly query: string | null;
+    readonly subject: string | null;
+    readonly predicate: string | null;
+    readonly kind: FactKind | null;
+    readonly mode: RecallMode;
+    readonly limit: number;
+    readonly nResults: number;
+    readonly returnedIds: ReadonlyArray<string>;
+}
+export interface FactStatsResult {
+    readonly days: number;
+    readonly total: number;
+    readonly with_results: number;
+    readonly hit_rate: number;
+    readonly by_source: Record<string, number>;
+    readonly top_subjects: ReadonlyArray<{
+        readonly subject: string;
+        readonly count: number;
+    }>;
+    readonly top_predicates: ReadonlyArray<{
+        readonly predicate: string;
+        readonly count: number;
+    }>;
+    readonly log_present: boolean;
+}
+export declare function logFactQuery(entry: FactLogEntry, logPath?: string): Promise<void>;
+export declare function factRecallStats(days: number, logPath?: string): Promise<FactStatsResult>;

package/dist/core/recall-facts/fact-query-log.js

@@ -0,0 +1,115 @@
+/**
+ * Fact query log + stats. The measurement surface for "are agents actually
+ * using the FactStore" — mirrors core/recall/query-log.ts but for fact
+ * recall. Every /api/recall/facts call appends one line; /api/recall/facts/
+ * stats reads it back.
+ *
+ * Telemetry path — never raises. File format: one JSON object per line at
+ * $NLM_FACT_QUERY_LOG or ~/.nlm/fact_query_log.jsonl. Append-only.
+ *
+ * Without this, the FactStore is a write-only system: facts go in via
+ * ingest + backfill, but there's no signal on whether anything reads them.
+ */
+import { appendFile, mkdir, readFile, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+function defaultLogPath() {
+    return process.env["NLM_FACT_QUERY_LOG"] ?? join(homedir(), ".nlm", "fact_query_log.jsonl");
+}
+export async function logFactQuery(entry, logPath = defaultLogPath()) {
+    try {
+        await mkdir(dirname(logPath), { recursive: true });
+        const payload = {
+            ts: new Date().toISOString(),
+            source: entry.source,
+            query: entry.query,
+            subject: entry.subject,
+            predicate: entry.predicate,
+            kind: entry.kind,
+            mode: entry.mode,
+            limit: entry.limit,
+            n_results: entry.nResults,
+            returned_ids: entry.returnedIds,
+        };
+        await appendFile(logPath, JSON.stringify(payload) + "\n", "utf8");
+    }
+    catch {
+        // Telemetry must never break the call path.
+    }
+}
+export async function factRecallStats(days, logPath = defaultLogPath()) {
+    const base = {
+        days,
+        total: 0,
+        with_results: 0,
+        hit_rate: 0,
+        by_source: {},
+        top_subjects: [],
+        top_predicates: [],
+        log_present: false,
+    };
+    try {
+        await stat(logPath);
+    }
+    catch {
+        return base;
+    }
+    const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+    const bySource = new Map();
+    const subjectCounts = new Map();
+    const predicateCounts = new Map();
+    let total = 0;
+    let withResults = 0;
+    let raw;
+    try {
+        raw = await readFile(logPath, "utf8");
+    }
+    catch {
+        return { ...base, log_present: true };
+    }
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        const tsRaw = entry["ts"];
+        if (typeof tsRaw !== "string")
+            continue;
+        const ts = Date.parse(tsRaw);
+        if (!Number.isFinite(ts) || ts < cutoff)
+            continue;
+        total += 1;
+        const n = typeof entry["n_results"] === "number" ? entry["n_results"] : 0;
+        if (n > 0)
+            withResults += 1;
+        const source = typeof entry["source"] === "string" ? entry["source"] : "unknown";
+        bySource.set(source, (bySource.get(source) ?? 0) + 1);
+        const subj = entry["subject"];
+        if (typeof subj === "string" && subj) {
+            const norm = subj.toLowerCase().trim();
+            subjectCounts.set(norm, (subjectCounts.get(norm) ?? 0) + 1);
+        }
+        const pred = entry["predicate"];
+        if (typeof pred === "string" && pred) {
+            predicateCounts.set(pred, (predicateCounts.get(pred) ?? 0) + 1);
+        }
+    }
+    const topN = (m) => [...m.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10);
+    return {
+        days,
+        total,
+        with_results: withResults,
+        hit_rate: total === 0 ? 0 : Math.round((withResults / total) * 1000) / 1000,
+        by_source: Object.fromEntries([...bySource.entries()].sort((a, b) => b[1] - a[1])),
+        top_subjects: topN(subjectCounts).map(([subject, count]) => ({ subject, count })),
+        top_predicates: topN(predicateCounts).map(([predicate, count]) => ({ predicate, count })),
+        log_present: true,
+    };
+}
+//# sourceMappingURL=fact-query-log.js.map

package/dist/core/recall-facts/fact-query-log.js.map

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

package/dist/core/recall-facts/fact-recall-service.d.ts

@@ -0,0 +1,34 @@
+/**
+ * FactRecallService — agent-facing recall over the FactStore.
+ *
+ * Mirrors RecallService's keyword / semantic / hybrid pattern but works on
+ * Fact records, not Session records. Sessions and facts answer different
+ * questions and have incompatibly-shaped results, so this is a separate
+ * service with its own MCP tool — see Section 4 of factstore-design.md.
+ *
+ * Filter pipeline:
+ *   1. Storage pre-filter (subject, predicate, kind, minConfidence,
+ *      includeSuperseded). Cheap SQL.
+ *   2. Keyword scoring over (value, subject, predicate). Pure, in-memory.
+ *   3. Semantic KNN via fact_embeddings vec0 (when mode != keyword).
+ *   4. Hybrid merge: 0.6 semantic + 0.4 keyword, matching the session
+ *      recall weights.
+ *
+ * Confidence policy: default `minConfidence` is 0.6 (Section 1 of the plan).
+ * Facts with classifier confidence in [0.4, 0.6) get written by
+ * extractFacts but stay out of agent recall unless the caller lowers the
+ * floor explicitly.
+ */
+import type { FactStore } from "../../ports/fact-store.js";
+import type { LLMClient } from "../../ports/llm-client.js";
+import type { FactRecallQuery, FactRecallResult } from "../../shared/types.js";
+export interface FactRecallServiceDeps {
+    readonly factStore: FactStore;
+    readonly llm: LLMClient;
+}
+export declare class FactRecallService {
+    private readonly deps;
+    constructor(deps: FactRecallServiceDeps);
+    search(input: FactRecallQuery): Promise<FactRecallResult>;
+    private runSemantic;
+}