@framers/agentos 0.1.246 → 0.1.248

package/dist/memory/retrieval/hybrid/HybridRetriever.js

@@ -0,0 +1,287 @@
+/**
+ * @file HybridRetriever.ts
+ * @description Hybrid BM25 + dense retrieval for memory-domain traces.
+ * Dense side uses {@link MemoryStore} (preserves 6-signal cognitive
+ * scoring). Sparse side uses a per-instance {@link BM25Index}. RRF
+ * merges by rank. Optional {@link RerankerService} runs over the
+ * merged pool.
+ *
+ * ## What this does
+ *
+ * Given a query, runs dense retrieval through `MemoryStore.query`
+ * (cognitive-scored traces) and sparse retrieval through an owned
+ * `BM25Index` (keyword-matched trace content). Fuses the two ranked
+ * lists via Reciprocal Rank Fusion, optionally reranks the merged
+ * pool with a neural cross-encoder, and returns a standard
+ * `CognitiveRetrievalResult` so downstream consumers (prompt
+ * assembly, bench adapters) don't change shape.
+ *
+ * ## Why a separate class, not a `CognitiveMemoryManager` option
+ *
+ * Keeps the existing manager retrieval path untouched (same reason
+ * as SessionRetriever in Step 2). MVP ships as opt-in.
+ *
+ * ## Rerank integration is mandatory-wired from the bench
+ *
+ * Per the Step 2 post-mortem (rerank-skip was the root cause of
+ * that step's RED verdict), Step 3 threads rerank from day 1 when
+ * the bench is configured with `--rerank cohere`. Callers outside
+ * the bench can pass `undefined` for `rerankerService` to skip
+ * rerank explicitly.
+ *
+ * ## Sparse-only documents are skipped in MVP
+ *
+ * A document that appears in `bm25.search` results but NOT in the
+ * dense over-fetch pool is skipped. Rationale: at the default
+ * over-fetch=3 and K=10 (30 dense candidates), a doc ranked top-30
+ * on sparse is very likely in dense's top-30 on any coherent query.
+ * Measured impact is expected to be negligible. If Tier A surfaces
+ * a meaningful drop rate, the fix is to add a
+ * `memoryStore.getTrace(id)` hydration path.
+ *
+ * @module agentos/memory/retrieval/hybrid/HybridRetriever
+ */
+import { BM25Index } from '../../../rag/search/BM25Index.js';
+import { reciprocalRankFusion } from './reciprocalRankFusion.js';
+/**
+ * Hybrid BM25 + dense retriever.
+ *
+ * @example
+ * ```ts
+ * const hybrid = new HybridRetriever({ memoryStore, rerankerService });
+ * // At ingest:
+ * hybrid.bm25.addDocument(trace.id, trace.content, { tag: 'bench-session:s-1' });
+ * // At query time:
+ * const result = await hybrid.retrieve(
+ *   'What did the user say about their mortgage?',
+ *   { valence: 0, arousal: 0, dominance: 0 },
+ *   { scope: 'user', scopeId: 'u1' },
+ *   { recallTopK: 10 },
+ * );
+ * ```
+ */
+export class HybridRetriever {
+    constructor(opts) {
+        this.memoryStore = opts.memoryStore;
+        this.bm25 = new BM25Index(opts.bm25Config);
+        this.rerankerService = opts.rerankerService;
+        this.hydeRetriever = opts.hydeRetriever;
+        this.splitAmbiguousThreshold = opts.splitAmbiguousThreshold;
+        this.defaultDenseWeight = opts.defaultDenseWeight ?? 0.7;
+        this.defaultSparseWeight = opts.defaultSparseWeight ?? 0.3;
+        this.defaultRrfK = opts.defaultRrfK ?? 60;
+    }
+    async retrieve(query, mood, scope, options = {}) {
+        const startTime = Date.now();
+        const recallTopK = options.recallTopK ?? 10;
+        const overFetchMultiplier = options.overFetchMultiplier ?? 3;
+        const overFetchTopK = recallTopK * overFetchMultiplier;
+        const wDense = options.denseWeight ?? this.defaultDenseWeight;
+        const wSparse = options.sparseWeight ?? this.defaultSparseWeight;
+        const rrfK = options.rrfK ?? this.defaultRrfK;
+        // HyDE expansion (Step 4): when a hydeRetriever is attached,
+        // generate a hypothetical answer and use it as the query for BOTH
+        // dense and sparse sides. The reranker (below) keeps the ORIGINAL
+        // query so it scores documents against the user's real intent,
+        // not the hypothesis. Errors are non-critical — fall back to raw.
+        let effectiveQuery = query;
+        let hypothesisDiagnostic;
+        if (this.hydeRetriever) {
+            try {
+                const hypo = await this.hydeRetriever.generateHypothesis(query);
+                if (hypo.hypothesis && hypo.hypothesis.trim().length > 0) {
+                    effectiveQuery = hypo.hypothesis;
+                    hypothesisDiagnostic = hypo.hypothesis.slice(0, 120);
+                }
+            }
+            catch {
+                // HyDE generation failed — raw query fallback.
+            }
+        }
+        // Dense side: use MemoryStore.query so we keep the 6-signal
+        // cognitive scoring (strength, recency, etc.) — matches baseline.
+        const { scored: denseScored, timings: denseTimings } = await this.memoryStore.query(effectiveQuery, mood, { topK: overFetchTopK, scopes: [scope] });
+        // Sparse side: BM25 over the per-instance index.
+        const sparseResults = this.bm25.search(effectiveQuery, overFetchTopK);
+        // Fallback: empty BM25 index or zero sparse hits => dense-only
+        // with explicit escalation diagnostic.
+        if (sparseResults.length === 0) {
+            return this.buildResult(denseScored.slice(0, recallTopK), {
+                escalations: ['hybrid-retriever:sparse-empty'],
+                candidatesScanned: denseScored.length,
+                vectorSearchMs: denseTimings.vectorSearchMs,
+                scoringMs: denseTimings.scoringMs,
+                totalMs: Date.now() - startTime,
+                hypothesis: hypothesisDiagnostic,
+            });
+        }
+        // Build 1-based ranked lists for RRF.
+        const denseRanked = denseScored.map((t, i) => ({ id: t.id, rank: i + 1 }));
+        const sparseRanked = sparseResults.map((r, i) => ({ id: r.id, rank: i + 1 }));
+        const merged = reciprocalRankFusion(denseRanked, sparseRanked, {
+            denseWeight: wDense,
+            sparseWeight: wSparse,
+            k: rrfK,
+        });
+        // Hydrate: resolve each RRFResult.id to the ScoredMemoryTrace from
+        // the dense side. Skip sparse-only docs (see file docstring).
+        const denseById = new Map(denseScored.map((t) => [t.id, t]));
+        const hydrated = [];
+        for (const m of merged) {
+            const trace = denseById.get(m.id);
+            if (trace) {
+                hydrated.push(trace);
+            }
+            // MVP: sparse-only docs (not in denseById) are skipped.
+        }
+        // Optional rerank: same 0.7 cognitive + 0.3 neural blend as baseline.
+        let splitDiagnostic;
+        if (this.rerankerService && hydrated.length > 0) {
+            try {
+                const rerankerOutput = await this.rerankerService.rerank({
+                    query,
+                    documents: hydrated.map((t) => ({
+                        id: t.id,
+                        content: t.content,
+                        originalScore: t.retrievalScore,
+                    })),
+                }, { topN: hydrated.length });
+                const neuralScores = new Map(rerankerOutput.results.map((r) => [r.id, r.relevanceScore]));
+                for (const trace of hydrated) {
+                    const neural = neuralScores.get(trace.id);
+                    if (neural !== undefined) {
+                        trace.retrievalScore = 0.7 * trace.retrievalScore + 0.3 * neural;
+                    }
+                }
+                // Step-6: split-on-ambiguous refinement.
+                if (this.splitAmbiguousThreshold !== undefined &&
+                    this.splitAmbiguousThreshold > 0 &&
+                    hydrated.length > 0) {
+                    splitDiagnostic = await this.refineAmbiguous(hydrated, neuralScores, query, this.splitAmbiguousThreshold);
+                }
+                hydrated.sort((a, b) => b.retrievalScore - a.retrievalScore);
+            }
+            catch {
+                // Reranker errors are non-critical: keep RRF ordering.
+            }
+        }
+        // Truncate to recallTopK.
+        const truncated = hydrated.slice(0, recallTopK);
+        return this.buildResult(truncated, {
+            candidatesScanned: denseScored.length + sparseResults.length,
+            vectorSearchMs: denseTimings.vectorSearchMs,
+            scoringMs: denseTimings.scoringMs,
+            totalMs: Date.now() - startTime,
+            hypothesis: hypothesisDiagnostic,
+            splitOnAmbiguous: splitDiagnostic,
+        });
+    }
+    /** Assemble the CognitiveRetrievalResult shape. */
+    buildResult(retrieved, d) {
+        return {
+            retrieved,
+            partiallyRetrieved: [],
+            diagnostics: {
+                candidatesScanned: d.candidatesScanned,
+                vectorSearchTimeMs: d.vectorSearchMs,
+                scoringTimeMs: d.scoringMs,
+                totalTimeMs: d.totalMs,
+                ...(d.escalations ? { escalations: d.escalations } : {}),
+                ...(d.hypothesis ? { hyde: { hypothesis: d.hypothesis } } : {}),
+                ...(d.splitOnAmbiguous ? { splitOnAmbiguous: d.splitOnAmbiguous } : {}),
+            },
+        };
+    }
+    /**
+     * Step-6: split bottom-fraction traces by neural score, rescore the
+     * halves, replace a trace's content with its better half IFF the
+     * better half's neural score outranks the original's. Monotonic.
+     *
+     * Modifies `hydrated` in place: `trace.content` and `trace.retrievalScore`
+     * are updated for replaced traces. Returns a diagnostic summary.
+     */
+    async refineAmbiguous(hydrated, neuralScores, query, threshold) {
+        const replacedIds = [];
+        const sortedByNeural = hydrated
+            .map((t) => ({ trace: t, neural: neuralScores.get(t.id) ?? 0 }))
+            .sort((a, b) => a.neural - b.neural);
+        const candidateCount = Math.ceil(hydrated.length * threshold);
+        const candidates = sortedByNeural.slice(0, candidateCount);
+        const splits = [];
+        for (const { trace, neural } of candidates) {
+            const halves = this.splitAtMidpointSentence(trace.content);
+            if (!halves)
+                continue;
+            splits.push({
+                traceId: trace.id,
+                halfAId: `${trace.id}::a`,
+                halfBId: `${trace.id}::b`,
+                halfA: halves[0],
+                halfB: halves[1],
+                originalNeural: neural,
+            });
+        }
+        if (splits.length === 0) {
+            return { threshold, candidateCount, replacedIds };
+        }
+        const halfDocs = splits.flatMap((s) => [
+            { id: s.halfAId, content: s.halfA },
+            { id: s.halfBId, content: s.halfB },
+        ]);
+        let halfScores;
+        try {
+            const halfOut = await this.rerankerService.rerank({ query, documents: halfDocs }, { topN: halfDocs.length });
+            halfScores = new Map(halfOut.results.map((r) => [r.id, r.relevanceScore]));
+        }
+        catch {
+            return { threshold, candidateCount, replacedIds };
+        }
+        const traceById = new Map(hydrated.map((t) => [t.id, t]));
+        for (const s of splits) {
+            const a = halfScores.get(s.halfAId) ?? -Infinity;
+            const b = halfScores.get(s.halfBId) ?? -Infinity;
+            const winningScore = Math.max(a, b);
+            if (winningScore <= s.originalNeural)
+                continue;
+            const winningText = a >= b ? s.halfA : s.halfB;
+            const trace = traceById.get(s.traceId);
+            if (!trace)
+                continue;
+            trace.content = winningText;
+            trace.retrievalScore += 0.3 * (winningScore - s.originalNeural);
+            replacedIds.push(s.traceId);
+        }
+        return { threshold, candidateCount, replacedIds };
+    }
+    /**
+     * Split a string at the sentence boundary nearest its midpoint.
+     * Returns [firstHalf, secondHalf] or null if the string is too short
+     * or no valid boundary is found.
+     */
+    splitAtMidpointSentence(text) {
+        if (text.length < 50)
+            return null;
+        const mid = Math.floor(text.length / 2);
+        const window = Math.floor(text.length * 0.4);
+        const lo = Math.max(0, mid - window);
+        const hi = Math.min(text.length, mid + window);
+        for (let offset = 0; offset <= window; offset++) {
+            for (const sign of [-1, 1]) {
+                const i = mid + sign * offset;
+                if (i < lo || i > hi)
+                    continue;
+                if (i > 0 &&
+                    i < text.length - 1 &&
+                    /[.!?]/.test(text[i]) &&
+                    /\s/.test(text[i + 1])) {
+                    return [text.slice(0, i + 1).trim(), text.slice(i + 1).trim()];
+                }
+            }
+        }
+        const spaceIdx = text.indexOf(' ', mid);
+        if (spaceIdx === -1 || spaceIdx >= text.length - 1)
+            return null;
+        return [text.slice(0, spaceIdx).trim(), text.slice(spaceIdx + 1).trim()];
+    }
+}
+//# sourceMappingURL=HybridRetriever.js.map

package/dist/memory/retrieval/hybrid/HybridRetriever.js.map

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

package/dist/memory/retrieval/hybrid/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @file index.ts
+ * @description Barrel exports for hybrid BM25 + dense retrieval
+ * (Step 3 of the RAG stack sequenced rollout).
+ *
+ * @module agentos/memory/retrieval/hybrid
+ */
+export { HybridRetriever } from './HybridRetriever.js';
+export type { HybridRetrieverOptions, HybridRetrieveOptions, } from './HybridRetriever.js';
+export { reciprocalRankFusion } from './reciprocalRankFusion.js';
+export type { RankedDoc, RRFOptions, RRFResult, } from './reciprocalRankFusion.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/hybrid/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EACV,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,YAAY,EACV,SAAS,EACT,UAAU,EACV,SAAS,GACV,MAAM,2BAA2B,CAAC"}

package/dist/memory/retrieval/hybrid/index.js

@@ -0,0 +1,10 @@
+/**
+ * @file index.ts
+ * @description Barrel exports for hybrid BM25 + dense retrieval
+ * (Step 3 of the RAG stack sequenced rollout).
+ *
+ * @module agentos/memory/retrieval/hybrid
+ */
+export { HybridRetriever } from './HybridRetriever.js';
+export { reciprocalRankFusion } from './reciprocalRankFusion.js';
+//# sourceMappingURL=index.js.map

package/dist/memory/retrieval/hybrid/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/hybrid/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAMvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/memory/retrieval/hybrid/reciprocalRankFusion.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @file reciprocalRankFusion.ts
+ * @description Rank-based fusion of two ranked document lists using
+ * the Reciprocal Rank Fusion (RRF) algorithm (Cormack et al. 2009).
+ *
+ * ## What this does
+ *
+ * Takes two 1-based ranked lists of document ids (one from dense
+ * retrieval, one from sparse retrieval) and merges them into a single
+ * ranked list via:
+ *
+ * ```
+ * score(d) = w_dense / (k + rank_dense(d)) + w_sparse / (k + rank_sparse(d))
+ * ```
+ *
+ * Missing ranks (a doc appearing on only one side) contribute zero
+ * from the other side.
+ *
+ * ## Why rank-based (not score-based)
+ *
+ * Dense scorers (cosine similarity, cognitive composites) and sparse
+ * scorers (BM25) produce values on different scales with different
+ * distributions. Score-weighted fusion requires calibration; rank
+ * fusion sidesteps this entirely. Published RAG literature
+ * consistently prefers RRF over weighted-sum for heterogeneous
+ * retrievers.
+ *
+ * ## Stable ordering
+ *
+ * When two documents have identical RRF scores, they are ordered by
+ * id ascending. Deterministic across process restarts.
+ *
+ * @module agentos/memory/retrieval/hybrid/reciprocalRankFusion
+ */
+/**
+ * One document's position in a ranked retrieval result.
+ */
+export interface RankedDoc {
+    id: string;
+    /** 1-based rank. First result has rank 1. */
+    rank: number;
+}
+/**
+ * Options for {@link reciprocalRankFusion}.
+ */
+export interface RRFOptions {
+    /** Weight on the dense-side rank contribution. Default 0.7. */
+    denseWeight?: number;
+    /** Weight on the sparse-side rank contribution. Default 0.3. */
+    sparseWeight?: number;
+    /**
+     * RRF smoothing constant. Larger k flattens rank differences.
+     * Default 60 per Cormack et al. 2009.
+     */
+    k?: number;
+}
+/**
+ * One merged result from {@link reciprocalRankFusion}.
+ */
+export interface RRFResult {
+    id: string;
+    /** Fused score; higher = more relevant. */
+    score: number;
+    /** Rank in the dense list (undefined if doc was sparse-only). */
+    denseRank?: number;
+    /** Rank in the sparse list (undefined if doc was dense-only). */
+    sparseRank?: number;
+}
+/**
+ * Merge two ranked retrieval results via Reciprocal Rank Fusion.
+ *
+ * @param denseRanked - 1-based ranked list from dense retrieval.
+ * @param sparseRanked - 1-based ranked list from sparse retrieval.
+ * @param options - {@link RRFOptions}; defaults to w_dense=0.7, w_sparse=0.3, k=60.
+ * @returns Merged results sorted by fused score descending, stable
+ *          tiebreak by id ascending.
+ *
+ * @example
+ * ```ts
+ * const dense = [{ id: 'a', rank: 1 }, { id: 'b', rank: 2 }];
+ * const sparse = [{ id: 'b', rank: 1 }, { id: 'c', rank: 2 }];
+ * const merged = reciprocalRankFusion(dense, sparse);
+ * // => [{ id: 'b', score: 0.0162, denseRank: 2, sparseRank: 1 }, ...]
+ * ```
+ */
+export declare function reciprocalRankFusion(denseRanked: RankedDoc[], sparseRanked: RankedDoc[], options?: RRFOptions): RRFResult[];
+//# sourceMappingURL=reciprocalRankFusion.d.ts.map

package/dist/memory/retrieval/hybrid/reciprocalRankFusion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reciprocalRankFusion.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/hybrid/reciprocalRankFusion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,SAAS,EAAE,EACxB,YAAY,EAAE,SAAS,EAAE,EACzB,OAAO,GAAE,UAAe,GACvB,SAAS,EAAE,CAoCb"}

package/dist/memory/retrieval/hybrid/reciprocalRankFusion.js

@@ -0,0 +1,88 @@
+/**
+ * @file reciprocalRankFusion.ts
+ * @description Rank-based fusion of two ranked document lists using
+ * the Reciprocal Rank Fusion (RRF) algorithm (Cormack et al. 2009).
+ *
+ * ## What this does
+ *
+ * Takes two 1-based ranked lists of document ids (one from dense
+ * retrieval, one from sparse retrieval) and merges them into a single
+ * ranked list via:
+ *
+ * ```
+ * score(d) = w_dense / (k + rank_dense(d)) + w_sparse / (k + rank_sparse(d))
+ * ```
+ *
+ * Missing ranks (a doc appearing on only one side) contribute zero
+ * from the other side.
+ *
+ * ## Why rank-based (not score-based)
+ *
+ * Dense scorers (cosine similarity, cognitive composites) and sparse
+ * scorers (BM25) produce values on different scales with different
+ * distributions. Score-weighted fusion requires calibration; rank
+ * fusion sidesteps this entirely. Published RAG literature
+ * consistently prefers RRF over weighted-sum for heterogeneous
+ * retrievers.
+ *
+ * ## Stable ordering
+ *
+ * When two documents have identical RRF scores, they are ordered by
+ * id ascending. Deterministic across process restarts.
+ *
+ * @module agentos/memory/retrieval/hybrid/reciprocalRankFusion
+ */
+/**
+ * Merge two ranked retrieval results via Reciprocal Rank Fusion.
+ *
+ * @param denseRanked - 1-based ranked list from dense retrieval.
+ * @param sparseRanked - 1-based ranked list from sparse retrieval.
+ * @param options - {@link RRFOptions}; defaults to w_dense=0.7, w_sparse=0.3, k=60.
+ * @returns Merged results sorted by fused score descending, stable
+ *          tiebreak by id ascending.
+ *
+ * @example
+ * ```ts
+ * const dense = [{ id: 'a', rank: 1 }, { id: 'b', rank: 2 }];
+ * const sparse = [{ id: 'b', rank: 1 }, { id: 'c', rank: 2 }];
+ * const merged = reciprocalRankFusion(dense, sparse);
+ * // => [{ id: 'b', score: 0.0162, denseRank: 2, sparseRank: 1 }, ...]
+ * ```
+ */
+export function reciprocalRankFusion(denseRanked, sparseRanked, options = {}) {
+    const wDense = options.denseWeight ?? 0.7;
+    const wSparse = options.sparseWeight ?? 0.3;
+    const k = options.k ?? 60;
+    const byId = new Map();
+    for (const { id, rank } of denseRanked) {
+        const prev = byId.get(id);
+        const denseContribution = wDense / (k + rank);
+        if (prev) {
+            prev.score += denseContribution;
+            prev.denseRank = rank;
+        }
+        else {
+            byId.set(id, { id, score: denseContribution, denseRank: rank });
+        }
+    }
+    for (const { id, rank } of sparseRanked) {
+        const prev = byId.get(id);
+        const sparseContribution = wSparse / (k + rank);
+        if (prev) {
+            prev.score += sparseContribution;
+            prev.sparseRank = rank;
+        }
+        else {
+            byId.set(id, { id, score: sparseContribution, sparseRank: rank });
+        }
+    }
+    const merged = Array.from(byId.values());
+    // Sort by score desc, stable tiebreak by id asc for determinism.
+    merged.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    });
+    return merged;
+}
+//# sourceMappingURL=reciprocalRankFusion.js.map

package/dist/memory/retrieval/hybrid/reciprocalRankFusion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reciprocalRankFusion.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/hybrid/reciprocalRankFusion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAuCH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,oBAAoB,CAClC,WAAwB,EACxB,YAAyB,EACzB,UAAsB,EAAE;IAExB,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,IAAI,GAAG,CAAC;IAC1C,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,IAAI,GAAG,CAAC;IAC5C,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;IAE1B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAqB,CAAC;IAE1C,KAAK,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,WAAW,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1B,MAAM,iBAAiB,GAAG,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QAC9C,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,CAAC,KAAK,IAAI,iBAAiB,CAAC;YAChC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACxB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IAED,KAAK,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,YAAY,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1B,MAAM,kBAAkB,GAAG,OAAO,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QAChD,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,CAAC,KAAK,IAAI,kBAAkB,CAAC;YACjC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACzB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,iEAAiE;IACjE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACnB,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK;YAAE,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;QAClD,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/memory/retrieval/session/SessionRetriever.d.ts

@@ -0,0 +1,123 @@
+/**
+ * @file SessionRetriever.ts
+ * @description Two-stage hierarchical retriever: select top-K sessions
+ * by summary similarity, then return top-M chunks per selected session
+ * from the underlying {@link MemoryStore}. Optional rerank pass over
+ * the merged pool. Returns a standard `CognitiveRetrievalResult` so
+ * downstream consumers (prompt assembly, bench adapters) don't change
+ * shape.
+ *
+ * ## What this does
+ *
+ * Implements the xMemory (arxiv 2602.02007v3) / TACITREE (EMNLP 2025)
+ * hierarchical-retrieval pattern, session-granularity variant: a
+ * coverage mechanism that guarantees the reader sees chunks from
+ * multiple distinct sessions on multi-session queries. Single-stage
+ * retrieval tends to cluster on the single most-relevant session,
+ * missing multi-session evidence; this retriever forces diversity by
+ * construction.
+ *
+ * ## Why a separate class, not a `CognitiveMemoryManager` option
+ *
+ * Keeps the existing manager retrieval path untouched. Step 2 MVP.
+ * Future steps may promote session-level retrieval into the manager
+ * once it's proven on benchmarks.
+ *
+ * ## Two-stage flow
+ *
+ * 1. Stage 1: `summaryStore.querySessions(query, topK=K)` — select
+ *    top-K sessions.
+ * 2. Stage 2: single `memoryStore.query(query, topK=K*M*OVER_FETCH)` —
+ *    over-fetch to ensure chunks from Stage-1 sessions land in the
+ *    candidate pool.
+ * 3. Post-filter: keep only traces whose `bench-session:<id>` tag
+ *    matches a Stage-1 session.
+ * 4. Group by session, take top-`chunksPerSession` (M) per session.
+ * 5. Optional rerank over the merged pool.
+ * 6. Truncate to `recallTopK`.
+ *
+ * ## Fallbacks
+ *
+ * - Stage 1 returns zero sessions (cold scope, no summaries indexed):
+ *   fall through to `memoryStore.query` and return its top-
+ *   `recallTopK` directly. Diagnostics tag
+ *   `escalations: ['session-retriever:stage1-empty']`.
+ * - Stage 2 post-filter wipes the pool: return the raw Stage-2 top-
+ *   `recallTopK` without session filtering. Diagnostics tag
+ *   `escalations: ['session-retriever:stage2-empty']`.
+ *
+ * @module agentos/memory/retrieval/session/SessionRetriever
+ */
+import type { IEmbeddingManager } from '../../../core/embeddings/IEmbeddingManager.js';
+import type { MemoryStore } from '../store/MemoryStore.js';
+import type { RerankerService } from '../../../rag/reranking/RerankerService.js';
+import type { CognitiveRetrievalResult, MemoryScope } from '../../core/types.js';
+import type { PADState } from '../../core/config.js';
+import type { SessionSummaryStore } from './SessionSummaryStore.js';
+/**
+ * Options for constructing a {@link SessionRetriever}.
+ */
+export interface SessionRetrieverOptions {
+    summaryStore: SessionSummaryStore;
+    memoryStore: MemoryStore;
+    embeddingManager: IEmbeddingManager;
+    /** Optional reranker. When provided, the merged chunk pool is reranked before truncation. */
+    rerankerService?: RerankerService;
+    /** Default K (sessions to select in Stage 1). @default 5 */
+    defaultTopSessions?: number;
+    /** Default M (chunks per session in Stage 2). @default 3 */
+    defaultChunksPerSession?: number;
+}
+/**
+ * Per-call options for {@link SessionRetriever.retrieve}.
+ */
+export interface SessionRetrieveOptions {
+    /** Override K (sessions). */
+    topSessions?: number;
+    /** Override M (chunks per session). */
+    chunksPerSession?: number;
+    /** Final truncation after merge and rerank. @default 10 */
+    recallTopK?: number;
+    /** Prefix for parsing session IDs off trace tags. @default 'bench-session:' */
+    sessionTagPrefix?: string;
+}
+/**
+ * Two-stage hierarchical retriever.
+ *
+ * @example
+ * ```ts
+ * const retriever = new SessionRetriever({
+ *   summaryStore,
+ *   memoryStore,
+ *   embeddingManager,
+ *   rerankerService,
+ *   defaultTopSessions: 5,
+ *   defaultChunksPerSession: 3,
+ * });
+ * const result = await retriever.retrieve(
+ *   'What did the user say about their rescue dog?',
+ *   { valence: 0, arousal: 0, dominance: 0 },
+ *   { scope: 'user', scopeId: 'u42' },
+ *   { recallTopK: 10 },
+ * );
+ * ```
+ */
+export declare class SessionRetriever {
+    private readonly opts;
+    constructor(opts: SessionRetrieverOptions);
+    /**
+     * Two-stage retrieve. Returns a `CognitiveRetrievalResult`
+     * compatible with the existing `CognitiveMemoryManager.retrieve`
+     * shape.
+     *
+     * Diagnostics are best-effort: timings reflect wall-clock of each
+     * stage, not the cognitive-scorer internal accounting.
+     */
+    retrieve(query: string, mood: PADState, scope: {
+        scope: MemoryScope;
+        scopeId: string;
+    }, options?: SessionRetrieveOptions): Promise<CognitiveRetrievalResult>;
+    /** Assemble the CognitiveRetrievalResult shape. */
+    private buildResult;
+}
+//# sourceMappingURL=SessionRetriever.d.ts.map

package/dist/memory/retrieval/session/SessionRetriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionRetriever.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/session/SessionRetriever.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+CAA+C,CAAC;AACvF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,KAAK,EACV,wBAAwB,EACxB,WAAW,EAEZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAapE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,mBAAmB,CAAC;IAClC,WAAW,EAAE,WAAW,CAAC;IACzB,gBAAgB,EAAE,iBAAiB,CAAC;IACpC,6FAA6F;IAC7F,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,4DAA4D;IAC5D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,4DAA4D;IAC5D,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,6BAA6B;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAEnB;gBAEU,IAAI,EAAE,uBAAuB;IAWzC;;;;;;;OAOG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAC9C,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,wBAAwB,CAAC;IAsHpC,mDAAmD;IACnD,OAAO,CAAC,WAAW;CAsBpB"}