shieldcortex 2.20.0 → 3.0.0

package/dist/memory/embedding.js

@@ -9,6 +9,31 @@
 import { generateEmbedding, cosineSimilarity as rawCosineSimilarity, preloadModel } from '../embeddings/index.js';
 let initialized = false;
 let initFailed = false;
+const QUERY_CACHE_TTL_MS = 10 * 60 * 1000;
+const QUERY_CACHE_MAX = 64;
+const queryEmbeddingCache = new Map();
+function isExpectedEmbeddingDisable(message) {
+    return message.includes('SHIELDCORTEX_SKIP_EMBEDDINGS=1');
+}
+function normalizeQuery(text) {
+    return text.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+function cloneEmbedding(embedding) {
+    return new Float32Array(embedding);
+}
+function pruneQueryCache(now) {
+    for (const [key, entry] of queryEmbeddingCache) {
+        if (entry.expiresAt <= now) {
+            queryEmbeddingCache.delete(key);
+        }
+    }
+    while (queryEmbeddingCache.size > QUERY_CACHE_MAX) {
+        const oldestKey = queryEmbeddingCache.keys().next().value;
+        if (!oldestKey)
+            break;
+        queryEmbeddingCache.delete(oldestKey);
+    }
+}
 /**
  * Lazy-load the embedding model. Cache the pipeline.
  * Returns false on failure (doesn't crash).
@@ -24,7 +49,10 @@ export async function initEmbeddings() {
         return true;
     }
     catch (e) {
-        console.warn('[shieldcortex] Embedding init failed, vector recall disabled:', e.message);
+        const message = e.message;
+        if (!isExpectedEmbeddingDisable(message)) {
+            console.warn('[shieldcortex] Embedding init failed, vector recall disabled:', message);
+        }
         initFailed = false; // Allow retry on next call
         return false;
     }
@@ -40,7 +68,10 @@ export async function embedText(text) {
         return embedding;
     }
     catch (e) {
-        console.warn('[shieldcortex] embedText failed:', e.message);
+        const message = e.message;
+        if (!isExpectedEmbeddingDisable(message)) {
+            console.warn('[shieldcortex] embedText failed:', message);
+        }
         return null;
     }
 }
@@ -52,16 +83,47 @@ export function cosineSimilarity(a, b) {
         return 0;
     return rawCosineSimilarity(a, b);
 }
+/**
+ * Cache repeated query embeddings in-process to avoid re-embedding the same
+ * recall queries during one MCP/API session.
+ */
+export async function getCachedQueryEmbedding(query) {
+    const normalized = normalizeQuery(query);
+    if (!normalized)
+        return null;
+    const now = Date.now();
+    const cached = queryEmbeddingCache.get(normalized);
+    if (cached && cached.expiresAt > now) {
+        queryEmbeddingCache.delete(normalized);
+        queryEmbeddingCache.set(normalized, cached);
+        return cloneEmbedding(cached.embedding);
+    }
+    if (cached) {
+        queryEmbeddingCache.delete(normalized);
+    }
+    const embedding = await embedText(query);
+    if (!embedding)
+        return null;
+    queryEmbeddingCache.set(normalized, {
+        embedding: cloneEmbedding(embedding),
+        expiresAt: now + QUERY_CACHE_TTL_MS,
+    });
+    pruneQueryCache(now);
+    return embedding;
+}
+export function clearQueryEmbeddingCache() {
+    queryEmbeddingCache.clear();
+}
 /**
  * Embed the query, compute similarity against all memory embeddings,
  * return top K (default 10) sorted by score desc.
  *
  * Non-throwing: returns empty array on failure.
  */
-export async function findSimilarMemories(query, memories, topK = 10) {
+export async function findSimilarMemories(query, memories, topK = 10, queryEmbedding) {
     try {
-        const queryEmbedding = await embedText(query);
-        if (!queryEmbedding)
+        const activeQueryEmbedding = queryEmbedding ?? await getCachedQueryEmbedding(query);
+        if (!activeQueryEmbedding)
             return [];
         // We need embeddings for each memory — caller should provide pre-computed
         // embeddings via the cache. For memories without cached embeddings, we
@@ -72,7 +134,7 @@ export async function findSimilarMemories(query, memories, topK = 10) {
             const memEmbedding = await getOrComputeEmbedding(mem.id, `${mem.title}\n${mem.content}`);
             if (!memEmbedding)
                 continue;
-            const score = cosineSimilarity(queryEmbedding, memEmbedding);
+            const score = cosineSimilarity(activeQueryEmbedding, memEmbedding);
             scored.push({ id: mem.id, score });
         }
         scored.sort((a, b) => b.score - a.score);
@@ -83,4 +145,3 @@ export async function findSimilarMemories(query, memories, topK = 10) {
         return [];
     }
 }
-//# sourceMappingURL=embedding.js.map

package/dist/memory/expiry.d.ts

@@ -23,4 +23,3 @@ export declare function applyExpiryRules(): {
     deleted: number;
     protected: number;
 };
-//# sourceMappingURL=expiry.d.ts.map

package/dist/memory/expiry.js

@@ -106,4 +106,3 @@ function isProtected(row, protectRules) {
     }
     return false;
 }
-//# sourceMappingURL=expiry.js.map

package/dist/memory/salience.d.ts

@@ -33,4 +33,3 @@ export declare function isWorthRemembering(input: MemoryInput, minSalience?: num
  * Get a human-readable explanation of why something was considered important
  */
 export declare function explainSalience(factors: SalienceFactors): string;
-//# sourceMappingURL=salience.d.ts.map

package/dist/memory/salience.js

@@ -213,4 +213,3 @@ export function explainSalience(factors) {
         return 'general note';
     return reasons.join(', ');
 }
-//# sourceMappingURL=salience.js.map

package/dist/memory/similarity.d.ts

@@ -54,4 +54,3 @@ export declare function wordOverlap(textA: string, textB: string): number;
  * @returns True if texts share at least minOverlap words
  */
 export declare function hasSignificantOverlap(textA: string, textB: string, minOverlap?: number): boolean;
-//# sourceMappingURL=similarity.d.ts.map

package/dist/memory/similarity.js

@@ -111,4 +111,3 @@ export function wordOverlap(textA, textB) {
 export function hasSignificantOverlap(textA, textB, minOverlap = 3) {
     return wordOverlap(textA, textB) >= minOverlap;
 }
-//# sourceMappingURL=similarity.js.map

package/dist/memory/store.d.ts

@@ -99,6 +99,7 @@ export declare function getEnrichmentCooldownStatus(memoryId: number): {
  */
 export declare function updateDecayScores(): number;
 export declare function searchMemories(options: SearchOptions, config?: MemoryConfig, source?: DefenceSource): Promise<SearchResult[]>;
+export declare function searchMemoriesExplained(options: SearchOptions, config?: MemoryConfig, source?: DefenceSource): Promise<SearchResult[]>;
 /**
  * Recall with embedding-based vector similarity fallback.
  *
@@ -112,6 +113,8 @@ export declare function recallWithEmbeddings(query: string, options?: {
     limit?: number;
     project?: string;
     threshold?: number;
+    existingResults?: SearchResult[];
+    queryEmbedding?: Float32Array | null;
 }): Promise<Memory[]>;
 /**
  * Get all memories for a project
@@ -190,4 +193,3 @@ export declare function detectRelationships(memory: Memory, maxResults?: number)
     relationship: RelationshipType;
     strength: number;
 }[];
-//# sourceMappingURL=store.d.ts.map

package/dist/memory/store.js

@@ -22,6 +22,7 @@ import { checkAccess } from '../defence/trust/access-control.js';
 import { scoreSource } from '../defence/trust/source-scorer.js';
 import { logAudit } from '../defence/audit/logger.js';
 import { dispatchWebhook } from '../events/webhooks.js';
+import { getCachedQueryEmbedding, findSimilarMemories } from './embedding.js';
 // Anti-bloat: Maximum content size per memory (10KB)
 const MAX_CONTENT_SIZE = 10 * 1024;
 // Track truncation info globally for the last addMemory call
@@ -147,33 +148,42 @@ function detectGlobalPattern(content, category, tags) {
 // Tracks write attempts per source to prevent audit log flooding
 const RATE_LIMIT_WINDOW_MS = 60_000; // 1 minute
 const RATE_LIMIT_MAX = 20; // max writes per window per source
-const rateLimitMap = new Map();
-let rateLimitCheckCount = 0;
-function pruneRateLimitMap() {
-    const now = Date.now();
-    for (const [key, entry] of rateLimitMap) {
-        if (now - entry.windowStart > RATE_LIMIT_WINDOW_MS * 2) {
-            rateLimitMap.delete(key);
-        }
-    }
-}
+let rateLimitPruneCount = 0;
 function checkRateLimit(source) {
-    // Prune stale entries every 50 checks
-    if (++rateLimitCheckCount % 50 === 0) {
-        pruneRateLimitMap();
-    }
+    const db = getDatabase();
     const key = `${source.type}:${source.identifier}`;
     const now = Date.now();
-    const entry = rateLimitMap.get(key);
-    if (!entry || now - entry.windowStart > RATE_LIMIT_WINDOW_MS) {
-        rateLimitMap.set(key, { count: 1, windowStart: now });
+    // Prune expired entries every 50 checks
+    if (++rateLimitPruneCount % 50 === 0) {
+        try {
+            db.prepare('DELETE FROM rate_limits WHERE ? - window_start_ms > ?')
+                .run(now, RATE_LIMIT_WINDOW_MS * 2);
+        }
+        catch {
+            // Table may not exist yet in legacy DBs — fall through to allow
+        }
+    }
+    try {
+        const row = db.prepare('SELECT write_count, window_start_ms FROM rate_limits WHERE source_key = ?')
+            .get(key);
+        if (!row || now - row.window_start_ms > RATE_LIMIT_WINDOW_MS) {
+            // New window — upsert
+            db.prepare('INSERT INTO rate_limits (source_key, write_count, window_start_ms) VALUES (?, 1, ?) ON CONFLICT(source_key) DO UPDATE SET write_count = 1, window_start_ms = ?').run(key, now, now);
+            return true;
+        }
+        // Increment counter
+        const newCount = row.write_count + 1;
+        db.prepare('UPDATE rate_limits SET write_count = ? WHERE source_key = ?')
+            .run(newCount, key);
+        if (newCount > RATE_LIMIT_MAX) {
+            return false; // rate limited
+        }
         return true;
     }
-    entry.count++;
-    if (entry.count > RATE_LIMIT_MAX) {
-        return false; // rate limited
+    catch {
+        // If rate_limits table doesn't exist (legacy DB), allow the write
+        return true;
     }
-    return true;
 }
 // ── Read-Time Access Control ──
 function logAccessDenial(memoryId, source, reason) {
@@ -410,7 +420,9 @@ export function addMemory(input, config = DEFAULT_CONFIG, source) {
         }
     })
         .catch(e => {
-        if (e instanceof Error && e.message.includes('Embedding worker unavailable')) {
+        if (e instanceof Error &&
+            (e.message.includes('Embedding worker unavailable') ||
+                e.message.includes('Embeddings disabled via SHIELDCORTEX_SKIP_EMBEDDINGS=1'))) {
             return;
         }
         console.error('[shieldcortex] Failed to generate embedding:', e);
@@ -866,42 +878,87 @@ function vectorSearch(queryEmbedding, limit, project, includeGlobal = true) {
         .slice(0, limit);
     return results;
 }
-/**
- * Search memories using full-text search, vector similarity, and filters
- * Now uses hybrid search combining FTS5 keywords with semantic vector matching
- */
-let searchCount = 0;
-export async function searchMemories(options, config = DEFAULT_CONFIG, source) {
+function buildSearchExplanation(memory, context, values) {
+    const matchedTags = context.queryTags.filter((queryTag) => memory.tags.some((memoryTag) => {
+        const lowerMemoryTag = memoryTag.toLowerCase();
+        return lowerMemoryTag.includes(queryTag) || queryTag.includes(lowerMemoryTag);
+    }));
+    const reasons = [];
+    if (values.vectorSimilarity > 0) {
+        reasons.push(`Semantic similarity ${(values.vectorSimilarity * 100).toFixed(0)}%`);
+    }
+    if (values.ftsScore > 0.3) {
+        reasons.push('Strong keyword match');
+    }
+    if (values.categoryBoost > 0 && context.detectedCategory) {
+        reasons.push(`Matches ${context.detectedCategory} category intent`);
+    }
+    if (matchedTags.length > 0) {
+        reasons.push(`Shared tags: ${matchedTags.slice(0, 3).join(', ')}`);
+    }
+    if (values.recencyBoost > 0) {
+        reasons.push('Recently accessed');
+    }
+    if (values.linkBoost > 0) {
+        reasons.push('Connected to related memories');
+    }
+    if (values.activationBoost > 0) {
+        reasons.push('Activated by recent recall activity');
+    }
+    if (reasons.length === 0) {
+        reasons.push('Ranked by salience and base recall heuristics');
+    }
+    return {
+        query: context.query,
+        reasons,
+        breakdown: {
+            ftsScore: values.ftsScore,
+            vectorSimilarity: values.vectorSimilarity,
+            vectorBoost: values.vectorBoost,
+            decayedScore: values.decayedScore,
+            priorityBoost: values.priorityBoost,
+            recencyBoost: values.recencyBoost,
+            categoryBoost: values.categoryBoost,
+            linkBoost: values.linkBoost,
+            tagBoost: values.tagBoost,
+            activationBoost: values.activationBoost,
+            finalScore: values.finalScore,
+            matchedTags,
+            matchedCategory: values.categoryBoost > 0 ? context.detectedCategory : null,
+        },
+    };
+}
+async function searchMemoriesInternal(options, config, source, execution) {
     if (++searchCount % 100 === 0) {
         pruneActivationCache();
     }
     const db = getDatabase();
     const limit = options.limit || 20;
     const includeGlobal = options.includeGlobal ?? true;
-    // Detect query category for boosting
     const detectedCategory = options.query ? detectQueryCategory(options.query) : null;
     const queryTags = options.query ? extractQueryTags(options.query) : [];
-    // SEMANTIC SEARCH: Generate query embedding (may fail on first call while model loads)
     let queryEmbedding = null;
-    let vectorResults = new Map(); // memoryId -> similarity
+    const vectorResults = new Map();
     if (options.query && options.query.trim()) {
         try {
-            queryEmbedding = await generateEmbedding(options.query);
+            queryEmbedding = await getCachedQueryEmbedding(options.query);
+            if (!queryEmbedding) {
+                throw new Error('query embedding unavailable');
+            }
             const vectorHits = vectorSearch(queryEmbedding, limit * 2, options.project, includeGlobal);
             for (const hit of vectorHits) {
                 vectorResults.set(hit.memory.id, hit.similarity);
             }
         }
-        catch (e) {
-            // Vector search unavailable - fall back to FTS only
-            console.log('[shieldcortex] Vector search unavailable, using FTS only');
+        catch {
+            if (process.env.SHIELDCORTEX_SKIP_EMBEDDINGS !== '1') {
+                console.log('[shieldcortex] Vector search unavailable, using FTS only');
+            }
         }
     }
     let sql;
     const params = [];
     if (options.query && options.query.trim()) {
-        // Use FTS search - escape query to prevent FTS5 syntax errors
-        // FTS5 interprets "word-word" as "column:value", so we quote terms
         const escapedQuery = escapeFts5Query(options.query.trim());
         sql = `
       SELECT m.*, fts.rank
@@ -912,10 +969,8 @@ export async function searchMemories(options, config = DEFAULT_CONFIG, source) {
         params.push(escapedQuery);
     }
     else {
-        // No query, just filter
         sql = `SELECT *, 0 as rank FROM memories m WHERE 1=1`;
     }
-    // Add filters - include global memories if enabled
     if (options.project) {
         if (includeGlobal) {
             sql += ` AND (m.project = ? OR m.scope = 'global')`;
@@ -938,8 +993,6 @@ export async function searchMemories(options, config = DEFAULT_CONFIG, source) {
         params.push(options.minSalience);
     }
     if (options.tags && options.tags.length > 0) {
-        // Use json_each() for proper JSON array parsing
-        // This avoids false positives from LIKE matching (e.g., "api" matching "api-gateway")
         const tagPlaceholders = options.tags.map(() => '?').join(',');
         sql += ` AND EXISTS (
       SELECT 1 FROM json_each(m.tags)
@@ -950,94 +1003,98 @@ export async function searchMemories(options, config = DEFAULT_CONFIG, source) {
     sql += ' ORDER BY m.salience DESC, m.last_accessed DESC LIMIT ?';
     params.push(limit);
     const rows = db.prepare(sql).all(...params);
-    // Convert to SearchResult with computed scores
-    const results = rows.map(row => {
+    const scoringContext = {
+        db,
+        config,
+        detectedCategory,
+        queryTags,
+        vectorResults,
+        query: options.query,
+    };
+    const results = rows.map((row) => {
         const memory = rowToMemory(row);
         const decayedScore = calculateDecayedScore(memory, config);
         memory.decayedScore = decayedScore;
-        // Improved FTS score normalization (BM25-style)
-        // FTS5 rank is negative, closer to 0 = better match
         const rawRank = row.rank;
         const ftsScore = rawRank ? 1 / (1 + Math.abs(rawRank)) : 0.3;
-        // Recency boost for recently accessed memories
         const hoursSinceAccess = (Date.now() - new Date(memory.lastAccessed).getTime()) / (1000 * 60 * 60);
         const recencyBoost = hoursSinceAccess < 1 ? 0.1 : (hoursSinceAccess < 24 ? 0.05 : 0);
-        // Category match bonus
         const categoryBoost = detectedCategory && memory.category === detectedCategory ? 0.1 : 0;
-        // Link boost - memories connected to high-salience memories rank higher
         const linkBoost = calculateLinkBoost(memory.id, db);
-        // Partial tag match bonus
         const tagBoost = calculateTagScore(queryTags, memory.tags);
-        // ORGANIC FEATURE: Spreading Activation boost (Phase 2)
-        // Recently accessed memories and their linked neighbors get a boost
         const activationBoost = getActivationBoost(memory.id);
-        // SEMANTIC SEARCH: Vector similarity boost (Phase 5)
-        // If memory was found by vector search, add similarity as a boost
         const vectorSimilarity = vectorResults.get(memory.id) || 0;
-        const vectorBoost = vectorSimilarity * 0.3; // 30% weight for vector similarity
-        // Combined relevance score (adjusted weights to accommodate vector)
-        const relevanceScore = (ftsScore * 0.25 + // Reduced from 0.3
-            vectorBoost + // New: 0-0.3 from vector similarity
-            decayedScore * 0.2 + // Reduced from 0.25
-            calculatePriority(memory) * 0.05 + // Reduced from 0.1
+        const vectorBoost = vectorSimilarity * 0.3;
+        const priorityBoost = calculatePriority(memory) * 0.05;
+        const relevanceScore = (ftsScore * 0.25 +
+            vectorBoost +
+            decayedScore * 0.2 +
+            priorityBoost +
             recencyBoost + categoryBoost + linkBoost + tagBoost + activationBoost);
-        return { memory, relevanceScore };
+        const result = { memory, relevanceScore };
+        if (execution.includeExplanation) {
+            result.explanation = buildSearchExplanation(memory, scoringContext, {
+                ftsScore,
+                vectorSimilarity,
+                vectorBoost,
+                decayedScore,
+                priorityBoost,
+                recencyBoost,
+                categoryBoost,
+                linkBoost,
+                tagBoost,
+                activationBoost,
+                finalScore: relevanceScore,
+            });
+        }
+        return result;
     });
-    // Sort by relevance and filter out too-decayed memories
     const sortedResults = results
-        .filter(r => options.includeDecayed || r.memory.decayedScore >= config.salienceThreshold)
+        .filter((result) => options.includeDecayed || result.memory.decayedScore >= config.salienceThreshold)
         .sort((a, b) => b.relevanceScore - a.relevanceScore);
-    // ORGANIC FEATURE: Reinforce top search results
-    // This closes the feedback loop - memories that appear in searches get a small
-    // salience boost with diminishing returns, so useful memories grow stronger
-    const topResults = sortedResults.slice(0, 5);
-    for (const result of topResults) {
-        reinforceFromSearch(result.memory.id);
-    }
-    // ORGANIC FEATURE: Link co-returned search results (top 5 only)
-    // Memories that frequently appear together in searches become linked,
-    // building the knowledge graph from usage patterns
-    if (topResults.length >= 2) {
-        for (let i = 0; i < topResults.length; i++) {
-            for (let j = i + 1; j < topResults.length; j++) {
-                const idA = topResults[i].memory.id;
-                const idB = topResults[j].memory.id;
-                const existing = db.prepare('SELECT strength FROM memory_links WHERE (source_id = ? AND target_id = ?) OR (source_id = ? AND target_id = ?)').get(idA, idB, idB, idA);
-                if (existing) {
-                    const newStrength = Math.min(1.0, existing.strength + 0.03);
-                    db.prepare('UPDATE memory_links SET strength = ? WHERE (source_id = ? AND target_id = ?) OR (source_id = ? AND target_id = ?)').run(newStrength, idA, idB, idB, idA);
-                }
-                else {
-                    try {
-                        db.prepare('INSERT INTO memory_links (source_id, target_id, relationship, strength) VALUES (?, ?, ?, ?)').run(idA, idB, 'related', 0.2);
+    if (execution.enableSideEffects) {
+        const topResults = sortedResults.slice(0, 5);
+        for (const result of topResults) {
+            reinforceFromSearch(result.memory.id);
+        }
+        if (topResults.length >= 2) {
+            for (let i = 0; i < topResults.length; i++) {
+                for (let j = i + 1; j < topResults.length; j++) {
+                    const idA = topResults[i].memory.id;
+                    const idB = topResults[j].memory.id;
+                    const existing = db.prepare('SELECT strength FROM memory_links WHERE (source_id = ? AND target_id = ?) OR (source_id = ? AND target_id = ?)').get(idA, idB, idB, idA);
+                    if (existing) {
+                        const newStrength = Math.min(1.0, existing.strength + 0.03);
+                        db.prepare('UPDATE memory_links SET strength = ? WHERE (source_id = ? AND target_id = ?) OR (source_id = ? AND target_id = ?)').run(newStrength, idA, idB, idB, idA);
                     }
-                    catch (e) {
-                        // Only ignore UNIQUE constraint violations (expected for existing links)
-                        if (!(e instanceof Error && e.message.includes('UNIQUE constraint'))) {
-                            console.warn('[shieldcortex] Unexpected error linking co-returned memories:', e);
+                    else {
+                        try {
+                            db.prepare('INSERT INTO memory_links (source_id, target_id, relationship, strength) VALUES (?, ?, ?, ?)').run(idA, idB, 'related', 0.2);
+                        }
+                        catch (e) {
+                            if (!(e instanceof Error && e.message.includes('UNIQUE constraint'))) {
+                                console.warn('[shieldcortex] Unexpected error linking co-returned memories:', e);
+                            }
                         }
                     }
                 }
             }
         }
-    }
-    // ORGANIC FEATURE: Enrich top result with search context
-    // When a search query contains significant new information not already in the
-    // top result, append it as enrichment context so memories accumulate knowledge
-    if (sortedResults.length > 0 && options.query && options.query.length > 30) {
-        const topResult = sortedResults[0];
-        const queryWords = new Set(options.query.toLowerCase().split(/\s+/).filter(w => w.length > 3));
-        const contentWords = new Set(topResult.memory.content.toLowerCase().split(/\s+/));
-        const newWords = [...queryWords].filter(w => !contentWords.has(w));
-        // Only enrich if query has significant new content (>30% new words)
-        if (newWords.length > queryWords.size * 0.3 && options.query.length > 50) {
-            try {
-                enrichMemory(topResult.memory.id, options.query, 'search');
+        if (sortedResults.length > 0 && options.query && options.query.length > 30) {
+            const topResult = sortedResults[0];
+            const queryWords = new Set(options.query.toLowerCase().split(/\s+/).filter(w => w.length > 3));
+            const contentWords = new Set(topResult.memory.content.toLowerCase().split(/\s+/));
+            const newWords = [...queryWords].filter(w => !contentWords.has(w));
+            if (newWords.length > queryWords.size * 0.3 && options.query.length > 50) {
+                try {
+                    enrichMemory(topResult.memory.id, options.query, 'search');
+                }
+                catch {
+                    // enrichment is best-effort
+                }
             }
-            catch { /* enrichment is best-effort */ }
         }
     }
-    // Look up contradictions for top results
     const finalResults = sortedResults.slice(0, limit);
     for (const result of finalResults) {
         const contradictions = db.prepare(`
@@ -1048,13 +1105,15 @@ export async function searchMemories(options, config = DEFAULT_CONFIG, source) {
         AND (ml.source_id = ? OR ml.target_id = ?)
     `).all(result.memory.id, result.memory.id, result.memory.id);
         if (contradictions.length > 0) {
-            result.contradictions = contradictions.map(c => {
-                const other = db.prepare('SELECT title FROM memories WHERE id = ?').get(c.other_id);
-                return { memoryId: c.other_id, title: other?.title || 'Unknown', score: c.strength };
+            result.contradictions = contradictions.map((contradiction) => {
+                const other = db.prepare('SELECT title FROM memories WHERE id = ?').get(contradiction.other_id);
+                return { memoryId: contradiction.other_id, title: other?.title || 'Unknown', score: contradiction.strength };
             });
+            if (result.explanation) {
+                result.explanation.reasons.push(`${contradictions.length} contradiction link${contradictions.length === 1 ? '' : 's'} attached`);
+            }
         }
     }
-    // ACCESS CONTROL: Filter results by source trust level
     if (source) {
         const db2 = getDatabase();
         return finalResults.filter(result => {
@@ -1069,6 +1128,23 @@ export async function searchMemories(options, config = DEFAULT_CONFIG, source) {
     }
     return finalResults;
 }
+/**
+ * Search memories using full-text search, vector similarity, and filters
+ * Now uses hybrid search combining FTS5 keywords with semantic vector matching
+ */
+let searchCount = 0;
+export async function searchMemories(options, config = DEFAULT_CONFIG, source) {
+    return searchMemoriesInternal(options, config, source, {
+        enableSideEffects: true,
+        includeExplanation: false,
+    });
+}
+export async function searchMemoriesExplained(options, config = DEFAULT_CONFIG, source) {
+    return searchMemoriesInternal(options, config, source, {
+        enableSideEffects: false,
+        includeExplanation: true,
+    });
+}
 /**
  * Recall with embedding-based vector similarity fallback.
  *
@@ -1082,18 +1158,20 @@ export async function recallWithEmbeddings(query, options) {
     const limit = options?.limit ?? 15;
     const threshold = options?.threshold ?? 0.3;
     // Step 1: Try FTS5 search first
-    let ftsResults = [];
-    try {
-        ftsResults = await searchMemories({
-            query,
-            project: options?.project,
-            limit,
-            includeGlobal: true,
-        });
-    }
-    catch (e) {
-        // FTS search failed — continue to embedding fallback
-        console.warn('[shieldcortex] FTS search failed in recallWithEmbeddings:', e.message);
+    let ftsResults = options?.existingResults ?? [];
+    if (ftsResults.length === 0) {
+        try {
+            ftsResults = await searchMemories({
+                query,
+                project: options?.project,
+                limit,
+                includeGlobal: true,
+            });
+        }
+        catch (e) {
+            // FTS search failed — continue to embedding fallback
+            console.warn('[shieldcortex] FTS search failed in recallWithEmbeddings:', e.message);
+        }
     }
     const ftsMemories = ftsResults.map(r => r.memory);
     // Step 2: If FTS5 returns >= 3 results, no need for embedding fallback
@@ -1102,7 +1180,7 @@ export async function recallWithEmbeddings(query, options) {
     }
     // Step 3: Run embedding similarity search as fallback
     try {
-        const { initEmbeddings, findSimilarMemories } = await import('./embedding.js');
+        const { initEmbeddings } = await import('./embedding.js');
         const ready = await initEmbeddings();
         if (!ready) {
             return ftsMemories.slice(0, limit);
@@ -1123,9 +1201,13 @@ export async function recallWithEmbeddings(query, options) {
         if (newCandidates.length === 0) {
             return ftsMemories.slice(0, limit);
         }
+        const queryEmbedding = options?.queryEmbedding ?? await getCachedQueryEmbedding(query);
+        if (!queryEmbedding) {
+            return ftsMemories.slice(0, limit);
+        }
         // Find similar memories using embeddings
         const remainingSlots = limit - ftsMemories.length;
-        const similar = await findSimilarMemories(query, newCandidates, remainingSlots);
+        const similar = await findSimilarMemories(query, newCandidates, remainingSlots, queryEmbedding);
         // Filter by threshold and fetch full Memory objects
         const embeddingMemories = [];
         for (const hit of similar) {
@@ -1498,4 +1580,3 @@ export function detectRelationships(memory, maxResults = 5) {
         .sort((a, b) => b.strength - a.strength)
         .slice(0, maxResults);
 }
-//# sourceMappingURL=store.js.map