nlm-memory 0.4.0

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

@@ -0,0 +1,112 @@
+/**
+ * Query log + stats aggregation. Mirrors recall.py's log_query() / stats().
+ *
+ * Telemetry path — never raises. The HTTP recall handler calls logQuery()
+ * after each /api/recall response; /api/recall/stats reads the same file
+ * back to drive the Pulse agent-recall observability panel.
+ *
+ * File format: one JSON object per line at $NLM_QUERY_LOG or
+ * ~/.nlm/query_log.jsonl. Append-only.
+ */
+import { appendFile, mkdir, readFile, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { readUsefulHitRate, defaultUsefulHitLogPath } from "./useful-scan.js";
+function defaultLogPath() {
+    return process.env["NLM_QUERY_LOG"] ?? join(homedir(), ".nlm", "query_log.jsonl");
+}
+export async function logQuery(entry, logPath = defaultLogPath()) {
+    try {
+        await mkdir(dirname(logPath), { recursive: true });
+        const payload = {
+            ts: new Date().toISOString(),
+            source: entry.source,
+            query: entry.query,
+            entity: entry.entity,
+            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 recallStats(days, logPath = defaultLogPath(), usefulHitLogPath = defaultUsefulHitLogPath()) {
+    const useful_hit_rate = await readUsefulHitRate(usefulHitLogPath, days);
+    const base = {
+        days,
+        total: 0,
+        with_results: 0,
+        hit_rate: 0,
+        useful_hit_rate,
+        by_source: {},
+        top_queries: [],
+        log_present: false,
+    };
+    try {
+        await stat(logPath);
+    }
+    catch {
+        return base;
+    }
+    const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+    const bySource = new Map();
+    const queryCounts = 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 q = entry["query"];
+        if (typeof q === "string" && q) {
+            const norm = q.toLowerCase().trim();
+            queryCounts.set(norm, (queryCounts.get(norm) ?? 0) + 1);
+        }
+    }
+    const sortedSources = [...bySource.entries()].sort((a, b) => b[1] - a[1]);
+    const sortedQueries = [...queryCounts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5);
+    return {
+        days,
+        total,
+        with_results: withResults,
+        hit_rate: total === 0 ? 0 : Math.round((withResults / total) * 1000) / 1000,
+        useful_hit_rate,
+        by_source: Object.fromEntries(sortedSources),
+        top_queries: sortedQueries.map(([query, count]) => ({ query, count })),
+        log_present: true,
+    };
+}
+//# sourceMappingURL=query-log.js.map

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

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

package/dist/core/recall/query-shape.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Query shape detection for force-include of keyword rank-1 in hybrid recall.
+ *
+ * Build F (2026-05-26): when a query has both a temporal marker and a
+ * named-entity-shaped token, the keyword-leg rank-1 session is force-included
+ * in the merged top-k result. Diagnostic justification: of 7 hybrid temporal
+ * misses where keyword found the right session, 5 had keyword rank=1 and
+ * pure RRF demoted them out of top-5 because the same session wasn't in
+ * semantic's top-15. Build E′ (asymmetric multiplicative boost) contributed
+ * zero — boost magnitude was too small to overcome the "appears in both lists
+ * at lower rank" advantage. Force-include sidesteps RRF math entirely.
+ *
+ * Probe data (n=500 LongMemEval-S, hybrid k=5):
+ *   - 17.3% of temporal-reasoning queries match the shape
+ *   - 0% of single-session-preference, 0% of single-session-assistant
+ *   - 1.4-2.6% of other types — bounded blast radius
+ */
+export interface QueryShape {
+    readonly hasTemporal: boolean;
+    readonly hasNamedEntity: boolean;
+}
+export declare function detectQueryShape(query: string): QueryShape;

package/dist/core/recall/query-shape.js

@@ -0,0 +1,64 @@
+/**
+ * Query shape detection for force-include of keyword rank-1 in hybrid recall.
+ *
+ * Build F (2026-05-26): when a query has both a temporal marker and a
+ * named-entity-shaped token, the keyword-leg rank-1 session is force-included
+ * in the merged top-k result. Diagnostic justification: of 7 hybrid temporal
+ * misses where keyword found the right session, 5 had keyword rank=1 and
+ * pure RRF demoted them out of top-5 because the same session wasn't in
+ * semantic's top-15. Build E′ (asymmetric multiplicative boost) contributed
+ * zero — boost magnitude was too small to overcome the "appears in both lists
+ * at lower rank" advantage. Force-include sidesteps RRF math entirely.
+ *
+ * Probe data (n=500 LongMemEval-S, hybrid k=5):
+ *   - 17.3% of temporal-reasoning queries match the shape
+ *   - 0% of single-session-preference, 0% of single-session-assistant
+ *   - 1.4-2.6% of other types — bounded blast radius
+ */
+const TEMPORAL_PATTERNS = [
+    /\b\d+\s+(day|week|month|year)s?\s+ago\b/i,
+    /\b(last|past|next)\s+(week|month|year|monday|tuesday|wednesday|thursday|friday|saturday|sunday)\b/i,
+    /\bwhen\s+did\b/i,
+    /\b(before|after)\s+I\b/,
+    /\bago\b/i,
+    /\b(yesterday|today|tomorrow)\b/i,
+    /\bhow\s+(long|many)\s+(days?|weeks?|months?|years?)\s+ago\b/i,
+];
+const COMMON_CAPS_NON_NE = new Set([
+    "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday",
+    "january", "february", "march", "april", "may", "june", "july", "august",
+    "september", "october", "november", "december",
+    "i", "i'd", "i've", "i'm", "i'll",
+]);
+export function detectQueryShape(query) {
+    if (!query)
+        return { hasTemporal: false, hasNamedEntity: false };
+    const hasTemporal = TEMPORAL_PATTERNS.some((re) => re.test(query));
+    const hasNamedEntity = detectNamedEntity(query);
+    return { hasTemporal, hasNamedEntity };
+}
+function detectNamedEntity(query) {
+    const tokens = query.split(/[\s,.;:!?()"'`]+/).filter((t) => t.length > 0);
+    if (tokens.length === 0)
+        return false;
+    for (let i = 1; i < tokens.length; i++) {
+        const tok = tokens[i];
+        if (tok && isNamedEntityToken(tok))
+            return true;
+    }
+    return false;
+}
+function isNamedEntityToken(tok) {
+    if (COMMON_CAPS_NON_NE.has(tok.toLowerCase()))
+        return false;
+    if (tok.length < 2)
+        return false;
+    if (/^[A-Z]{2,}$/.test(tok))
+        return true;
+    const hasUpper = /[A-Z]/.test(tok);
+    const hasLower = /[a-z]/.test(tok);
+    if (hasUpper && hasLower)
+        return true;
+    return false;
+}
+//# sourceMappingURL=query-shape.js.map

package/dist/core/recall/query-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-shape.js","sourceRoot":"","sources":["../../../src/core/recall/query-shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,iBAAiB,GAA0B;IAC/C,0CAA0C;IAC1C,oGAAoG;IACpG,iBAAiB;IACjB,wBAAwB;IACxB,UAAU;IACV,iCAAiC;IACjC,8DAA8D;CAC/D,CAAC;AAEF,MAAM,kBAAkB,GAAwB,IAAI,GAAG,CAAC;IACtD,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ;IAC5E,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ;IACxE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU;IAC9C,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAClC,CAAC,CAAC;AAOH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IACjE,MAAM,WAAW,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACnE,MAAM,cAAc,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAChD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,CAAC;AACzC,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAa;IACtC,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3E,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,GAAG,IAAI,kBAAkB,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;IAClD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,kBAAkB,CAAC,GAAW;IACrC,IAAI,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5D,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACjC,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,QAAQ,IAAI,QAAQ;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,KAAK,CAAC;AACf,CAAC"}

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

@@ -0,0 +1,19 @@
+/**
+ * RecallService — the use case. Composes filters, keyword scoring, and
+ * semantic search into a single recall operation.
+ *
+ * Depends only on ports (SessionStore, LLMClient). No framework imports,
+ * no SQLite, no HTTP. Tests substitute fake adapters.
+ */
+import type { LLMClient } from "../../ports/llm-client.js";
+import type { SessionStore } from "../../ports/session-store.js";
+import type { RecallQuery, RecallResult } from "../../shared/types.js";
+export interface RecallServiceDeps {
+    readonly store: SessionStore;
+    readonly llm: LLMClient;
+}
+export declare class RecallService {
+    private readonly deps;
+    constructor(deps: RecallServiceDeps);
+    search(input: RecallQuery): Promise<RecallResult>;
+}

package/dist/core/recall/recall-service.js

@@ -0,0 +1,252 @@
+/**
+ * RecallService — the use case. Composes filters, keyword scoring, and
+ * semantic search into a single recall operation.
+ *
+ * Depends only on ports (SessionStore, LLMClient). No framework imports,
+ * no SQLite, no HTTP. Tests substitute fake adapters.
+ */
+import { LLMUnreachableError } from "../../ports/llm-client.js";
+import { applyFilter } from "./filter.js";
+import { keywordMatchFields } from "./match-fields.js";
+import { detectQueryShape } from "./query-shape.js";
+import { tokenSet } from "./tokenize.js";
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+// Reciprocal Rank Fusion constant (Cormack et al. 2009). k=60 is the
+// canonical literature default. RRF combines ranked lists from multiple
+// retrievers by summing 1/(k + rank) per retriever, ignoring raw scores —
+// robust to wildly different score distributions (BM25 unbounded vs cosine
+// in [-1,1]) without requiring normalization.
+const RRF_K = 60;
+const SEMANTIC_OVERFETCH = 3;
+const KEYWORD_OVERFETCH = 3;
+export class RecallService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async search(input) {
+        const mode = input.mode ?? "keyword";
+        const limit = clampLimit(input.limit);
+        const entity = input.entity ?? null;
+        const kind = input.kind ?? null;
+        const empty = {
+            query: input.query,
+            entity,
+            kind,
+            mode,
+            limit,
+            total: 0,
+            results: [],
+        };
+        if (!input.query && !entity && !kind)
+            return empty;
+        // 1. Search legs — ranked neighbor IDs only. No session bodies loaded.
+        const kwNeighbors = (mode === "keyword" || mode === "hybrid") && input.query
+            ? await this.deps.store.keywordSearch(input.query, limit * KEYWORD_OVERFETCH)
+            : [];
+        let semNeighbors = [];
+        let semError = null;
+        if ((mode === "semantic" || mode === "hybrid") && input.query) {
+            try {
+                const embedding = await this.deps.llm.embed(input.query, "query");
+                semNeighbors = await this.deps.store.semanticSearch(embedding.vector, limit * SEMANTIC_OVERFETCH);
+            }
+            catch (err) {
+                if (err instanceof LLMUnreachableError) {
+                    semError = "ollama_unreachable";
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
+        if (mode === "semantic" && semError) {
+            return { ...empty, modeUnavailable: semError };
+        }
+        // 2. Resolve ONLY the hit sessions — never the whole corpus. The
+        //    entity/kind filter is applied to the fetched hits; a filtered-out
+        //    session is absent from byId and is skipped during resolution.
+        const hitIds = uniqueIds(kwNeighbors, semNeighbors);
+        const hitSessions = await this.deps.store.getByIds(hitIds);
+        const filterArgs = {};
+        if (input.entity !== undefined)
+            filterArgs.entity = input.entity;
+        if (input.kind !== undefined)
+            filterArgs.kind = input.kind;
+        const byId = new Map(applyFilter(hitSessions, filterArgs).map((s) => [s.id, s]));
+        // 3. Build hits from the resolved sessions, preserving leg rank order.
+        const queryTokens = input.query
+            ? new Set(tokenSet(input.query))
+            : new Set();
+        const kwHits = [];
+        for (const n of kwNeighbors) {
+            const session = byId.get(n.sessionId);
+            if (!session)
+                continue;
+            kwHits.push({
+                session,
+                score: n.score,
+                matchedIn: keywordMatchFields(session, queryTokens),
+            });
+        }
+        const semHits = [];
+        for (const n of semNeighbors) {
+            const session = byId.get(n.sessionId);
+            if (!session)
+                continue;
+            semHits.push({ session, similarity: cosineFromL2(n.distance) });
+        }
+        // 4. Finalize per mode.
+        if (mode === "keyword") {
+            return finalize(input.query, entity, kind, mode, limit, kwHits.map(toKeywordHit));
+        }
+        if (mode === "semantic") {
+            return finalize(input.query, entity, kind, mode, limit, semHits.map(toSemanticHit));
+        }
+        const merged = mergeHybrid(kwHits, semHits);
+        const shape = detectQueryShape(input.query);
+        const forceIncluded = (shape.hasTemporal && shape.hasNamedEntity)
+            ? forceIncludeKeywordTop(merged, kwHits, limit)
+            : merged;
+        const result = finalize(input.query, entity, kind, mode, limit, forceIncluded);
+        return semError ? { ...result, modeUnavailable: semError } : result;
+    }
+}
+function uniqueIds(kw, sem) {
+    const ids = new Set();
+    for (const n of kw)
+        ids.add(n.sessionId);
+    for (const n of sem)
+        ids.add(n.sessionId);
+    return [...ids];
+}
+/**
+ * Reciprocal Rank Fusion across the keyword + semantic legs.
+ *
+ * matchScore = Σ 1/(RRF_K + rank_i) for each retriever the session appears in.
+ * A session at rank 1 in both retrievers therefore scores ~0.0328 (the max
+ * possible with two retrievers at k=60); a session at rank 1 in one
+ * retriever and absent from the other scores ~0.0164.
+ *
+ * keywordScore and semanticScore stay populated as min-max normalized
+ * informational values so the UI can show "how strong was each leg" —
+ * they're no longer used to compute matchScore.
+ */
+function mergeHybrid(kwHits, semHits) {
+    const maxKw = Math.max(1, ...kwHits.map((h) => h.score));
+    const maxSem = Math.max(1, ...semHits.map((h) => h.similarity));
+    const kwRank = new Map();
+    kwHits.forEach((h, i) => kwRank.set(h.session.id, i + 1));
+    const semRank = new Map();
+    semHits.forEach((h, i) => semRank.set(h.session.id, i + 1));
+    const kwMap = new Map(kwHits.map((h) => [h.session.id, h]));
+    const semMap = new Map(semHits.map((h) => [h.session.id, h]));
+    const allIds = new Set([...kwMap.keys(), ...semMap.keys()]);
+    const rows = [];
+    for (const id of allIds) {
+        const kw = kwMap.get(id);
+        const sem = semMap.get(id);
+        const session = (kw ?? sem).session;
+        const kRank = kwRank.get(id);
+        const sRank = semRank.get(id);
+        const rrf = (kRank !== undefined ? 1 / (RRF_K + kRank) : 0) +
+            (sRank !== undefined ? 1 / (RRF_K + sRank) : 0);
+        const matchedIn = uniqueFields(kw?.matchedIn ?? [], sem ? ["semantic"] : []);
+        rows.push({
+            ...sessionHitFields(session),
+            matchScore: round4(rrf),
+            matchedIn,
+            keywordScore: kw ? round4(kw.score / maxKw) : 0,
+            semanticScore: sem ? round4(sem.similarity / maxSem) : 0,
+        });
+    }
+    rows.sort((a, b) => b.matchScore - a.matchScore);
+    return rows;
+}
+/**
+ * Force-include the keyword-leg rank-1 session into the merged top-`limit`
+ * result. Only invoked when the query shape (temporal + named entity)
+ * indicates a Mode A pattern where pure RRF is known to demote keyword
+ * winners (see query-shape.ts for diagnosis). If the rank-1 keyword session
+ * is already in the limited top-N, no change. Otherwise it's inserted at
+ * position `limit - 1`, displacing the lowest-confidence merged hit.
+ */
+function forceIncludeKeywordTop(merged, kwHits, limit) {
+    if (kwHits.length === 0 || merged.length === 0)
+        return merged;
+    const topId = kwHits[0].session.id;
+    const top = merged.slice(0, limit);
+    if (top.some((h) => h.id === topId))
+        return merged;
+    const forcedHit = merged.find((h) => h.id === topId);
+    if (!forcedHit)
+        return merged;
+    const kept = top.slice(0, Math.max(0, limit - 1));
+    const tail = merged.slice(limit);
+    return [...kept, forcedHit, ...tail];
+}
+function toKeywordHit(h) {
+    return {
+        ...sessionHitFields(h.session),
+        matchScore: h.score,
+        matchedIn: h.matchedIn,
+    };
+}
+function toSemanticHit(h) {
+    return {
+        ...sessionHitFields(h.session),
+        matchScore: h.similarity,
+        matchedIn: ["semantic"],
+    };
+}
+function sessionHitFields(s) {
+    return {
+        id: s.id,
+        startedAt: s.startedAt,
+        label: s.label,
+        summary: s.summary,
+        entities: s.entities,
+        decisions: s.decisions,
+        open: s.open,
+        status: s.status,
+    };
+}
+function finalize(query, entity, kind, mode, limit, hits) {
+    return {
+        query,
+        entity,
+        kind,
+        mode,
+        limit,
+        total: hits.length,
+        results: hits.slice(0, limit),
+    };
+}
+function clampLimit(limit) {
+    const n = limit ?? DEFAULT_LIMIT;
+    if (Number.isNaN(n) || n < 1)
+        return 1;
+    return Math.min(MAX_LIMIT, Math.trunc(n));
+}
+function cosineFromL2(distance) {
+    // session_embeddings stores unit-normalized vectors. For unit vectors,
+    // cos_sim = 1 - L2^2 / 2. Mirrors recall.py:_run_semantic.
+    const cos = 1 - (distance * distance) / 2;
+    return round4(Math.max(-1, Math.min(1, cos)));
+}
+function round4(value) {
+    return Math.round(value * 10_000) / 10_000;
+}
+function uniqueFields(a, b) {
+    const seen = new Set();
+    const out = [];
+    for (const f of [...a, ...b]) {
+        if (!seen.has(f)) {
+            seen.add(f);
+            out.push(f);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=recall-service.js.map

package/dist/core/recall/recall-service.js.map

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

package/dist/core/recall/recent-log.d.ts

@@ -0,0 +1,16 @@
+/**
+ * recentLog — tail the query log for the /live observability panel.
+ * Returns the last N entries in chronological order (most recent first).
+ */
+export interface RecentLogEntry {
+    readonly ts: string;
+    readonly source: string;
+    readonly query: string | null;
+    readonly entity: string | null;
+    readonly kind: string | null;
+    readonly mode: string;
+    readonly limit: number;
+    readonly nResults: number;
+    readonly returnedIds: ReadonlyArray<string>;
+}
+export declare function recentQueryLog(limit: number, logPath?: string): RecentLogEntry[];

package/dist/core/recall/recent-log.js

@@ -0,0 +1,46 @@
+/**
+ * recentLog — tail the query log for the /live observability panel.
+ * Returns the last N entries in chronological order (most recent first).
+ */
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function defaultLogPath() {
+    return process.env["NLM_QUERY_LOG"] ?? join(homedir(), ".nlm", "query_log.jsonl");
+}
+const TAIL_BYTES = 256 * 1024;
+export function recentQueryLog(limit, logPath = defaultLogPath()) {
+    if (!existsSync(logPath))
+        return [];
+    const size = statSync(logPath).size;
+    const start = Math.max(0, size - TAIL_BYTES);
+    const tail = readFileSync(logPath, { encoding: "utf8" }).slice(start);
+    const entries = [];
+    for (const line of tail.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const raw = JSON.parse(trimmed);
+            entries.push({
+                ts: typeof raw["ts"] === "string" ? raw["ts"] : "",
+                source: typeof raw["source"] === "string" ? raw["source"] : "unknown",
+                query: typeof raw["query"] === "string" ? raw["query"] : null,
+                entity: typeof raw["entity"] === "string" ? raw["entity"] : null,
+                kind: typeof raw["kind"] === "string" ? raw["kind"] : null,
+                mode: typeof raw["mode"] === "string" ? raw["mode"] : "keyword",
+                limit: typeof raw["limit"] === "number" ? raw["limit"] : 0,
+                nResults: typeof raw["n_results"] === "number" ? raw["n_results"] : 0,
+                returnedIds: Array.isArray(raw["returned_ids"])
+                    ? raw["returned_ids"].filter((x) => typeof x === "string")
+                    : [],
+            });
+        }
+        catch {
+            continue;
+        }
+    }
+    entries.sort((a, b) => b.ts.localeCompare(a.ts));
+    return entries.slice(0, limit);
+}
+//# sourceMappingURL=recent-log.js.map

package/dist/core/recall/recent-log.js.map

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

package/dist/core/recall/tokenize.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tokenizer mirrors recall.py:_TOKEN_RE. Identical regex, lowercase normalize.
+ * Pure function. The keyword scorer's parity with the Python implementation
+ * starts here.
+ */
+export declare function tokenize(text: string | null | undefined): ReadonlyArray<string>;
+export declare function tokenSet(text: string | null | undefined): Set<string>;

package/dist/core/recall/tokenize.js

@@ -0,0 +1,18 @@
+/**
+ * Tokenizer mirrors recall.py:_TOKEN_RE. Identical regex, lowercase normalize.
+ * Pure function. The keyword scorer's parity with the Python implementation
+ * starts here.
+ */
+const TOKEN_PATTERN = /[A-Za-z0-9][A-Za-z0-9_.-]*/g;
+export function tokenize(text) {
+    if (!text)
+        return [];
+    const matches = text.match(TOKEN_PATTERN);
+    if (!matches)
+        return [];
+    return matches.map((t) => t.toLowerCase());
+}
+export function tokenSet(text) {
+    return new Set(tokenize(text));
+}
+//# sourceMappingURL=tokenize.js.map

package/dist/core/recall/tokenize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenize.js","sourceRoot":"","sources":["../../../src/core/recall/tokenize.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,aAAa,GAAG,6BAA6B,CAAC;AAEpD,MAAM,UAAU,QAAQ,CAAC,IAA+B;IACtD,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAC1C,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAA+B;IACtD,OAAO,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;AACjC,CAAC"}

package/dist/core/recall/useful-scan.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ */
+export interface UsefulHitEntry {
+    readonly ts: string;
+    readonly source: "hook";
+    readonly conversationId: string;
+    readonly returnedIds: ReadonlyArray<string>;
+    readonly useful: boolean | null;
+    readonly matchedId: string | null;
+    readonly scannedAt: string;
+}
+export interface ScanResult {
+    readonly total: number;
+    readonly measurable: number;
+    readonly useful: number;
+    readonly appended: number;
+}
+export declare function defaultUsefulHitLogPath(): string;
+export declare function isProbe(promptPreview: string): boolean;
+/**
+ * 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 declare function extractAssistantTurnsAfter(transcriptPath: string, afterTs: number, limit: number): ReadonlyArray<string>;
+export declare function findMatchedId(ids: ReadonlyArray<string>, turns: ReadonlyArray<string>): string | null;
+export declare function scanUsefulHits(opts: {
+    days?: number;
+    hookLogPath?: string;
+    usefulHitLogPath?: string;
+    transcriptsDir?: string;
+    dryRun?: boolean;
+}): Promise<ScanResult>;
+/**
+ * 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 declare function readUsefulHitRate(usefulHitLogPath?: string, days?: number): Promise<number | null>;