@poolzin/pool-bot 2026.2.11 → 2026.2.18

package/dist/memory/manager.js

@@ -20,6 +20,7 @@ import { buildFileEntry, chunkMarkdown, ensureDir, hashText, isMemoryPath, listM
 import { bm25RankToScore, buildFtsQuery, mergeHybridResults } from "./hybrid.js";
 import { searchKeyword, searchVector } from "./manager-search.js";
 import { ensureMemoryIndexSchema } from "./memory-schema.js";
+import { extractKeywords } from "./query-expansion.js";
 import { requireNodeSqlite } from "./sqlite.js";
 import { loadSqliteVecExtension } from "./sqlite-vec.js";
 const META_KEY = "memory_index_meta_v1";
@@ -54,6 +55,7 @@ export class MemoryIndexManager {
     requestedProvider;
     fallbackFrom;
     fallbackReason;
+    providerUnavailableReason;
     openAi;
     gemini;
     voyage;
@@ -108,6 +110,7 @@ export class MemoryIndexManager {
             workspaceDir,
             settings,
             providerResult,
+            purpose: params.purpose,
         });
         INDEX_CACHE.set(key, manager);
         return manager;
@@ -122,6 +125,7 @@ export class MemoryIndexManager {
         this.requestedProvider = params.providerResult.requestedProvider;
         this.fallbackFrom = params.providerResult.fallbackFrom;
         this.fallbackReason = params.providerResult.fallbackReason;
+        this.providerUnavailableReason = params.providerResult.providerUnavailableReason;
         this.openAi = params.providerResult.openAi;
         this.gemini = params.providerResult.gemini;
         this.voyage = params.providerResult.voyage;
@@ -146,7 +150,8 @@ export class MemoryIndexManager {
         this.ensureWatcher();
         this.ensureSessionListener();
         this.ensureIntervalSync();
-        this.dirty = this.sources.has("memory");
+        const statusOnly = params.purpose === "status";
+        this.dirty = this.sources.has("memory") && (statusOnly ? !meta : true);
         this.batch = this.resolveBatchConfig();
     }
     async warmSession(sessionKey) {
@@ -175,6 +180,30 @@ export class MemoryIndexManager {
         const maxResults = opts?.maxResults ?? this.settings.query.maxResults;
         const hybrid = this.settings.query.hybrid;
         const candidates = Math.min(200, Math.max(1, Math.floor(maxResults * hybrid.candidateMultiplier)));
+        // FTS-only mode: no embedding provider available
+        if (!this.provider) {
+            if (!this.fts.enabled || !this.fts.available) {
+                log.warn("memory search: no provider and FTS unavailable");
+                return [];
+            }
+            const keywords = extractKeywords(cleaned);
+            const searchTerms = keywords.length > 0 ? keywords : [cleaned];
+            const resultSets = await Promise.all(searchTerms.map((term) => this.searchKeyword(term, candidates).catch(() => [])));
+            const seenIds = new Map();
+            for (const results of resultSets) {
+                for (const result of results) {
+                    const existing = seenIds.get(result.id);
+                    if (!existing || result.score > existing.score) {
+                        seenIds.set(result.id, result);
+                    }
+                }
+            }
+            const merged = [...seenIds.values()]
+                .toSorted((a, b) => b.score - a.score)
+                .filter((entry) => entry.score >= minScore)
+                .slice(0, maxResults);
+            return merged;
+        }
         const keywordResults = hybrid.enabled
             ? await this.searchKeyword(cleaned, candidates).catch(() => [])
             : [];
@@ -186,15 +215,19 @@ export class MemoryIndexManager {
         if (!hybrid.enabled) {
             return vectorResults.filter((entry) => entry.score >= minScore).slice(0, maxResults);
         }
-        const merged = this.mergeHybridResults({
+        const merged = await this.mergeHybridResults({
             vector: vectorResults,
             keyword: keywordResults,
             vectorWeight: hybrid.vectorWeight,
             textWeight: hybrid.textWeight,
+            mmr: hybrid.mmr,
+            temporalDecay: hybrid.temporalDecay,
         });
         return merged.filter((entry) => entry.score >= minScore).slice(0, maxResults);
     }
     async searchVector(queryVec, limit) {
+        if (!this.provider)
+            return [];
         const results = await searchVector({
             db: this.db,
             vectorTable: VECTOR_TABLE,
@@ -218,7 +251,7 @@ export class MemoryIndexManager {
         const results = await searchKeyword({
             db: this.db,
             ftsTable: FTS_TABLE,
-            providerModel: this.provider.model,
+            providerModel: this.provider?.model ?? "fts-only",
             query,
             limit,
             snippetMaxChars: SNIPPET_MAX_CHARS,
@@ -228,8 +261,8 @@ export class MemoryIndexManager {
         });
         return results.map((entry) => entry);
     }
-    mergeHybridResults(params) {
-        const merged = mergeHybridResults({
+    async mergeHybridResults(params) {
+        const merged = await mergeHybridResults({
             vector: params.vector.map((r) => ({
                 id: r.id,
                 path: r.path,
@@ -250,6 +283,9 @@ export class MemoryIndexManager {
             })),
             vectorWeight: params.vectorWeight,
             textWeight: params.textWeight,
+            workspaceDir: this.workspaceDir,
+            mmr: params.mmr,
+            temporalDecay: params.temporalDecay,
         });
         return merged.map((entry) => entry);
     }
@@ -359,8 +395,8 @@ export class MemoryIndexManager {
             dirty: this.dirty || this.sessionsDirty,
             workspaceDir: this.workspaceDir,
             dbPath: this.settings.store.path,
-            provider: this.provider.id,
-            model: this.provider.model,
+            provider: this.provider?.id ?? "none",
+            model: this.provider?.model,
             requestedProvider: this.requestedProvider,
             sources: Array.from(this.sources),
             extraPaths: this.settings.extraPaths,
@@ -882,7 +918,7 @@ export class MemoryIndexManager {
                 try {
                     this.db
                         .prepare(`DELETE FROM ${FTS_TABLE} WHERE path = ? AND source = ? AND model = ?`)
-                        .run(stale.path, "memory", this.provider.model);
+                        .run(stale.path, "memory", this.provider?.model ?? "fts-only");
                 }
                 catch { }
             }
@@ -976,7 +1012,7 @@ export class MemoryIndexManager {
                 try {
                     this.db
                         .prepare(`DELETE FROM ${FTS_TABLE} WHERE path = ? AND source = ? AND model = ?`)
-                        .run(stale.path, "sessions", this.provider.model);
+                        .run(stale.path, "sessions", this.provider?.model ?? "fts-only");
                 }
                 catch { }
             }
@@ -1015,8 +1051,8 @@ export class MemoryIndexManager {
         const meta = this.readMeta();
         const needsFullReindex = params?.force ||
             !meta ||
-            meta.model !== this.provider.model ||
-            meta.provider !== this.provider.id ||
+            meta.model !== this.provider?.model ||
+            meta.provider !== this.provider?.id ||
             meta.providerKey !== this.providerKey ||
             meta.chunkTokens !== this.settings.chunking.tokens ||
             meta.chunkOverlap !== this.settings.chunking.overlap ||
@@ -1068,9 +1104,9 @@ export class MemoryIndexManager {
     resolveBatchConfig() {
         const batch = this.settings.remote?.batch;
         const enabled = Boolean(batch?.enabled &&
-            ((this.openAi && this.provider.id === "openai") ||
-                (this.gemini && this.provider.id === "gemini") ||
-                (this.voyage && this.provider.id === "voyage")));
+            ((this.openAi && this.provider?.id === "openai") ||
+                (this.gemini && this.provider?.id === "gemini") ||
+                (this.voyage && this.provider?.id === "voyage")));
         return {
             enabled,
             wait: batch?.wait ?? true,
@@ -1081,7 +1117,7 @@ export class MemoryIndexManager {
     }
     async activateFallbackProvider(reason) {
         const fallback = this.settings.fallback;
-        if (!fallback || fallback === "none" || fallback === this.provider.id)
+        if (!fallback || fallback === "none" || !this.provider || fallback === this.provider.id)
             return false;
         if (this.fallbackFrom)
             return false;
@@ -1170,8 +1206,8 @@ export class MemoryIndexManager {
                 this.sessionsDirty = false;
             }
             nextMeta = {
-                model: this.provider.model,
-                provider: this.provider.id,
+                model: this.provider?.model ?? "fts-only",
+                provider: this.provider?.id ?? "none",
                 providerKey: this.providerKey,
                 chunkTokens: this.settings.chunking.tokens,
                 chunkOverlap: this.settings.chunking.overlap,
@@ -1371,7 +1407,11 @@ export class MemoryIndexManager {
         if (unique.length === 0)
             return new Map();
         const out = new Map();
-        const baseParams = [this.provider.id, this.provider.model, this.providerKey];
+        const baseParams = [
+            this.provider?.id ?? "none",
+            this.provider?.model ?? "fts-only",
+            this.providerKey,
+        ];
         const batchSize = 400;
         for (let start = 0; start < unique.length; start += batchSize) {
             const batch = unique.slice(start, start + batchSize);
@@ -1387,7 +1427,7 @@ export class MemoryIndexManager {
         return out;
     }
     upsertEmbeddingCache(entries) {
-        if (!this.cache.enabled)
+        if (!this.cache.enabled || !this.provider)
             return;
         if (entries.length === 0)
             return;
@@ -1461,6 +1501,9 @@ export class MemoryIndexManager {
         return embeddings;
     }
     computeProviderKey() {
+        if (!this.provider) {
+            return hashText(JSON.stringify({ provider: "none", model: "fts-only" }));
+        }
         if (this.provider.id === "openai" && this.openAi) {
             const entries = Object.entries(this.openAi.headers)
                 .filter(([key]) => key.toLowerCase() !== "authorization")
@@ -1491,13 +1534,13 @@ export class MemoryIndexManager {
         return hashText(JSON.stringify({ provider: this.provider.id, model: this.provider.model }));
     }
     async embedChunksWithBatch(chunks, entry, source) {
-        if (this.provider.id === "openai" && this.openAi) {
+        if (this.provider?.id === "openai" && this.openAi) {
             return this.embedChunksWithOpenAiBatch(chunks, entry, source);
         }
-        if (this.provider.id === "gemini" && this.gemini) {
+        if (this.provider?.id === "gemini" && this.gemini) {
             return this.embedChunksWithGeminiBatch(chunks, entry, source);
         }
-        if (this.provider.id === "voyage" && this.voyage) {
+        if (this.provider?.id === "voyage" && this.voyage) {
             return this.embedChunksWithVoyageBatch(chunks, entry, source);
         }
         return this.embedChunksInBatches(chunks);
@@ -1602,7 +1645,7 @@ export class MemoryIndexManager {
                 method: "POST",
                 url: OPENAI_BATCH_ENDPOINT,
                 body: {
-                    model: this.openAi?.model ?? this.provider.model,
+                    model: this.openAi?.model ?? this.provider?.model ?? "fts-only",
                     input: chunk.text,
                 },
             });
@@ -1700,6 +1743,8 @@ export class MemoryIndexManager {
     async embedBatchWithRetry(texts) {
         if (texts.length === 0)
             return [];
+        if (!this.provider)
+            throw new Error("embedding provider unavailable");
         let attempt = 0;
         let delayMs = EMBEDDING_RETRY_BASE_DELAY_MS;
         while (true) {
@@ -1729,13 +1774,15 @@ export class MemoryIndexManager {
         return /(rate[_ ]limit|too many requests|429|resource has been exhausted|5\d\d|cloudflare)/i.test(message);
     }
     resolveEmbeddingTimeout(kind) {
-        const isLocal = this.provider.id === "local";
+        const isLocal = this.provider?.id === "local";
         if (kind === "query") {
             return isLocal ? EMBEDDING_QUERY_TIMEOUT_LOCAL_MS : EMBEDDING_QUERY_TIMEOUT_REMOTE_MS;
         }
         return isLocal ? EMBEDDING_BATCH_TIMEOUT_LOCAL_MS : EMBEDDING_BATCH_TIMEOUT_REMOTE_MS;
     }
     async embedQueryWithTimeout(text) {
+        if (!this.provider)
+            throw new Error("embedding provider unavailable");
         const timeoutMs = this.resolveEmbeddingTimeout("query");
         log.debug("memory embeddings: query start", { provider: this.provider.id, timeoutMs });
         return await this.withTimeout(this.provider.embedQuery(text), timeoutMs, `memory embeddings query timed out after ${Math.round(timeoutMs / 1000)}s`);
@@ -1873,7 +1920,7 @@ export class MemoryIndexManager {
             try {
                 this.db
                     .prepare(`DELETE FROM ${FTS_TABLE} WHERE path = ? AND source = ? AND model = ?`)
-                    .run(entry.path, options.source, this.provider.model);
+                    .run(entry.path, options.source, this.provider?.model ?? "fts-only");
             }
             catch { }
         }
@@ -1883,7 +1930,8 @@ export class MemoryIndexManager {
         for (let i = 0; i < chunks.length; i++) {
             const chunk = chunks[i];
             const embedding = embeddings[i] ?? [];
-            const id = hashText(`${options.source}:${entry.path}:${chunk.startLine}:${chunk.endLine}:${chunk.hash}:${this.provider.model}`);
+            const providerModel = this.provider?.model ?? "fts-only";
+            const id = hashText(`${options.source}:${entry.path}:${chunk.startLine}:${chunk.endLine}:${chunk.hash}:${providerModel}`);
             this.db
                 .prepare(`INSERT INTO chunks (id, path, source, start_line, end_line, hash, model, text, embedding, updated_at)
            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
@@ -1893,7 +1941,7 @@ export class MemoryIndexManager {
              text=excluded.text,
              embedding=excluded.embedding,
              updated_at=excluded.updated_at`)
-                .run(id, entry.path, options.source, chunk.startLine, chunk.endLine, chunk.hash, this.provider.model, chunk.text, JSON.stringify(embedding), now);
+                .run(id, entry.path, options.source, chunk.startLine, chunk.endLine, chunk.hash, providerModel, chunk.text, JSON.stringify(embedding), now);
             if (vectorReady && embedding.length > 0) {
                 try {
                     this.db.prepare(`DELETE FROM ${VECTOR_TABLE} WHERE id = ?`).run(id);
@@ -1907,7 +1955,7 @@ export class MemoryIndexManager {
                 this.db
                     .prepare(`INSERT INTO ${FTS_TABLE} (text, id, path, source, model, start_line, end_line)\n` +
                     ` VALUES (?, ?, ?, ?, ?, ?, ?)`)
-                    .run(chunk.text, id, entry.path, options.source, this.provider.model, chunk.startLine, chunk.endLine);
+                    .run(chunk.text, id, entry.path, options.source, providerModel, chunk.startLine, chunk.endLine);
             }
         }
         this.db

package/dist/memory/mmr.js

@@ -0,0 +1,164 @@
+/**
+ * Maximal Marginal Relevance (MMR) re-ranking algorithm.
+ *
+ * MMR balances relevance with diversity by iteratively selecting results
+ * that maximize: λ * relevance - (1-λ) * max_similarity_to_selected
+ *
+ * @see Carbonell & Goldstein, "The Use of MMR, Diversity-Based Reranking" (1998)
+ */
+export const DEFAULT_MMR_CONFIG = {
+    enabled: false,
+    lambda: 0.7,
+};
+/**
+ * Tokenize text for Jaccard similarity computation.
+ * Extracts alphanumeric tokens and normalizes to lowercase.
+ */
+export function tokenize(text) {
+    const tokens = text.toLowerCase().match(/[a-z0-9_]+/g) ?? [];
+    return new Set(tokens);
+}
+/**
+ * Compute Jaccard similarity between two token sets.
+ * Returns a value in [0, 1] where 1 means identical sets.
+ */
+export function jaccardSimilarity(setA, setB) {
+    if (setA.size === 0 && setB.size === 0) {
+        return 1;
+    }
+    if (setA.size === 0 || setB.size === 0) {
+        return 0;
+    }
+    let intersectionSize = 0;
+    const smaller = setA.size <= setB.size ? setA : setB;
+    const larger = setA.size <= setB.size ? setB : setA;
+    for (const token of smaller) {
+        if (larger.has(token)) {
+            intersectionSize++;
+        }
+    }
+    const unionSize = setA.size + setB.size - intersectionSize;
+    return unionSize === 0 ? 0 : intersectionSize / unionSize;
+}
+/**
+ * Compute text similarity between two content strings using Jaccard on tokens.
+ */
+export function textSimilarity(contentA, contentB) {
+    return jaccardSimilarity(tokenize(contentA), tokenize(contentB));
+}
+/**
+ * Compute the maximum similarity between an item and all selected items.
+ */
+function maxSimilarityToSelected(item, selectedItems, tokenCache) {
+    if (selectedItems.length === 0) {
+        return 0;
+    }
+    let maxSim = 0;
+    const itemTokens = tokenCache.get(item.id) ?? tokenize(item.content);
+    for (const selected of selectedItems) {
+        const selectedTokens = tokenCache.get(selected.id) ?? tokenize(selected.content);
+        const sim = jaccardSimilarity(itemTokens, selectedTokens);
+        if (sim > maxSim) {
+            maxSim = sim;
+        }
+    }
+    return maxSim;
+}
+/**
+ * Compute MMR score for a candidate item.
+ * MMR = λ * relevance - (1-λ) * max_similarity_to_selected
+ */
+export function computeMMRScore(relevance, maxSimilarity, lambda) {
+    return lambda * relevance - (1 - lambda) * maxSimilarity;
+}
+/**
+ * Re-rank items using Maximal Marginal Relevance (MMR).
+ *
+ * The algorithm iteratively selects items that balance relevance with diversity:
+ * 1. Start with the highest-scoring item
+ * 2. For each remaining slot, select the item that maximizes the MMR score
+ * 3. MMR score = λ * relevance - (1-λ) * max_similarity_to_already_selected
+ *
+ * @param items - Items to re-rank, must have score and content
+ * @param config - MMR configuration (lambda, enabled)
+ * @returns Re-ranked items in MMR order
+ */
+export function mmrRerank(items, config = {}) {
+    const { enabled = DEFAULT_MMR_CONFIG.enabled, lambda = DEFAULT_MMR_CONFIG.lambda } = config;
+    // Early exits
+    if (!enabled || items.length <= 1) {
+        return [...items];
+    }
+    // Clamp lambda to valid range
+    const clampedLambda = Math.max(0, Math.min(1, lambda));
+    // If lambda is 1, just return sorted by relevance (no diversity penalty)
+    if (clampedLambda === 1) {
+        return [...items].toSorted((a, b) => b.score - a.score);
+    }
+    // Pre-tokenize all items for efficiency
+    const tokenCache = new Map();
+    for (const item of items) {
+        tokenCache.set(item.id, tokenize(item.content));
+    }
+    // Normalize scores to [0, 1] for fair comparison with similarity
+    const maxScore = Math.max(...items.map((i) => i.score));
+    const minScore = Math.min(...items.map((i) => i.score));
+    const scoreRange = maxScore - minScore;
+    const normalizeScore = (score) => {
+        if (scoreRange === 0) {
+            return 1; // All scores equal
+        }
+        return (score - minScore) / scoreRange;
+    };
+    const selected = [];
+    const remaining = new Set(items);
+    // Select items iteratively
+    while (remaining.size > 0) {
+        let bestItem = null;
+        let bestMMRScore = -Infinity;
+        for (const candidate of remaining) {
+            const normalizedRelevance = normalizeScore(candidate.score);
+            const maxSim = maxSimilarityToSelected(candidate, selected, tokenCache);
+            const mmrScore = computeMMRScore(normalizedRelevance, maxSim, clampedLambda);
+            // Use original score as tiebreaker (higher is better)
+            if (mmrScore > bestMMRScore ||
+                (mmrScore === bestMMRScore && candidate.score > (bestItem?.score ?? -Infinity))) {
+                bestMMRScore = mmrScore;
+                bestItem = candidate;
+            }
+        }
+        if (bestItem) {
+            selected.push(bestItem);
+            remaining.delete(bestItem);
+        }
+        else {
+            // Should never happen, but safety exit
+            break;
+        }
+    }
+    return selected;
+}
+/**
+ * Apply MMR re-ranking to hybrid search results.
+ * Adapts the generic MMR function to work with the hybrid search result format.
+ */
+export function applyMMRToHybridResults(results, config = {}) {
+    if (results.length === 0) {
+        return results;
+    }
+    // Create a map from ID to original item for type-safe retrieval
+    const itemById = new Map();
+    // Create MMR items with unique IDs
+    const mmrItems = results.map((r, index) => {
+        const id = `${r.path}:${r.startLine}:${index}`;
+        itemById.set(id, r);
+        return {
+            id,
+            score: r.score,
+            content: r.snippet,
+        };
+    });
+    const reranked = mmrRerank(mmrItems, config);
+    // Map back to original items using the ID
+    return reranked.map((item) => itemById.get(item.id));
+}