nlm-memory 0.5.21 → 0.5.22

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

@@ -0,0 +1,47 @@
+/**
+ * Append-only JSONL miss log. One line per session the agent explicitly
+ * fetched or cited but which the hook's pre-prompt recall never surfaced
+ * in this conversation. Source: Stop hook's miss-detection pass (spec E).
+ *
+ * Default path ~/.nlm/miss-log.jsonl, overridable via NLM_MISS_LOG.
+ * Disable emission entirely with NLM_MISS_LOG_ENABLED=0 — used by
+ * deployments that want recall but not telemetry. Telemetry path — never
+ * raises; failure to write is silently swallowed.
+ */
+export type MissKind = "get_session" | "cite_session";
+export interface MissEntry {
+    readonly conversationId: string;
+    readonly missedId: string;
+    readonly kind: MissKind;
+    /**
+     * Count of how many sessions WERE surfaced this conversation. Helps
+     * distinguish "hook never fired" (surfacedCount=0) from "hook fired but
+     * missed this one" (surfacedCount>0). Aggregation can filter accordingly.
+     */
+    readonly surfacedCount: number;
+}
+export interface MissStats {
+    readonly days: number;
+    readonly total: number;
+    readonly distinctIds: number;
+    /** Top missed sessions ordered by miss count, with diagnostic context. */
+    readonly topIds: ReadonlyArray<{
+        readonly id: string;
+        readonly count: number;
+        readonly conversations: number;
+    }>;
+    readonly logPresent: boolean;
+}
+export declare function appendMiss(entry: MissEntry, logPath?: string): Promise<void>;
+/**
+ * Append multiple misses in one call. Each gets the same timestamp.
+ * Quieter than appendMiss × N when several misses fire in a single Stop
+ * hook invocation (which is the common case).
+ */
+export declare function appendMisses(entries: ReadonlyArray<MissEntry>, logPath?: string): Promise<void>;
+/**
+ * Read the miss log and aggregate by missedId. Used by the `nlm misses`
+ * CLI. Days filter applied at parse time. Bad lines (non-JSON or missing
+ * fields) are skipped silently.
+ */
+export declare function missStats(days: number, logPath?: string): Promise<MissStats>;

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

@@ -0,0 +1,112 @@
+/**
+ * Append-only JSONL miss log. One line per session the agent explicitly
+ * fetched or cited but which the hook's pre-prompt recall never surfaced
+ * in this conversation. Source: Stop hook's miss-detection pass (spec E).
+ *
+ * Default path ~/.nlm/miss-log.jsonl, overridable via NLM_MISS_LOG.
+ * Disable emission entirely with NLM_MISS_LOG_ENABLED=0 — used by
+ * deployments that want recall but not telemetry. Telemetry path — never
+ * raises; failure to write is silently swallowed.
+ */
+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_MISS_LOG"] ?? join(homedir(), ".nlm", "miss-log.jsonl");
+}
+function isEnabled() {
+    const raw = process.env["NLM_MISS_LOG_ENABLED"];
+    if (raw === undefined)
+        return true;
+    return raw !== "0" && raw.toLowerCase() !== "false";
+}
+export async function appendMiss(entry, logPath) {
+    if (!isEnabled())
+        return;
+    const path = logPath ?? defaultLogPath();
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        const line = `${JSON.stringify({
+            ts: new Date().toISOString(),
+            ...entry,
+        })}\n`;
+        await appendFile(path, line, "utf8");
+    }
+    catch {
+        // Telemetry must never break recall.
+    }
+}
+/**
+ * Append multiple misses in one call. Each gets the same timestamp.
+ * Quieter than appendMiss × N when several misses fire in a single Stop
+ * hook invocation (which is the common case).
+ */
+export async function appendMisses(entries, logPath) {
+    if (!isEnabled())
+        return;
+    if (entries.length === 0)
+        return;
+    const path = logPath ?? defaultLogPath();
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        const ts = new Date().toISOString();
+        const block = entries.map((e) => `${JSON.stringify({ ts, ...e })}\n`).join("");
+        await appendFile(path, block, "utf8");
+    }
+    catch {
+        // Swallow.
+    }
+}
+/**
+ * Read the miss log and aggregate by missedId. Used by the `nlm misses`
+ * CLI. Days filter applied at parse time. Bad lines (non-JSON or missing
+ * fields) are skipped silently.
+ */
+export async function missStats(days, logPath) {
+    const path = logPath ?? defaultLogPath();
+    try {
+        await stat(path);
+    }
+    catch {
+        return { days, total: 0, distinctIds: 0, topIds: [], logPresent: false };
+    }
+    const raw = await readFile(path, "utf8");
+    const cutoff = Date.now() - days * 86_400_000;
+    const counts = new Map();
+    let total = 0;
+    for (const line of raw.split("\n")) {
+        if (!line)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!parsed.ts || !parsed.missedId || !parsed.conversationId)
+            continue;
+        if (Date.parse(parsed.ts) < cutoff)
+            continue;
+        total += 1;
+        let bucket = counts.get(parsed.missedId);
+        if (!bucket) {
+            bucket = { count: 0, convs: new Set() };
+            counts.set(parsed.missedId, bucket);
+        }
+        bucket.count += 1;
+        bucket.convs.add(parsed.conversationId);
+    }
+    const topIds = [...counts.entries()]
+        .map(([id, b]) => ({ id, count: b.count, conversations: b.convs.size }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 20);
+    return {
+        days,
+        total,
+        distinctIds: counts.size,
+        topIds,
+        logPresent: true,
+    };
+}
+//# sourceMappingURL=miss-log.js.map

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

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

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

@@ -11,6 +11,9 @@
 import type { RecallKindFilter, RecallMode } from "../../shared/types.js";
 export interface LogEntry {
     readonly source: string;
+    /** Calling agent runtime (claude-code / hermes / pi.dev / codex / etc).
+     *  Logged when the caller passes x-recall-runtime; null for legacy entries. */
+    readonly runtime: string | null;
     readonly query: string | null;
     readonly entity: string | null;
     readonly kind: RecallKindFilter | null;

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

@@ -20,6 +20,7 @@ export async function logQuery(entry, logPath = defaultLogPath()) {
         const payload = {
             ts: new Date().toISOString(),
             source: entry.source,
+            runtime: entry.runtime,
             query: entry.query,
             entity: entry.entity,
             kind: entry.kind,

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

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

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

@@ -0,0 +1,52 @@
+/**
+ * Recency weighting for recall scoring.
+ *
+ * Multiplies each RecallHit's matchScore by an age-decay factor so identical-
+ * relevance sessions sort newer-first. The factor is exponential half-life:
+ *
+ *     f(age_days) = max(FLOOR, 2 ^ (-age_days / half_life_days))
+ *
+ * Default half-life: 180 days (6 months). A 180-day-old session scores 0.5×,
+ * a 1-year-old session scores 0.25×, an 18-month-old session scores ~0.13×.
+ *
+ * Default floor: 0.25. A truly-relevant ancient session never drops below
+ * a quarter of its raw score — so age alone can't push it out of top results
+ * if the keyword/semantic signal is strong enough.
+ *
+ * Configuration:
+ *   NLM_RECALL_DECAY_HALF_LIFE_DAYS  — override the half-life. Set to 0 to
+ *                                       disable decay entirely (returns 1.0).
+ *   NLM_RECALL_DECAY_FLOOR           — override the floor (0.0 - 1.0 range).
+ *
+ * Env vars are read once at module load and cached. To change at runtime,
+ * call resetRecencyConfigForTest() (test-only) and reimport.
+ *
+ * Design notes:
+ *   - Applied once at finalize() time in recall-service.ts, after per-mode
+ *     scoring but before the limit slice. Single call-site covers keyword,
+ *     semantic, and hybrid modes uniformly.
+ *   - Future startedAt (clock skew) is clamped to multiplier = 1.0.
+ *   - Missing/invalid startedAt returns 1.0 (treat as fresh — don't penalize
+ *     for data we don't have).
+ */
+interface RecencyConfig {
+    readonly halfLifeDays: number;
+    readonly floor: number;
+    readonly disabled: boolean;
+}
+/**
+ * Test-only: drop the cached config so the next call re-reads env vars.
+ */
+export declare function resetRecencyConfigForTest(): void;
+/**
+ * Return the multiplier in (0, 1] for a session whose ISO 8601 `startedAt`
+ * timestamp is given. `now` defaults to Date.now() and may be overridden
+ * for deterministic tests.
+ */
+export declare function recencyMultiplier(startedAt: string | null | undefined, now?: number): number;
+/**
+ * Read-only view of the active config. Exposed for diagnostics (e.g. the
+ * `/api/health` endpoint or operator-facing logs).
+ */
+export declare function getRecencyConfig(): RecencyConfig;
+export {};

package/dist/core/recall/recency.js

@@ -0,0 +1,98 @@
+/**
+ * Recency weighting for recall scoring.
+ *
+ * Multiplies each RecallHit's matchScore by an age-decay factor so identical-
+ * relevance sessions sort newer-first. The factor is exponential half-life:
+ *
+ *     f(age_days) = max(FLOOR, 2 ^ (-age_days / half_life_days))
+ *
+ * Default half-life: 180 days (6 months). A 180-day-old session scores 0.5×,
+ * a 1-year-old session scores 0.25×, an 18-month-old session scores ~0.13×.
+ *
+ * Default floor: 0.25. A truly-relevant ancient session never drops below
+ * a quarter of its raw score — so age alone can't push it out of top results
+ * if the keyword/semantic signal is strong enough.
+ *
+ * Configuration:
+ *   NLM_RECALL_DECAY_HALF_LIFE_DAYS  — override the half-life. Set to 0 to
+ *                                       disable decay entirely (returns 1.0).
+ *   NLM_RECALL_DECAY_FLOOR           — override the floor (0.0 - 1.0 range).
+ *
+ * Env vars are read once at module load and cached. To change at runtime,
+ * call resetRecencyConfigForTest() (test-only) and reimport.
+ *
+ * Design notes:
+ *   - Applied once at finalize() time in recall-service.ts, after per-mode
+ *     scoring but before the limit slice. Single call-site covers keyword,
+ *     semantic, and hybrid modes uniformly.
+ *   - Future startedAt (clock skew) is clamped to multiplier = 1.0.
+ *   - Missing/invalid startedAt returns 1.0 (treat as fresh — don't penalize
+ *     for data we don't have).
+ */
+const DEFAULT_HALF_LIFE_DAYS = 180;
+const DEFAULT_FLOOR = 0.25;
+const MS_PER_DAY = 86_400_000;
+let cached = null;
+function loadConfig() {
+    if (cached)
+        return cached;
+    const halfLifeRaw = process.env["NLM_RECALL_DECAY_HALF_LIFE_DAYS"];
+    const floorRaw = process.env["NLM_RECALL_DECAY_FLOOR"];
+    let halfLifeDays = DEFAULT_HALF_LIFE_DAYS;
+    let disabled = false;
+    if (halfLifeRaw !== undefined) {
+        const parsed = Number.parseFloat(halfLifeRaw);
+        if (Number.isFinite(parsed)) {
+            if (parsed <= 0) {
+                disabled = true;
+            }
+            else {
+                halfLifeDays = parsed;
+            }
+        }
+    }
+    let floor = DEFAULT_FLOOR;
+    if (floorRaw !== undefined) {
+        const parsed = Number.parseFloat(floorRaw);
+        if (Number.isFinite(parsed) && parsed >= 0 && parsed <= 1) {
+            floor = parsed;
+        }
+    }
+    cached = { halfLifeDays, floor, disabled };
+    return cached;
+}
+/**
+ * Test-only: drop the cached config so the next call re-reads env vars.
+ */
+export function resetRecencyConfigForTest() {
+    cached = null;
+}
+/**
+ * Return the multiplier in (0, 1] for a session whose ISO 8601 `startedAt`
+ * timestamp is given. `now` defaults to Date.now() and may be overridden
+ * for deterministic tests.
+ */
+export function recencyMultiplier(startedAt, now = Date.now()) {
+    const cfg = loadConfig();
+    if (cfg.disabled)
+        return 1.0;
+    if (!startedAt)
+        return 1.0;
+    const started = Date.parse(startedAt);
+    if (Number.isNaN(started))
+        return 1.0;
+    const ageMs = now - started;
+    if (ageMs <= 0)
+        return 1.0;
+    const ageDays = ageMs / MS_PER_DAY;
+    const raw = Math.pow(2, -ageDays / cfg.halfLifeDays);
+    return Math.max(cfg.floor, raw);
+}
+/**
+ * Read-only view of the active config. Exposed for diagnostics (e.g. the
+ * `/api/health` endpoint or operator-facing logs).
+ */
+export function getRecencyConfig() {
+    return loadConfig();
+}
+//# sourceMappingURL=recency.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recency.js","sourceRoot":"","sources":["../../../src/core/recall/recency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,sBAAsB,GAAG,GAAG,CAAC;AACnC,MAAM,aAAa,GAAG,IAAI,CAAC;AAC3B,MAAM,UAAU,GAAG,UAAU,CAAC;AAQ9B,IAAI,MAAM,GAAyB,IAAI,CAAC;AAExC,SAAS,UAAU;IACjB,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;IACnE,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;IAEvD,IAAI,YAAY,GAAG,sBAAsB,CAAC;IAC1C,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;QAC9C,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;gBAChB,QAAQ,GAAG,IAAI,CAAC;YAClB,CAAC;iBAAM,CAAC;gBACN,YAAY,GAAG,MAAM,CAAC;YACxB,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,KAAK,GAAG,aAAa,CAAC;IAC1B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAC3C,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;YAC1D,KAAK,GAAG,MAAM,CAAC;QACjB,CAAC;IACH,CAAC;IAED,MAAM,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IAC3C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB;IACvC,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAoC,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;IAC9F,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;IACzB,IAAI,GAAG,CAAC,QAAQ;QAAE,OAAO,GAAG,CAAC;IAC7B,IAAI,CAAC,SAAS;QAAE,OAAO,GAAG,CAAC;IAE3B,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACtC,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,GAAG,CAAC;IAEtC,MAAM,KAAK,GAAG,GAAG,GAAG,OAAO,CAAC;IAC5B,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,GAAG,CAAC;IAE3B,MAAM,OAAO,GAAG,KAAK,GAAG,UAAU,CAAC;IACnC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,OAAO,GAAG,GAAG,CAAC,YAAY,CAAC,CAAC;IACrD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC"}

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

@@ -5,6 +5,7 @@
 export interface RecentLogEntry {
     readonly ts: string;
     readonly source: string;
+    readonly runtime: string | null;
     readonly query: string | null;
     readonly entity: string | null;
     readonly kind: string | null;

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

@@ -25,6 +25,7 @@ export function recentQueryLog(limit, logPath = defaultLogPath()) {
             entries.push({
                 ts: typeof raw["ts"] === "string" ? raw["ts"] : "",
                 source: typeof raw["source"] === "string" ? raw["source"] : "unknown",
+                runtime: typeof raw["runtime"] === "string" ? raw["runtime"] : null,
                 query: typeof raw["query"] === "string" ? raw["query"] : null,
                 entity: typeof raw["entity"] === "string" ? raw["entity"] : null,
                 kind: typeof raw["kind"] === "string" ? raw["kind"] : null,

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

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

package/dist/core/recall/related-facts.d.ts

@@ -0,0 +1,30 @@
+/**
+ * pickRelatedFacts — Spec G.2 server-side helper that selects 3–5 current
+ * high-confidence facts about the entities in the top recall hits.
+ *
+ * Algorithm:
+ *   1. Walk top-N hits, collect a deduped entity set (cap entities so very
+ *      entity-rich sessions don't dominate).
+ *   2. For each entity, fetch its current (non-superseded) facts from
+ *      FactStore.list. Filter to confidence ≥ min.
+ *   3. Compute corroboration counts (Spec G.1) for all candidates in a
+ *      single batched query.
+ *   4. Filter to facts seen across ≥ MIN_CORROBORATION sessions — a fact
+ *      asserted by only one session isn't "known" yet for the purposes
+ *      of hook injection.
+ *   5. Sort by (corroborationCount DESC, confidence DESC) and take limit.
+ *
+ * Defaults are tunable via env vars (NLM_HOOK_FACT_LIMIT,
+ * NLM_HOOK_FACT_MIN_CORROBORATION, NLM_HOOK_FACT_MIN_CONFIDENCE) and any
+ * fail in the path returns an empty array so the pointer block degrades
+ * to the session-only format. This is a quality enhancement; never let
+ * it block recall.
+ */
+import type { FactStore } from "../../ports/fact-store.js";
+import type { RecallHit, RelatedFact } from "../../shared/types.js";
+export interface PickRelatedFactsOptions {
+    readonly limit?: number;
+    readonly minCorroboration?: number;
+    readonly minConfidence?: number;
+}
+export declare function pickRelatedFacts(hits: ReadonlyArray<RecallHit>, factStore: FactStore, opts?: PickRelatedFactsOptions): Promise<RelatedFact[]>;

package/dist/core/recall/related-facts.js

@@ -0,0 +1,134 @@
+/**
+ * pickRelatedFacts — Spec G.2 server-side helper that selects 3–5 current
+ * high-confidence facts about the entities in the top recall hits.
+ *
+ * Algorithm:
+ *   1. Walk top-N hits, collect a deduped entity set (cap entities so very
+ *      entity-rich sessions don't dominate).
+ *   2. For each entity, fetch its current (non-superseded) facts from
+ *      FactStore.list. Filter to confidence ≥ min.
+ *   3. Compute corroboration counts (Spec G.1) for all candidates in a
+ *      single batched query.
+ *   4. Filter to facts seen across ≥ MIN_CORROBORATION sessions — a fact
+ *      asserted by only one session isn't "known" yet for the purposes
+ *      of hook injection.
+ *   5. Sort by (corroborationCount DESC, confidence DESC) and take limit.
+ *
+ * Defaults are tunable via env vars (NLM_HOOK_FACT_LIMIT,
+ * NLM_HOOK_FACT_MIN_CORROBORATION, NLM_HOOK_FACT_MIN_CONFIDENCE) and any
+ * fail in the path returns an empty array so the pointer block degrades
+ * to the session-only format. This is a quality enhancement; never let
+ * it block recall.
+ */
+const DEFAULT_FACT_LIMIT = 5;
+const DEFAULT_MIN_CORROBORATION = 2;
+const DEFAULT_MIN_CONFIDENCE = 0.7;
+const TOP_HITS_FOR_ENTITY_SCAN = 5;
+const MAX_ENTITIES_TO_QUERY = 8;
+function readInt(envKey, fallback) {
+    const raw = process.env[envKey];
+    if (raw === undefined)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+function readFloat(envKey, fallback) {
+    const raw = process.env[envKey];
+    if (raw === undefined)
+        return fallback;
+    const parsed = Number.parseFloat(raw);
+    return Number.isFinite(parsed) && parsed >= 0 && parsed <= 1 ? parsed : fallback;
+}
+export async function pickRelatedFacts(hits, factStore, opts = {}) {
+    if (hits.length === 0)
+        return [];
+    const limit = opts.limit ?? readInt("NLM_HOOK_FACT_LIMIT", DEFAULT_FACT_LIMIT);
+    const minCorroboration = opts.minCorroboration ?? readInt("NLM_HOOK_FACT_MIN_CORROBORATION", DEFAULT_MIN_CORROBORATION);
+    const minConfidence = opts.minConfidence ?? readFloat("NLM_HOOK_FACT_MIN_CONFIDENCE", DEFAULT_MIN_CONFIDENCE);
+    if (limit <= 0)
+        return [];
+    try {
+        // 1. Collect entities from the top hits.
+        const entities = collectEntities(hits.slice(0, TOP_HITS_FOR_ENTITY_SCAN));
+        if (entities.length === 0)
+            return [];
+        // 2. Fetch current facts per entity. Parallelize to keep latency bounded.
+        const factLists = await Promise.all(entities.map((entity) => factStore.list({ subject: entity, includeSuperseded: false })));
+        // 3. Flatten, filter by confidence.
+        const candidates = [];
+        for (const list of factLists) {
+            for (const f of list) {
+                if (f.confidence >= minConfidence)
+                    candidates.push(f);
+            }
+        }
+        if (candidates.length === 0)
+            return [];
+        // 4. Batch-compute corroboration for all candidates.
+        const triples = candidates.map((f) => ({
+            subject: f.subject,
+            predicate: f.predicate,
+            value: f.value,
+        }));
+        const counts = await factStore.corroborationCounts(triples);
+        // 5. Build RelatedFact[], filter by minCorroboration, dedupe by
+        //    (subject, predicate) — only the most-corroborated value per pair
+        //    survives so we don't list "polysignal uses: duckdb" AND
+        //    "polysignal uses: postgres" as if both were current.
+        const byKey = new Map();
+        for (const f of candidates) {
+            const corrKey = `${f.subject} ${f.predicate} ${f.value}`;
+            const corroborationCount = counts.get(corrKey) ?? 1;
+            if (corroborationCount < minCorroboration)
+                continue;
+            const dedupeKey = `${f.subject} ${f.predicate}`;
+            const existing = byKey.get(dedupeKey);
+            if (!existing ||
+                corroborationCount > existing.corroborationCount ||
+                (corroborationCount === existing.corroborationCount && f.confidence > existing.confidence)) {
+                byKey.set(dedupeKey, {
+                    subject: f.subject,
+                    predicate: f.predicate,
+                    value: f.value,
+                    corroborationCount,
+                    confidence: f.confidence,
+                });
+            }
+        }
+        const sorted = [...byKey.values()].sort((a, b) => {
+            if (b.corroborationCount !== a.corroborationCount) {
+                return b.corroborationCount - a.corroborationCount;
+            }
+            return b.confidence - a.confidence;
+        });
+        return sorted.slice(0, limit).map((r) => ({
+            subject: r.subject,
+            predicate: r.predicate,
+            value: r.value,
+            corroborationCount: r.corroborationCount,
+        }));
+    }
+    catch {
+        // Fail-open: empty array means the pointer block renders session-only.
+        return [];
+    }
+}
+function collectEntities(hits) {
+    // Order matters: earlier hits contribute first so the top-ranked
+    // session's entities are most likely to make the cut.
+    const seen = new Set();
+    const out = [];
+    for (const hit of hits) {
+        for (const ent of hit.entities) {
+            const trimmed = ent.trim();
+            if (!trimmed || seen.has(trimmed))
+                continue;
+            seen.add(trimmed);
+            out.push(trimmed);
+            if (out.length >= MAX_ENTITIES_TO_QUERY)
+                return out;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=related-facts.js.map

package/dist/core/recall/related-facts.js.map

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

package/dist/core/recall/rewrite-cache.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Bounded in-memory TTL cache for query rewrites.
+ *
+ * Same raw query within the TTL window reuses the prior LLM rewrite —
+ * avoids burning ~hundreds-of-ms per repeated call when an agent hammers
+ * `recall_sessions` with slightly different phrasings of the same intent.
+ *
+ * Bounded by max entries (LRU eviction) AND TTL (lazy expiry on read).
+ * No background timer — entries are checked at read time and dropped if
+ * expired, which keeps the cache zero-cost when idle.
+ */
+import type { RewriteResult } from "../../ports/llm-client.js";
+export declare class RewriteCache {
+    private readonly store;
+    private readonly maxEntries;
+    private readonly ttlMs;
+    constructor(opts?: {
+        readonly maxEntries?: number;
+        readonly ttlMs?: number;
+    });
+    get(rawQuery: string, now?: number): RewriteResult | null;
+    set(rawQuery: string, result: RewriteResult, now?: number): void;
+    size(): number;
+    clear(): void;
+}

package/dist/core/recall/rewrite-cache.js

@@ -0,0 +1,60 @@
+/**
+ * Bounded in-memory TTL cache for query rewrites.
+ *
+ * Same raw query within the TTL window reuses the prior LLM rewrite —
+ * avoids burning ~hundreds-of-ms per repeated call when an agent hammers
+ * `recall_sessions` with slightly different phrasings of the same intent.
+ *
+ * Bounded by max entries (LRU eviction) AND TTL (lazy expiry on read).
+ * No background timer — entries are checked at read time and dropped if
+ * expired, which keeps the cache zero-cost when idle.
+ */
+const DEFAULT_MAX_ENTRIES = 200;
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+export class RewriteCache {
+    store = new Map();
+    maxEntries;
+    ttlMs;
+    constructor(opts = {}) {
+        this.maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+    }
+    get(rawQuery, now = Date.now()) {
+        const key = normalize(rawQuery);
+        const entry = this.store.get(key);
+        if (!entry)
+            return null;
+        if (entry.expiresAt <= now) {
+            this.store.delete(key);
+            return null;
+        }
+        // LRU touch: re-insert so this key is now the most recent.
+        this.store.delete(key);
+        this.store.set(key, entry);
+        return entry.result;
+    }
+    set(rawQuery, result, now = Date.now()) {
+        const key = normalize(rawQuery);
+        if (this.store.has(key))
+            this.store.delete(key);
+        this.store.set(key, { result, expiresAt: now + this.ttlMs });
+        while (this.store.size > this.maxEntries) {
+            const oldestKey = this.store.keys().next().value;
+            if (oldestKey === undefined)
+                break;
+            this.store.delete(oldestKey);
+        }
+    }
+    size() {
+        return this.store.size;
+    }
+    clear() {
+        this.store.clear();
+    }
+}
+function normalize(s) {
+    // Case-insensitive, whitespace-collapsed key — "PGVector  thing" hits the
+    // same cache slot as "pgvector thing".
+    return s.trim().toLowerCase().replace(/\s+/g, " ");
+}
+//# sourceMappingURL=rewrite-cache.js.map