@vinaes/succ 1.4.0 → 1.5.42

package/dist/lib/reranker.js

@@ -0,0 +1,294 @@
+/**
+ * Cross-encoder reranker for search result post-processing.
+ *
+ * Uses an ONNX cross-encoder model (ms-marco-MiniLM-L6-v2) to score
+ * (query, document) pairs for relevance. Applied after hybrid search
+ * (BM25 + vector + RRF) to improve precision.
+ *
+ * Architecture: singleton session, lazy-loaded on first use, auto-disposed on cleanup.
+ */
+import * as ort from 'onnxruntime-node';
+import { resolveModelPath } from './ort-session.js';
+import { detectExecutionProvider } from './ort-provider.js';
+import { getConfig } from './config.js';
+import { logInfo, logWarn } from './fault-logger.js';
+/** Default cross-encoder model — small, fast, good quality */
+const DEFAULT_RERANKER_MODEL = 'cross-encoder/ms-marco-MiniLM-L6-v2';
+/** Max sequence length for cross-encoder input (query + doc tokens) */
+const MAX_SEQ_LENGTH = 512;
+/** Batch size for cross-encoder inference (limits memory usage) */
+const RERANKER_BATCH_SIZE = 16;
+// Singleton session
+let rerankerSession = null;
+let rerankerTokenizer = null;
+let rerankerInitializing = null;
+let rerankerInitFailed = false; // Don't retry after initialization failure
+let rerankerShuttingDown = false; // Guard against races between init and cleanup
+/**
+ * Initialize the cross-encoder reranker session.
+ * Uses same model resolution + provider detection as embedding pipeline.
+ */
+async function initReranker() {
+    if (rerankerShuttingDown)
+        throw new Error('Reranker is shutting down');
+    if (rerankerSession && rerankerTokenizer)
+        return;
+    if (rerankerInitFailed)
+        throw new Error('Reranker initialization previously failed');
+    // Prevent concurrent initialization
+    if (rerankerInitializing) {
+        await rerankerInitializing;
+        return;
+    }
+    rerankerInitializing = (async () => {
+        try {
+            const config = getConfig();
+            const model = config.llm?.reranker?.model ?? DEFAULT_RERANKER_MODEL;
+            logInfo('reranker', `Loading cross-encoder model: ${model}`);
+            // Load tokenizer
+            const { AutoTokenizer } = await import('@huggingface/transformers');
+            rerankerTokenizer = await AutoTokenizer.from_pretrained(model);
+            // Resolve model path (same cache locations as embeddings)
+            const modelPath = await resolveModelPath(model);
+            // Create session with GPU fallback
+            const providerResult = detectExecutionProvider(process.platform, {
+                gpu_enabled: config.gpu_enabled,
+                gpu_device: config.gpu_device,
+            });
+            for (const provider of providerResult.fallbackChain) {
+                try {
+                    rerankerSession = await ort.InferenceSession.create(modelPath, {
+                        executionProviders: [provider],
+                        interOpNumThreads: 1,
+                        intraOpNumThreads: 2,
+                    });
+                    logInfo('reranker', `Cross-encoder loaded with provider: ${provider}`);
+                    return;
+                }
+                catch (err) {
+                    logWarn('reranker', `Provider ${provider} failed, trying next`, {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            throw new Error(`Failed to create reranker session with any provider: ${providerResult.fallbackChain.join(', ')}`);
+        }
+        catch (error) {
+            rerankerSession = null;
+            rerankerTokenizer = null;
+            rerankerInitFailed = true;
+            throw error;
+        }
+        finally {
+            rerankerInitializing = null;
+        }
+    })();
+    await rerankerInitializing;
+}
+/**
+ * Score a batch of (query, document) pairs using the cross-encoder.
+ * Returns relevance scores (higher = more relevant).
+ *
+ * Cross-encoders output logits; we apply sigmoid to get 0-1 scores.
+ */
+async function scorePairs(query, documents) {
+    if (documents.length === 0)
+        return [];
+    await initReranker();
+    if (!rerankerSession || !rerankerTokenizer) {
+        throw new Error('Reranker not initialized');
+    }
+    const allScores = [];
+    // Process in batches to limit memory usage
+    for (let i = 0; i < documents.length; i += RERANKER_BATCH_SIZE) {
+        const batch = documents.slice(i, i + RERANKER_BATCH_SIZE);
+        const batchScores = await scoreBatch(query, batch);
+        allScores.push(...batchScores);
+    }
+    return allScores;
+}
+/**
+ * Score a single batch of (query, document) pairs.
+ */
+async function scoreBatch(query, documents) {
+    // Cross-encoders take (query, document) as a text pair input.
+    // The tokenizer encodes them as [CLS] query [SEP] document [SEP].
+    const pairs = documents.map((doc) => [query, doc]);
+    // Tokenize all pairs
+    const encoded = rerankerTokenizer(pairs, {
+        padding: true,
+        truncation: true,
+        max_length: MAX_SEQ_LENGTH,
+        return_tensors: false,
+    });
+    const batchSize = documents.length;
+    const seqLen = encoded.input_ids.dims ? encoded.input_ids.dims[1] : encoded.input_ids[0].length;
+    // Flatten for ORT tensors
+    const flatInputIds = encoded.input_ids.dims
+        ? encoded.input_ids.data
+        : new BigInt64Array(encoded.input_ids.flat().map((v) => BigInt(v)));
+    const flatAttentionMask = encoded.attention_mask.dims
+        ? encoded.attention_mask.data
+        : new BigInt64Array(encoded.attention_mask.flat().map((v) => BigInt(v)));
+    const inputIdsTensor = new ort.Tensor('int64', toBigInt64(flatInputIds, batchSize * seqLen), [
+        batchSize,
+        seqLen,
+    ]);
+    const attentionMaskTensor = new ort.Tensor('int64', toBigInt64(flatAttentionMask, batchSize * seqLen), [batchSize, seqLen]);
+    const feeds = {
+        input_ids: inputIdsTensor,
+        attention_mask: attentionMaskTensor,
+    };
+    // Some models need token_type_ids (0 for query, 1 for document)
+    if (rerankerSession.inputNames.includes('token_type_ids')) {
+        let tokenTypeData;
+        if (encoded.token_type_ids) {
+            const flatTokenTypes = encoded.token_type_ids.dims
+                ? encoded.token_type_ids.data
+                : new BigInt64Array(encoded.token_type_ids.flat().map((v) => BigInt(v)));
+            tokenTypeData = toBigInt64(flatTokenTypes, batchSize * seqLen);
+        }
+        else {
+            tokenTypeData = new BigInt64Array(batchSize * seqLen);
+        }
+        feeds.token_type_ids = new ort.Tensor('int64', tokenTypeData, [batchSize, seqLen]);
+    }
+    // Run inference
+    const results = await rerankerSession.run(feeds);
+    // Cross-encoder outputs logits (usually shape [batch, 1] or [batch])
+    const outputKey = rerankerSession.outputNames[0];
+    const output = results[outputKey];
+    const logits = output.data;
+    // Apply sigmoid to convert logits to 0-1 relevance scores
+    const scores = [];
+    for (let i = 0; i < batchSize; i++) {
+        const logit = logits[i];
+        scores.push(sigmoid(logit));
+    }
+    return scores;
+}
+/**
+ * Rerank hybrid search results using cross-encoder scoring.
+ *
+ * Takes existing search results (from BM25 + vector + RRF) and re-scores
+ * them using a cross-encoder model that sees both query and document together.
+ *
+ * @param query - Original search query
+ * @param results - Hybrid search results to rerank
+ * @param topK - Number of top results to return (default: results.length)
+ * @returns Reranked results with updated similarity scores
+ */
+export async function rerank(query, results, topK) {
+    if (results.length === 0)
+        return [];
+    // Normalize topK: must be a positive integer, clamped to results length.
+    const safeTopK = topK !== undefined && Number.isFinite(topK) && topK > 0
+        ? Math.min(Math.floor(topK), results.length)
+        : undefined;
+    // Helper: apply topK slice consistently on every return path.
+    const applyTopK = (arr) => (safeTopK !== undefined ? arr.slice(0, safeTopK) : arr);
+    if (results.length === 1)
+        return applyTopK(results);
+    const config = getConfig();
+    const rerankerConfig = config.llm?.reranker;
+    // Check if reranking is enabled
+    if (rerankerConfig?.enabled === false) {
+        return applyTopK(results);
+    }
+    // Don't rerank if too few results (overhead not worth it)
+    const minResults = rerankerConfig?.min_results ?? 3;
+    if (results.length < minResults) {
+        return applyTopK(results);
+    }
+    try {
+        // Prepare document texts for scoring
+        // Truncate long documents to save compute
+        const rawMaxDocChars = rerankerConfig?.max_doc_chars ?? 1000;
+        const maxDocChars = Number.isFinite(rawMaxDocChars) && rawMaxDocChars > 0 ? Math.floor(rawMaxDocChars) : 1000;
+        const docTexts = results.map((r) => {
+            const text = r.content.slice(0, maxDocChars);
+            // Include symbol metadata for code results
+            if (r.symbol_name) {
+                return `${r.symbol_name}${r.signature ? ': ' + r.signature : ''}\n${text}`;
+            }
+            return text;
+        });
+        // Score all (query, document) pairs
+        const scores = await scorePairs(query, docTexts);
+        // Combine with original scores:
+        // reranker_weight * cross_encoder_score + (1 - reranker_weight) * original_score
+        const rawWeight = rerankerConfig?.weight ?? 0.7;
+        const weight = Number.isFinite(rawWeight) ? Math.max(0, Math.min(1, rawWeight)) : 0.7;
+        const reranked = results.map((result, i) => ({
+            ...result,
+            _originalSimilarity: result.similarity,
+            similarity: weight * scores[i] + (1 - weight) * result.similarity,
+        }));
+        // Sort by new combined score
+        reranked.sort((a, b) => b.similarity - a.similarity);
+        // Return top-K
+        return applyTopK(reranked);
+    }
+    catch (error) {
+        // Graceful degradation: return original results if reranker fails
+        logWarn('reranker', `Cross-encoder reranking failed, returning original results: ${error instanceof Error ? error.message : String(error)}`);
+        return applyTopK(results);
+    }
+}
+/**
+ * Check if the reranker is available and enabled.
+ */
+export function isRerankerEnabled() {
+    const config = getConfig();
+    return config.llm?.reranker?.enabled !== false;
+}
+/**
+ * Cleanup reranker session to free memory.
+ *
+ * Sets a shutdown guard first, then awaits any in-flight initialization before
+ * releasing ONNX resources. This prevents a race where cleanup returns while
+ * initReranker() is still allocating the session (which would then leak).
+ */
+export async function cleanupReranker() {
+    rerankerShuttingDown = true;
+    // Wait for any in-flight init to finish before releasing resources.
+    if (rerankerInitializing) {
+        try {
+            await rerankerInitializing;
+        }
+        catch {
+            // Init may have failed — that's fine, we're cleaning up anyway
+            logWarn('reranker', 'Reranker init failed during shutdown — continuing cleanup');
+        }
+    }
+    if (rerankerSession) {
+        try {
+            await rerankerSession.release();
+        }
+        catch (err) {
+            logWarn('reranker', err instanceof Error ? err.message : 'Reranker session release failed');
+        }
+        rerankerSession = null;
+    }
+    rerankerTokenizer = null;
+    rerankerInitializing = null;
+    rerankerInitFailed = false;
+    rerankerShuttingDown = false;
+}
+// ============================================================================
+// Utilities
+// ============================================================================
+function sigmoid(x) {
+    return 1 / (1 + Math.exp(-x));
+}
+function toBigInt64(data, expectedLength) {
+    if (data instanceof BigInt64Array && data.length === expectedLength) {
+        return data;
+    }
+    const arr = new BigInt64Array(expectedLength);
+    for (let i = 0; i < expectedLength && i < data.length; i++) {
+        arr[i] = typeof data[i] === 'bigint' ? data[i] : BigInt(Number(data[i]));
+    }
+    return arr;
+}
+//# sourceMappingURL=reranker.js.map

package/dist/lib/reranker.js.map

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

package/dist/lib/retrieval-feedback.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Retrieval Feedback Loops — track whether recalled memories were useful.
+ *
+ * Records recall events and uses historical usefulness to boost/decay
+ * memory retrieval scores. Self-improving retrieval over time.
+ *
+ * Inspired by Cognee's ~90% accuracy from feedback loops.
+ */
+export interface RecallEvent {
+    id: number;
+    memory_id: number;
+    query: string;
+    was_used: boolean;
+    rank_position: number | null;
+    similarity_score: number | null;
+    created_at: string;
+}
+export interface RecallStats {
+    memoryId: number;
+    totalRecalls: number;
+    timesUsed: number;
+    timesIgnored: number;
+    useRate: number;
+    avgRankWhenUsed: number | null;
+    avgRankWhenIgnored: number | null;
+    lastRecalled: string | null;
+    /** Boost factor: >1 means boost, <1 means decay */
+    boostFactor: number;
+}
+export interface RecallSummary {
+    totalEvents: number;
+    uniqueMemories: number;
+    overallUseRate: number;
+    neverUsedMemories: number;
+    topPerformers: Array<{
+        memoryId: number;
+        useRate: number;
+        totalRecalls: number;
+    }>;
+    worstPerformers: Array<{
+        memoryId: number;
+        useRate: number;
+        totalRecalls: number;
+    }>;
+}
+/**
+ * Record a recall event — whether a memory was used after being retrieved.
+ *
+ * @param memoryId - The memory that was recalled
+ * @param query - The query that triggered the recall
+ * @param wasUsed - Whether the agent/user used this memory
+ * @param rankPosition - Position in the result list (1-based)
+ * @param similarityScore - The similarity score from retrieval
+ */
+export declare function recordRecallEvent(memoryId: number, query: string, wasUsed: boolean, rankPosition?: number, similarityScore?: number): number;
+/**
+ * Record recall events for a batch of retrieved memories.
+ * Mark top-K as "used" and remaining as "ignored".
+ *
+ * @param retrievedIds - All memory IDs returned by recall, in rank order
+ * @param usedIds - Memory IDs that were actually used/referenced
+ * @param query - The search query
+ */
+export declare function recordRecallBatch(retrievedIds: number[], usedIds: Set<number>, query: string, similarityScores?: Map<number, number>): void;
+/**
+ * Get recall statistics for a specific memory.
+ */
+export declare function getRecallStats(memoryId: number): RecallStats;
+/**
+ * Get recall summary across all memories.
+ */
+export declare function getRecallSummary(): RecallSummary;
+/**
+ * Get the boost factor for a memory based on its recall history.
+ * Used to adjust retrieval scores.
+ *
+ * @returns boost factor: 1.0 = neutral, >1.0 = boost, <1.0 = decay
+ */
+export declare function getBoostFactor(memoryId: number): number;
+/**
+ * Get boost factors for multiple memories at once.
+ */
+export declare function getBoostFactors(memoryIds: number[]): Map<number, number>;
+/**
+ * Get memory IDs that are never used (recalled but never marked as used).
+ * Useful for cleanup suggestions.
+ */
+export declare function getNeverUsedMemories(minRecalls?: number, limit?: number): Array<{
+    memoryId: number;
+    totalRecalls: number;
+    lastRecalled: string;
+}>;
+/**
+ * Delete old recall events to prevent unbounded growth.
+ *
+ * @param olderThanDays - Delete events older than this many days
+ * @returns Number of events deleted
+ */
+export declare function cleanupRecallEvents(olderThanDays?: number): number;
+//# sourceMappingURL=retrieval-feedback.d.ts.map

package/dist/lib/retrieval-feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval-feedback.d.ts","sourceRoot":"","sources":["../../src/lib/retrieval-feedback.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAqBH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClF,eAAe,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrF;AAMD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,EAChB,YAAY,CAAC,EAAE,MAAM,EACrB,eAAe,CAAC,EAAE,MAAM,GACvB,MAAM,CAER;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EAAE,EACtB,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,EACpB,KAAK,EAAE,MAAM,EACb,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GACrC,IAAI,CAUN;AAMD;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAmB5D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAiBhD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIvD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBxE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,GAAE,MAAU,EACtB,KAAK,GAAE,MAAW,GACjB,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,CAEzE;AAMD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,GAAE,MAAW,GAAG,MAAM,CAEtE"}

package/dist/lib/retrieval-feedback.js

@@ -0,0 +1,174 @@
+/**
+ * Retrieval Feedback Loops — track whether recalled memories were useful.
+ *
+ * Records recall events and uses historical usefulness to boost/decay
+ * memory retrieval scores. Self-improving retrieval over time.
+ *
+ * Inspired by Cognee's ~90% accuracy from feedback loops.
+ */
+// NOTE: Use-rate boost from recall events. See also temporal.ts calculateAccessBoost() for count-based access boost. These are complementary.
+import { insertRecallEvent, insertRecallEventsBatch, getRecallStatsRow, getRecallSummaryRow, getNeverUsedCount, getTopPerformers, getWorstPerformers, getBoostDataForMemory, getBoostDataForMemories, getNeverUsedMemoryRows, deleteOldRecallEvents, } from './db/index.js';
+// ============================================================================
+// Recording
+// ============================================================================
+/**
+ * Record a recall event — whether a memory was used after being retrieved.
+ *
+ * @param memoryId - The memory that was recalled
+ * @param query - The query that triggered the recall
+ * @param wasUsed - Whether the agent/user used this memory
+ * @param rankPosition - Position in the result list (1-based)
+ * @param similarityScore - The similarity score from retrieval
+ */
+export function recordRecallEvent(memoryId, query, wasUsed, rankPosition, similarityScore) {
+    return insertRecallEvent(memoryId, query, wasUsed, rankPosition ?? null, similarityScore ?? null);
+}
+/**
+ * Record recall events for a batch of retrieved memories.
+ * Mark top-K as "used" and remaining as "ignored".
+ *
+ * @param retrievedIds - All memory IDs returned by recall, in rank order
+ * @param usedIds - Memory IDs that were actually used/referenced
+ * @param query - The search query
+ */
+export function recordRecallBatch(retrievedIds, usedIds, query, similarityScores) {
+    const events = retrievedIds.map((memId, i) => ({
+        memoryId: memId,
+        query,
+        wasUsed: usedIds.has(memId),
+        rankPosition: i + 1,
+        similarityScore: similarityScores?.get(memId) ?? null,
+    }));
+    insertRecallEventsBatch(events);
+}
+// ============================================================================
+// Statistics
+// ============================================================================
+/**
+ * Get recall statistics for a specific memory.
+ */
+export function getRecallStats(memoryId) {
+    const row = getRecallStatsRow(memoryId);
+    const totalRecalls = row.total_recalls;
+    const timesUsed = row.times_used;
+    const timesIgnored = totalRecalls - timesUsed;
+    const useRate = totalRecalls > 0 ? timesUsed / totalRecalls : 0;
+    return {
+        memoryId,
+        totalRecalls,
+        timesUsed,
+        timesIgnored,
+        useRate,
+        avgRankWhenUsed: row.avg_rank_used,
+        avgRankWhenIgnored: row.avg_rank_ignored,
+        lastRecalled: row.last_recalled,
+        boostFactor: computeBoostFactor(totalRecalls, useRate),
+    };
+}
+/**
+ * Get recall summary across all memories.
+ */
+export function getRecallSummary() {
+    const totalRow = getRecallSummaryRow();
+    const total = totalRow.total;
+    const uniqueMemories = totalRow.unique_mems;
+    const overallUseRate = total > 0 ? totalRow.total_used / total : 0;
+    const neverUsedMemories = getNeverUsedCount();
+    const topPerformers = getTopPerformers();
+    const worstPerformers = getWorstPerformers();
+    return {
+        totalEvents: total,
+        uniqueMemories,
+        overallUseRate,
+        neverUsedMemories,
+        topPerformers,
+        worstPerformers,
+    };
+}
+/**
+ * Get the boost factor for a memory based on its recall history.
+ * Used to adjust retrieval scores.
+ *
+ * @returns boost factor: 1.0 = neutral, >1.0 = boost, <1.0 = decay
+ */
+export function getBoostFactor(memoryId) {
+    const row = getBoostDataForMemory(memoryId);
+    const useRate = row.total > 0 ? row.used / row.total : 0;
+    return computeBoostFactor(row.total, useRate);
+}
+/**
+ * Get boost factors for multiple memories at once.
+ */
+export function getBoostFactors(memoryIds) {
+    if (memoryIds.length === 0)
+        return new Map();
+    const rows = getBoostDataForMemories(memoryIds);
+    const result = new Map();
+    for (const row of rows) {
+        const useRate = row.total > 0 ? row.used / row.total : 0;
+        result.set(row.memory_id, computeBoostFactor(row.total, useRate));
+    }
+    // Memories with no recall history get neutral boost
+    for (const id of memoryIds) {
+        if (!result.has(id)) {
+            result.set(id, 1.0);
+        }
+    }
+    return result;
+}
+/**
+ * Get memory IDs that are never used (recalled but never marked as used).
+ * Useful for cleanup suggestions.
+ */
+export function getNeverUsedMemories(minRecalls = 3, limit = 50) {
+    return getNeverUsedMemoryRows(minRecalls, limit);
+}
+// ============================================================================
+// Cleanup
+// ============================================================================
+/**
+ * Delete old recall events to prevent unbounded growth.
+ *
+ * @param olderThanDays - Delete events older than this many days
+ * @returns Number of events deleted
+ */
+export function cleanupRecallEvents(olderThanDays = 90) {
+    return deleteOldRecallEvents(olderThanDays);
+}
+// ============================================================================
+// Internal
+// ============================================================================
+/**
+ * Compute boost factor from total recalls and use rate.
+ *
+ * Formula:
+ * - 0 recalls → 1.0 (neutral)
+ * - 1-2 recalls → minor adjustment (not enough data)
+ * - 3+ recalls → significant adjustment based on use rate
+ *
+ * Use rate mapping:
+ * - 80-100% → 1.3 (strong boost)
+ * - 60-80%  → 1.15 (moderate boost)
+ * - 40-60%  → 1.0 (neutral)
+ * - 20-40%  → 0.85 (moderate decay)
+ * - 0-20%   → 0.7 (strong decay)
+ */
+function computeBoostFactor(totalRecalls, useRate) {
+    if (totalRecalls < 3) {
+        // Not enough data — minor adjustment
+        if (totalRecalls === 0)
+            return 1.0;
+        return 0.95 + useRate * 0.1; // 0.95-1.05 range
+    }
+    // Significant data — apply full boost/decay
+    if (useRate >= 0.8)
+        return 1.3;
+    if (useRate >= 0.6)
+        return 1.15;
+    if (useRate >= 0.4)
+        return 1.0;
+    if (useRate >= 0.2)
+        return 0.85;
+    return 0.7;
+}
+//# sourceMappingURL=retrieval-feedback.js.map

package/dist/lib/retrieval-feedback.js.map

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

package/dist/lib/review/context-pack.d.ts

@@ -0,0 +1,58 @@
+/**
+ * MR Context Pack Generator — builds review context from a git diff.
+ *
+ * Pipeline:
+ * 1. git diff → parse-diff → changed files + hunks
+ * 2. succ_search_code → related symbols for each changed function
+ * 3. succ_recall → past decisions/pitfalls for touched modules
+ * 4. git log → recent changes to same files
+ * 5. callLLM → structured review context pack
+ */
+export interface ReviewContextPack {
+    summary: string;
+    diffStats: {
+        files: number;
+        additions: number;
+        deletions: number;
+    };
+    changedFiles: Array<{
+        path: string;
+        additions: number;
+        deletions: number;
+        isNew: boolean;
+        isDeleted: boolean;
+    }>;
+    changedSymbols: Array<{
+        file: string;
+        symbol: string;
+    }>;
+    relatedSymbols: Array<{
+        file: string;
+        symbol: string;
+        similarity: number;
+    }>;
+    relevantMemories: Array<{
+        id: number;
+        content: string;
+        tags: string[];
+        similarity: number;
+    }>;
+    recentHistory: Array<{
+        file: string;
+        commits: string[];
+    }>;
+    reviewFocus: string[];
+    blastRadius: string;
+}
+/**
+ * Generate a review context pack for a git diff reference.
+ *
+ * @param diffRef - Git diff reference (e.g., "HEAD~1", "main..feature", a commit SHA)
+ * @param options - Configuration options
+ */
+export declare function generateReviewContext(diffRef?: string, options?: {
+    maxRelatedSymbols?: number;
+    maxMemories?: number;
+    generateLLMSummary?: boolean;
+}): Promise<ReviewContextPack>;
+//# sourceMappingURL=context-pack.d.ts.map

package/dist/lib/review/context-pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-pack.d.ts","sourceRoot":"","sources":["../../../src/lib/review/context-pack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAiBH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,YAAY,EAAE,KAAK,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,OAAO,CAAC;QACf,SAAS,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;IACH,cAAc,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,cAAc,EAAE,KAAK,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IACH,gBAAgB,EAAE,KAAK,CAAC;QACtB,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IACH,aAAa,EAAE,KAAK,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC,CAAC;IACH,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,GAAE,MAAiB,EAC1B,OAAO,GAAE;IACP,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CACzB,GACL,OAAO,CAAC,iBAAiB,CAAC,CAuE5B"}