causantic 0.2.0 → 0.3.0

package/dist/retrieval/context-assembler.js

@@ -1,313 +1,76 @@
 /**
  * Context assembly for memory retrieval.
- * Combines vector search with graph traversal to assemble relevant context.
- */
-import { vectorStore } from '../storage/vector-store.js';
-import { getChunkById } from '../storage/chunk-store.js';
-import { Embedder } from '../models/embedder.js';
-import { getModel } from '../models/model-registry.js';
-import { getConfig } from '../config/memory-config.js';
-import { approximateTokens } from '../utils/token-counter.js';
-import { traverseMultiple, dedupeAndRank } from './traverser.js';
-import { getReferenceClock } from '../storage/clock-store.js';
-import { KeywordStore } from '../storage/keyword-store.js';
-import { fuseRRF } from './rrf.js';
-import { expandViaClusters } from './cluster-expander.js';
-import { createLogger } from '../utils/logger.js';
-const log = createLogger('context-assembler');
-/**
- * Shared embedder instance for retrieval.
- */
-let sharedEmbedder = null;
-/**
- * Get or create shared embedder.
- */
-async function getEmbedder() {
-    if (!sharedEmbedder) {
-        sharedEmbedder = new Embedder();
-        await sharedEmbedder.load(getModel('jina-small'));
-    }
-    return sharedEmbedder;
-}
-/**
- * Shared keyword store instance for retrieval.
- */
-let sharedKeywordStore = null;
-/**
- * Get or create shared keyword store.
+ *
+ * Delegates to specialized modules:
+ * - searchContext() for pure semantic search (no graph)
+ * - recallContext() for episodic recall (backward chain walking)
+ * - predictContext() for episodic prediction (forward chain walking)
  */
-function getKeywordStore() {
-    if (!sharedKeywordStore) {
-        sharedKeywordStore = new KeywordStore();
-    }
-    return sharedKeywordStore;
-}
+import { searchContext, disposeSearch } from './search-assembler.js';
+import { recallContext, predictContext } from './chain-assembler.js';
 /**
  * Assemble context from memory based on a query.
- *
- * Pipeline: embed → [vector search, keyword search] → RRF fusion → cluster expansion
- *           → graph traverse → combine → dedupe → recency → budget
+ * Delegates to searchContext (pure search, no graph).
  */
 export async function assembleContext(request) {
-    const startTime = Date.now();
-    const config = getConfig();
-    const { query, currentSessionId, projectSlug, projectFilter, queryTime = Date.now(), maxTokens = config.mcpMaxResponseTokens, mode, range = 'auto', vectorSearchLimit = 20, skipGraph = false, skipClusters = false, } = request;
-    const { hybridSearch, clusterExpansion } = config;
-    // If projectFilter is a single string, also use it for clock lookup
-    const effectiveProjectSlug = projectSlug ??
-        (typeof projectFilter === 'string' ? projectFilter : undefined);
-    // Get reference clock for vector clock-based decay (if project slug provided)
-    const referenceClock = effectiveProjectSlug ? getReferenceClock(effectiveProjectSlug) : undefined;
-    // 1. Embed query
-    const embedder = await getEmbedder();
-    const queryResult = await embedder.embed(query, true); // isQuery = true
-    // 2. Run vector search and keyword search in parallel
-    const vectorSearchPromise = projectFilter
-        ? vectorStore.searchByProject(queryResult.embedding, projectFilter, vectorSearchLimit)
-        : vectorStore.search(queryResult.embedding, vectorSearchLimit);
-    let keywordResults = [];
-    try {
-        const keywordStore = getKeywordStore();
-        keywordResults = projectFilter
-            ? keywordStore.searchByProject(query, projectFilter, hybridSearch.keywordSearchLimit)
-            : keywordStore.search(query, hybridSearch.keywordSearchLimit);
-    }
-    catch (error) {
-        // Graceful fallback: keyword search unavailable (FTS5 missing, table corrupted, etc.)
-        log.warn('Keyword search unavailable, falling back to vector-only', {
-            error: error.message,
-        });
-    }
-    const similar = await vectorSearchPromise;
-    if (similar.length === 0 && keywordResults.length === 0) {
-        return {
-            text: '',
-            tokenCount: 0,
-            chunks: [],
-            totalConsidered: 0,
-            durationMs: Date.now() - startTime,
-            graphBoosted: 0,
-        };
-    }
-    // 3. Convert to RankedItem format and fuse with RRF
-    const vectorItems = similar.map(s => ({
-        chunkId: s.id,
-        score: Math.max(0, 1 - s.distance),
-        source: 'vector',
-    }));
-    const keywordItems = keywordResults.map(r => ({
-        chunkId: r.id,
-        score: r.score,
-        source: 'keyword',
-    }));
-    const fusedResults = fuseRRF([
-        { items: vectorItems, weight: hybridSearch.vectorWeight },
-        ...(keywordItems.length > 0
-            ? [{ items: keywordItems, weight: hybridSearch.keywordWeight }]
-            : []),
-    ], hybridSearch.rrfK);
-    // 4. Cluster expansion (skip if requested for benchmarking)
-    const expandedResults = skipClusters
-        ? fusedResults
-        : expandViaClusters(fusedResults, clusterExpansion, projectFilter);
-    const sourceMap = new Map();
-    for (const item of expandedResults) {
-        if (item.source && !sourceMap.has(item.chunkId)) {
-            sourceMap.set(item.chunkId, item.source);
-        }
-    }
-    // 5. Determine traversal direction and decay model based on mode and range
-    const direction = mode === 'predict' ? 'forward' : 'backward';
-    let decayConfig;
-    if (direction === 'forward') {
-        decayConfig = config.forwardDecay;
-    }
-    else if (range === 'short') {
-        decayConfig = config.shortRangeDecay;
-    }
-    else if (range === 'long') {
-        decayConfig = config.longRangeDecay;
-    }
-    else {
-        decayConfig = mode === 'explain' ? config.longRangeDecay : config.shortRangeDecay;
-    }
-    // 6. Traverse graph from fused+expanded seeds (skip if requested for benchmarking)
-    let traversalResult;
-    if (skipGraph) {
-        traversalResult = { chunks: [], visited: 0 };
-    }
-    else {
-        const startIds = expandedResults.map(r => r.chunkId);
-        const startWeights = expandedResults.map(r => r.score);
-        traversalResult = await traverseMultiple(startIds, startWeights, queryTime, {
-            direction,
-            decayConfig,
-            referenceClock,
-        });
-        // Tag traversal results with 'graph' source
-        for (const tc of traversalResult.chunks) {
-            if (!sourceMap.has(tc.chunkId)) {
-                sourceMap.set(tc.chunkId, 'graph');
-            }
-        }
-    }
-    // 7. Combine direct hits with traversal, boosting intersection
-    const allChunks = [];
-    let graphBoostedCount = 0;
-    // Build graph traversal lookup
-    const graphChunkMap = new Map();
-    for (const tc of traversalResult.chunks) {
-        graphChunkMap.set(tc.chunkId, tc);
-    }
-    // Direct hits: boost if also found via graph traversal
-    const directChunkIds = new Set();
-    for (const item of expandedResults) {
-        directChunkIds.add(item.chunkId);
-        let weight = item.score * config.directHitBoost;
-        const graphEntry = graphChunkMap.get(item.chunkId);
-        if (graphEntry) {
-            weight += graphEntry.weight * config.graphAgreementBoost;
-            graphBoostedCount++;
-        }
-        allChunks.push({ chunkId: item.chunkId, weight, depth: 0 });
-    }
-    // Graph-only results: add unchanged
-    for (const tc of traversalResult.chunks) {
-        if (!directChunkIds.has(tc.chunkId)) {
-            allChunks.push(tc);
-        }
-    }
-    // 8. Dedupe and rank
-    const ranked = dedupeAndRank(allChunks);
-    // 9. Apply recency boost for current session
-    if (currentSessionId) {
-        for (const wc of ranked) {
-            const chunk = getChunkById(wc.chunkId);
-            if (chunk && chunk.sessionId === currentSessionId) {
-                wc.weight *= 1.2; // 20% boost for current session
-            }
-        }
-        ranked.sort((a, b) => b.weight - a.weight);
-    }
-    // 10. Assemble within token budget
-    const assembled = assembleWithinBudget(ranked, maxTokens, sourceMap);
-    return {
-        text: assembled.text,
-        tokenCount: assembled.tokenCount,
-        chunks: assembled.includedChunks,
-        totalConsidered: ranked.length,
-        durationMs: Date.now() - startTime,
-        graphBoosted: graphBoostedCount,
-    };
-}
-/**
- * Assemble text within token budget.
- */
-function assembleWithinBudget(ranked, maxTokens, sourceMap) {
-    const parts = [];
-    const includedChunks = [];
-    let totalTokens = 0;
-    for (const wc of ranked) {
-        const chunk = getChunkById(wc.chunkId);
-        if (!chunk)
-            continue;
-        const chunkTokens = chunk.approxTokens || approximateTokens(chunk.content);
-        // Check if adding this chunk would exceed budget
-        if (totalTokens + chunkTokens > maxTokens) {
-            // Try to fit a truncated version
-            const remainingTokens = maxTokens - totalTokens;
-            if (remainingTokens > 100) {
-                const truncated = truncateChunk(chunk.content, remainingTokens);
-                parts.push(formatChunkForOutput(chunk, truncated, wc.weight));
-                totalTokens += approximateTokens(truncated);
-                includedChunks.push({
-                    id: chunk.id,
-                    sessionSlug: chunk.sessionSlug,
-                    weight: wc.weight,
-                    preview: truncated.slice(0, 100) + '...',
-                    source: sourceMap?.get(chunk.id),
-                });
-            }
-            break;
-        }
-        parts.push(formatChunkForOutput(chunk, chunk.content, wc.weight));
-        totalTokens += chunkTokens;
-        includedChunks.push({
-            id: chunk.id,
-            sessionSlug: chunk.sessionSlug,
-            weight: wc.weight,
-            preview: chunk.content.slice(0, 100) + (chunk.content.length > 100 ? '...' : ''),
-            source: sourceMap?.get(chunk.id),
-        });
-    }
-    return {
-        text: parts.join('\n\n---\n\n'),
-        tokenCount: totalTokens,
-        includedChunks,
-    };
-}
-/**
- * Format a chunk for output with metadata header.
- */
-function formatChunkForOutput(chunk, content, weight) {
-    const date = new Date(chunk.startTime).toLocaleDateString();
-    const relevance = (weight * 100).toFixed(0);
-    return `[Session: ${chunk.sessionSlug} | Date: ${date} | Relevance: ${relevance}%]\n${content}`;
-}
-/**
- * Truncate chunk content to fit token budget.
- */
-function truncateChunk(content, maxTokens) {
-    // Rough estimate: 4 chars per token
-    const maxChars = maxTokens * 4;
-    if (content.length <= maxChars) {
-        return content;
-    }
-    // Try to cut at a paragraph boundary
-    const truncated = content.slice(0, maxChars);
-    const lastNewline = truncated.lastIndexOf('\n\n');
-    if (lastNewline > maxChars * 0.5) {
-        return truncated.slice(0, lastNewline) + '\n\n...[truncated]';
-    }
-    return truncated + '\n...[truncated]';
+    const searchResponse = await searchContext({
+        query: request.query,
+        currentSessionId: request.currentSessionId,
+        projectFilter: request.projectFilter,
+        maxTokens: request.maxTokens,
+        vectorSearchLimit: request.vectorSearchLimit,
+    });
+    return searchResponseToRetrievalResponse(searchResponse);
 }
 /**
- * Recall: retrieve context relevant to a query.
+ * Recall: episodic retrieval walking backward through causal chains.
  */
 export async function recall(query, options = {}) {
-    return assembleContext({
+    const response = await recallContext({
         query,
-        mode: 'recall',
-        ...options,
-    });
-}
-/**
- * Explain: retrieve context that explains how we got to current state.
- */
-export async function explain(topic, options = {}) {
-    return assembleContext({
-        query: topic,
-        mode: 'explain',
-        ...options,
+        currentSessionId: options.currentSessionId,
+        projectFilter: options.projectFilter,
+        maxTokens: options.maxTokens,
+        vectorSearchLimit: options.vectorSearchLimit,
     });
+    return episodicResponseToRetrievalResponse(response);
 }
 /**
- * Predict: retrieve context that might be relevant next.
+ * Predict: episodic retrieval walking forward through causal chains.
  */
 export async function predict(context, options = {}) {
-    return assembleContext({
+    const response = await predictContext({
         query: context,
-        mode: 'predict',
-        ...options,
+        currentSessionId: options.currentSessionId,
+        projectFilter: options.projectFilter,
+        maxTokens: options.maxTokens,
+        vectorSearchLimit: options.vectorSearchLimit,
     });
+    return episodicResponseToRetrievalResponse(response);
 }
 /**
  * Cleanup shared resources.
  */
 export async function disposeRetrieval() {
-    if (sharedEmbedder) {
-        await sharedEmbedder.dispose();
-        sharedEmbedder = null;
-    }
+    await disposeSearch();
+}
+// Adapters
+function searchResponseToRetrievalResponse(response) {
+    return {
+        text: response.text,
+        tokenCount: response.tokenCount,
+        chunks: response.chunks,
+        totalConsidered: response.totalConsidered,
+        durationMs: response.durationMs,
+    };
+}
+function episodicResponseToRetrievalResponse(response) {
+    return {
+        text: response.text,
+        tokenCount: response.tokenCount,
+        chunks: response.chunks,
+        totalConsidered: response.chunks.length,
+        durationMs: response.durationMs,
+    };
 }
 //# sourceMappingURL=context-assembler.js.map

package/dist/retrieval/context-assembler.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-assembler.js","sourceRoot":"","sources":["../../src/retrieval/context-assembler.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"context-assembler.js","sourceRoot":"","sources":["../../src/retrieval/context-assembler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,aAAa,EAAuB,MAAM,uBAAuB,CAAC;AAC1F,OAAO,EAAE,aAAa,EAAE,cAAc,EAAyB,MAAM,sBAAsB,CAAC;AA8C5F;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAAyB;IAC7D,MAAM,cAAc,GAAG,MAAM,aAAa,CAAC;QACzC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;QAC1C,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;KAC7C,CAAC,CAAC;IAEH,OAAO,iCAAiC,CAAC,cAAc,CAAC,CAAC;AAC3D,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,KAAa,EACb,UAAqC,EAAE;IAEvC,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC;QACnC,KAAK;QACL,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;QAC1C,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;KAC7C,CAAC,CAAC;IAEH,OAAO,mCAAmC,CAAC,QAAQ,CAAC,CAAC;AACvD,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,OAAe,EACf,UAAqC,EAAE;IAEvC,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC;QACpC,KAAK,EAAE,OAAO;QACd,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;QAC1C,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;KAC7C,CAAC,CAAC;IAEH,OAAO,mCAAmC,CAAC,QAAQ,CAAC,CAAC;AACvD,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,MAAM,aAAa,EAAE,CAAC;AACxB,CAAC;AAED,WAAW;AAEX,SAAS,iCAAiC,CAAC,QAAwB;IACjE,OAAO;QACL,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,UAAU,EAAE,QAAQ,CAAC,UAAU;QAC/B,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,eAAe,EAAE,QAAQ,CAAC,eAAe;QACzC,UAAU,EAAE,QAAQ,CAAC,UAAU;KAChC,CAAC;AACJ,CAAC;AAED,SAAS,mCAAmC,CAAC,QAA0B;IACrE,OAAO;QACL,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,UAAU,EAAE,QAAQ,CAAC,UAAU;QAC/B,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM;QACvC,UAAU,EAAE,QAAQ,CAAC,UAAU;KAChC,CAAC;AACJ,CAAC"}

package/dist/retrieval/index.d.ts

@@ -1,10 +1,14 @@
 /**
  * Retrieval system exports.
  */
-export { traverse, traverseMultiple, resolveChunks, dedupeAndRank } from './traverser.js';
-export type { TraversalOptions } from './traverser.js';
-export { assembleContext, recall, explain, predict, disposeRetrieval, } from './context-assembler.js';
-export type { RetrievalMode, RetrievalRange, RetrievalRequest, RetrievalResponse } from './context-assembler.js';
+export { assembleContext, recall, predict, disposeRetrieval, } from './context-assembler.js';
+export type { RetrievalRequest, RetrievalResponse } from './context-assembler.js';
+export { searchContext, disposeSearch } from './search-assembler.js';
+export type { SearchRequest, SearchResponse } from './search-assembler.js';
+export { recallContext, predictContext } from './chain-assembler.js';
+export type { EpisodicRequest, EpisodicResponse } from './chain-assembler.js';
+export { walkChains, selectBestChain } from './chain-walker.js';
+export type { Chain, ChainWalkerOptions } from './chain-walker.js';
 export { fuseRRF } from './rrf.js';
 export type { RankedItem, RRFSource } from './rrf.js';
 export { expandViaClusters } from './cluster-expander.js';

package/dist/retrieval/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC1F,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGvD,OAAO,EACL,eAAe,EACf,MAAM,EACN,OAAO,EACP,OAAO,EACP,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGjH,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAGtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EACL,eAAe,EACf,MAAM,EACN,OAAO,EACP,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGlF,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACrE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG3E,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACrE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG9E,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAChE,YAAY,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAGnE,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAGtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/retrieval/index.js

@@ -1,10 +1,14 @@
 /**
  * Retrieval system exports.
  */
-// Traverser
-export { traverse, traverseMultiple, resolveChunks, dedupeAndRank } from './traverser.js';
 // Context assembler
-export { assembleContext, recall, explain, predict, disposeRetrieval, } from './context-assembler.js';
+export { assembleContext, recall, predict, disposeRetrieval, } from './context-assembler.js';
+// Search assembler
+export { searchContext, disposeSearch } from './search-assembler.js';
+// Chain assembler
+export { recallContext, predictContext } from './chain-assembler.js';
+// Chain walker
+export { walkChains, selectBestChain } from './chain-walker.js';
 // Reciprocal Rank Fusion
 export { fuseRRF } from './rrf.js';
 // Cluster expansion

package/dist/retrieval/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY;AACZ,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG1F,oBAAoB;AACpB,OAAO,EACL,eAAe,EACf,MAAM,EACN,OAAO,EACP,OAAO,EACP,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAGhC,yBAAyB;AACzB,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAGnC,oBAAoB;AACpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,oBAAoB;AACpB,OAAO,EACL,eAAe,EACf,MAAM,EACN,OAAO,EACP,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAGhC,mBAAmB;AACnB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAGrE,kBAAkB;AAClB,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGrE,eAAe;AACf,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGhE,yBAAyB;AACzB,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAGnC,oBAAoB;AACpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/retrieval/rrf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rrf.d.ts","sourceRoot":"","sources":["../../src/retrieval/rrf.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;CACrD;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAID;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,SAAS,EAAE,EAAE,CAAC,GAAE,MAAkB,GAAG,UAAU,EAAE,CAyCjF"}
+{"version":3,"file":"rrf.d.ts","sourceRoot":"","sources":["../../src/retrieval/rrf.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;CACrD;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAID;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,SAAS,EAAE,EAAE,CAAC,GAAE,MAAkB,GAAG,UAAU,EAAE,CA2CjF"}

package/dist/retrieval/rrf.js

@@ -39,8 +39,10 @@ export function fuseRRF(sources, k = DEFAULT_K) {
     // Convert to array and sort by fused score descending
     const results = [];
     for (const [chunkId, { score, sources }] of scoreMap) {
-        // Pick the first source as the primary one (vector > keyword > cluster > graph)
-        const priority = ['vector', 'keyword', 'cluster', 'graph'];
+        // Credit the most informative source (graph > cluster > keyword > vector).
+        // Vector is the baseline — rarer sources that also found this chunk
+        // represent added value from the graph/keyword/cluster pipeline stages.
+        const priority = ['graph', 'cluster', 'keyword', 'vector'];
         let bestSource = undefined;
         for (const p of priority) {
             if (sources.has(p)) {

package/dist/retrieval/rrf.js.map

@@ -1 +1 @@
-{"version":3,"file":"rrf.js","sourceRoot":"","sources":["../../src/retrieval/rrf.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH,MAAM,SAAS,GAAG,EAAE,CAAC;AAErB;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,OAAoB,EAAE,IAAY,SAAS;IACjE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,2CAA2C;IAC3C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAmD,CAAC;IAE5E,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC;YACtD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAChC,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,wCAAwC;YAEzF,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC5C,IAAI,QAAQ,EAAE,CAAC;gBACb,QAAQ,CAAC,KAAK,IAAI,QAAQ,CAAC;gBAC3B,IAAI,IAAI,CAAC,MAAM;oBAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrD,CAAC;iBAAM,CAAC;gBACN,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;gBAClC,IAAI,IAAI,CAAC,MAAM;oBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC1C,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;IACH,CAAC;IAED,sDAAsD;IACtD,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,KAAK,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC;QACrD,gFAAgF;QAChF,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;QAC3D,IAAI,UAAU,GAAyB,SAAS,CAAC;QACjD,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnB,UAAU,GAAG,CAAyB,CAAC;gBACvC,MAAM;YACR,CAAC;QACH,CAAC;QAED,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;IACvD,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAC1C,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"rrf.js","sourceRoot":"","sources":["../../src/retrieval/rrf.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH,MAAM,SAAS,GAAG,EAAE,CAAC;AAErB;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,OAAoB,EAAE,IAAY,SAAS;IACjE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,2CAA2C;IAC3C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAmD,CAAC;IAE5E,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC;YACtD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAChC,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,wCAAwC;YAEzF,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC5C,IAAI,QAAQ,EAAE,CAAC;gBACb,QAAQ,CAAC,KAAK,IAAI,QAAQ,CAAC;gBAC3B,IAAI,IAAI,CAAC,MAAM;oBAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrD,CAAC;iBAAM,CAAC;gBACN,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;gBAClC,IAAI,IAAI,CAAC,MAAM;oBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC1C,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;IACH,CAAC;IAED,sDAAsD;IACtD,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,KAAK,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC;QACrD,2EAA2E;QAC3E,oEAAoE;QACpE,wEAAwE;QACxE,MAAM,QAAQ,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QAC3D,IAAI,UAAU,GAAyB,SAAS,CAAC;QACjD,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnB,UAAU,GAAG,CAAyB,CAAC;gBACvC,MAAM;YACR,CAAC;QACH,CAAC;QAED,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;IACvD,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAC1C,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/retrieval/search-assembler.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Pure search pipeline for semantic discovery.
+ *
+ * Pipeline: embed → [vector, keyword] → RRF → cluster expand → dedupe → recency → budget
+ *
+ * No graph traversal. Used for the `search` MCP tool and as fallback for episodic recall
+ * when no qualifying chain is found.
+ */
+/**
+ * Request for search-based context retrieval.
+ */
+export interface SearchRequest {
+    /** Query text */
+    query: string;
+    /** Current session ID (optional, for recency boost) */
+    currentSessionId?: string;
+    /** Filter results to specific project(s) */
+    projectFilter?: string | string[];
+    /** Maximum tokens in response */
+    maxTokens?: number;
+    /** Number of vector search results */
+    vectorSearchLimit?: number;
+    /** Skip cluster expansion (for benchmarking) */
+    skipClusters?: boolean;
+}
+/**
+ * Search response with assembled context.
+ */
+export interface SearchResponse {
+    /** Assembled context text */
+    text: string;
+    /** Approximate token count */
+    tokenCount: number;
+    /** Chunks included in response */
+    chunks: Array<{
+        id: string;
+        sessionSlug: string;
+        weight: number;
+        preview: string;
+        source?: 'vector' | 'keyword' | 'cluster';
+    }>;
+    /** Total chunks considered */
+    totalConsidered: number;
+    /** Time taken in milliseconds */
+    durationMs: number;
+    /** Query embedding (for downstream chain walking) */
+    queryEmbedding: number[];
+    /** Top seed IDs from RRF (for chain walking) */
+    seedIds: string[];
+}
+/**
+ * Run the search pipeline: embed → vector + keyword → RRF → cluster expand → budget.
+ */
+export declare function searchContext(request: SearchRequest): Promise<SearchResponse>;
+/**
+ * Cleanup shared resources.
+ */
+export declare function disposeSearch(): Promise<void>;
+//# sourceMappingURL=search-assembler.d.ts.map

package/dist/retrieval/search-assembler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-assembler.d.ts","sourceRoot":"","sources":["../../src/retrieval/search-assembler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4CAA4C;IAC5C,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAClC,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,MAAM,EAAE,KAAK,CAAC;QACZ,EAAE,EAAE,MAAM,CAAC;QACX,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;KAC3C,CAAC,CAAC;IACH,8BAA8B;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,gDAAgD;IAChD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AA2BD;;GAEG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CA0HnF;AA0FD;;GAEG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAKnD"}