@framers/agentos 0.1.247 → 0.1.249

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"}

package/dist/memory/retrieval/session/SessionRetriever.js

@@ -0,0 +1,220 @@
+/**
+ * @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
+ */
+/**
+ * Over-fetch multiplier applied to the Stage-2 `MemoryStore.query`
+ * topK, so post-filtering by session tag has enough candidates to
+ * find chunks from every Stage-1 session.
+ *
+ * At the defaults (K=5 sessions × M=3 chunks), Stage-2 requests
+ * `5 * 3 * 3 = 45` candidates. Empirically this is enough overhead
+ * even when the question is topically dominated by one session.
+ */
+const STAGE2_OVER_FETCH = 3;
+/**
+ * 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 class SessionRetriever {
+    constructor(opts) {
+        this.opts = {
+            summaryStore: opts.summaryStore,
+            memoryStore: opts.memoryStore,
+            embeddingManager: opts.embeddingManager,
+            rerankerService: opts.rerankerService,
+            defaultTopSessions: opts.defaultTopSessions ?? 5,
+            defaultChunksPerSession: opts.defaultChunksPerSession ?? 3,
+        };
+    }
+    /**
+     * 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.
+     */
+    async retrieve(query, mood, scope, options = {}) {
+        const startTime = Date.now();
+        const K = options.topSessions ?? this.opts.defaultTopSessions;
+        const M = options.chunksPerSession ?? this.opts.defaultChunksPerSession;
+        const recallTopK = options.recallTopK ?? 10;
+        const tagPrefix = options.sessionTagPrefix ?? 'bench-session:';
+        // Stage 1: select top-K sessions by summary similarity.
+        const stage1Start = Date.now();
+        const sessions = await this.opts.summaryStore.querySessions(query, {
+            scope: scope.scope,
+            scopeId: scope.scopeId,
+            topK: K,
+        });
+        const stage1Ms = Date.now() - stage1Start;
+        // Stage-1 fallback: no summaries indexed for this scope.
+        if (sessions.length === 0) {
+            const { scored, timings } = await this.opts.memoryStore.query(query, mood, {
+                topK: recallTopK,
+                scopes: [scope],
+            });
+            return this.buildResult(scored.slice(0, recallTopK), {
+                fallback: 'stage1-empty',
+                candidatesScanned: scored.length,
+                vectorSearchMs: timings.vectorSearchMs,
+                scoringMs: timings.scoringMs,
+                totalMs: Date.now() - startTime,
+            });
+        }
+        // Stage 2: over-fetch from MemoryStore so post-filter has enough
+        // candidates per session.
+        const overFetchTopK = K * M * STAGE2_OVER_FETCH;
+        const { scored: stage2Pool, timings: stage2Timings } = await this.opts.memoryStore.query(query, mood, { topK: overFetchTopK, scopes: [scope] });
+        // Post-filter: keep only traces whose bench-session tag matches a
+        // Stage-1 session. Group by session.
+        const selectedIds = new Set(sessions.map((s) => s.sessionId));
+        const bySession = new Map();
+        for (const trace of stage2Pool) {
+            const tag = trace.tags.find((t) => t.startsWith(tagPrefix));
+            if (!tag)
+                continue;
+            const sid = tag.slice(tagPrefix.length);
+            if (!selectedIds.has(sid))
+                continue;
+            const bucket = bySession.get(sid) ?? [];
+            bucket.push(trace);
+            bySession.set(sid, bucket);
+        }
+        // Stage-2 fallback: post-filter wiped the pool. Return raw Stage-2
+        // top-recallTopK without session filtering.
+        if (bySession.size === 0) {
+            return this.buildResult(stage2Pool.slice(0, recallTopK), {
+                fallback: 'stage2-empty',
+                candidatesScanned: stage2Pool.length,
+                vectorSearchMs: stage2Timings.vectorSearchMs,
+                scoringMs: stage2Timings.scoringMs,
+                totalMs: Date.now() - startTime,
+            });
+        }
+        // Take top-M per session (bucket is already sorted by retrieval
+        // score — MemoryStore.query returns scored traces in descending
+        // order).
+        const merged = [];
+        for (const [, bucket] of bySession)
+            merged.push(...bucket.slice(0, M));
+        // Optional rerank over the merged pool.
+        const final = merged;
+        if (this.opts.rerankerService && final.length > 0) {
+            try {
+                const rerankerOutput = await this.opts.rerankerService.rerank({
+                    query,
+                    documents: final.map((t) => ({
+                        id: t.id,
+                        content: t.content,
+                        originalScore: t.retrievalScore,
+                    })),
+                }, { topN: final.length });
+                const rerankedScores = new Map(rerankerOutput.results.map((r) => [r.id, r.relevanceScore]));
+                for (const trace of final) {
+                    const neural = rerankedScores.get(trace.id);
+                    if (neural !== undefined) {
+                        // Blend identical to CognitiveMemoryManager.retrieve: 0.7 cognitive + 0.3 neural.
+                        trace.retrievalScore = 0.7 * trace.retrievalScore + 0.3 * neural;
+                    }
+                }
+                final.sort((a, b) => b.retrievalScore - a.retrievalScore);
+            }
+            catch {
+                // Reranker errors are non-critical; degrade to cognitive-only ordering.
+            }
+        }
+        else {
+            // No rerank: sort by cognitive score (bucket grouping left order
+            // per-session, not global).
+            final.sort((a, b) => b.retrievalScore - a.retrievalScore);
+        }
+        // Truncate to recallTopK.
+        const truncated = final.slice(0, recallTopK);
+        return this.buildResult(truncated, {
+            candidatesScanned: stage2Pool.length,
+            vectorSearchMs: stage2Timings.vectorSearchMs + stage1Ms,
+            scoringMs: stage2Timings.scoringMs,
+            totalMs: Date.now() - startTime,
+        });
+    }
+    /** Assemble the CognitiveRetrievalResult shape. */
+    buildResult(retrieved, d) {
+        return {
+            retrieved,
+            partiallyRetrieved: [],
+            diagnostics: {
+                candidatesScanned: d.candidatesScanned,
+                vectorSearchTimeMs: d.vectorSearchMs,
+                scoringTimeMs: d.scoringMs,
+                totalTimeMs: d.totalMs,
+                ...(d.fallback ? { escalations: [`session-retriever:${d.fallback}`] } : {}),
+            },
+        };
+    }
+}
+//# sourceMappingURL=SessionRetriever.js.map

package/dist/memory/retrieval/session/SessionRetriever.js.map

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

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

@@ -0,0 +1,122 @@
+/**
+ * @file SessionSummaryStore.ts
+ * @description Vector store for session-level summaries, used by
+ * {@link SessionRetriever} to select top-K relevant sessions at
+ * retrieval time before drilling into chunk-level results.
+ *
+ * ## What this does
+ *
+ * Maintains a per-scope vector collection
+ * `<collectionPrefix>_<scope>_<scopeId>` (default prefix
+ * `cogmem_sessions`) with one vector per unique session. Each vector
+ * is the embedding of that session's {@link SessionSummarizer}
+ * output: a 50-100 token dense fact-laden summary.
+ *
+ * ## Why a dedicated collection
+ *
+ * Session summaries are a structurally different retrieval target
+ * than individual memory traces: there's one per conversation thread,
+ * they live longer, and they want to be searched in their own metric
+ * space without dilution from per-chunk vectors. A dedicated
+ * collection also lets {@link SessionRetriever} do Stage 1 session
+ * selection with a single cheap vector search, independent of the
+ * chunk-level trace store.
+ *
+ * ## Relation to Anthropic contextual retrieval
+ *
+ * `SessionSummarizer` implements the Anthropic Sep-2024
+ * contextual-retrieval pattern at session granularity: it prepends
+ * a summary to every chunk before embedding. This store is the
+ * retrieval-time counterpart. It lets callers search the summaries
+ * directly rather than relying on the prepended-summary chunks to
+ * surface via their own query embeddings. Together they form the
+ * `SessionRetriever` two-stage flow documented in the Step 2 design
+ * spec.
+ *
+ * @module agentos/memory/retrieval/session/SessionSummaryStore
+ */
+import type { IVectorStore } from '../../../core/vector-store/IVectorStore.js';
+import type { IEmbeddingManager } from '../../../core/embeddings/IEmbeddingManager.js';
+import type { MemoryScope } from '../../core/types.js';
+/**
+ * Options for constructing a {@link SessionSummaryStore}.
+ */
+export interface SessionSummaryStoreOptions {
+    /** Vector store to use for the summary collection. */
+    vectorStore: IVectorStore;
+    /** Embedding manager shared with the rest of the memory stack (reuse for cache hits). */
+    embeddingManager: IEmbeddingManager;
+    /**
+     * Collection-name prefix. Final collection is
+     * `<prefix>_<scope>_<scopeId>`.
+     * @default 'cogmem_sessions'
+     */
+    collectionPrefix?: string;
+}
+/**
+ * Input for {@link SessionSummaryStore.indexSession}.
+ */
+export interface IndexSessionInput {
+    scope: MemoryScope;
+    scopeId: string;
+    sessionId: string;
+    /** The summary text produced by `SessionSummarizer`. Must be non-empty. */
+    summary: string;
+    /** Optional ISO date for the session. Stored for future temporal filtering. */
+    sessionDate?: string;
+}
+/**
+ * One row from {@link SessionSummaryStore.querySessions}.
+ */
+export interface QueriedSession {
+    sessionId: string;
+    /** Similarity in the vector store's configured metric (cosine by default, range [-1, 1]). */
+    similarityScore: number;
+}
+/**
+ * Dedicated vector store wrapper for session-level summaries.
+ *
+ * @example
+ * ```ts
+ * const store = new SessionSummaryStore({ vectorStore, embeddingManager });
+ * await store.indexSession({
+ *   scope: 'user', scopeId: 'u42', sessionId: 's-7',
+ *   summary: 'User discussed adopting a rescue dog from Portland shelter...',
+ * });
+ * const hits = await store.querySessions('rescue dog adoption', {
+ *   scope: 'user', scopeId: 'u42', topK: 5,
+ * });
+ * ```
+ */
+export declare class SessionSummaryStore {
+    private readonly vectorStore;
+    private readonly embeddingManager;
+    private readonly collectionPrefix;
+    constructor(opts: SessionSummaryStoreOptions);
+    /**
+     * Embed the summary and upsert into the scope-specific collection.
+     * Upsert is idempotent: re-indexing the same `sessionId` replaces
+     * the prior vector rather than appending a duplicate.
+     */
+    indexSession(input: IndexSessionInput): Promise<void>;
+    /**
+     * Embed the query and return the top-K sessions for the given
+     * scope, ordered by descending similarity. Returns `[]` when the
+     * collection does not yet exist (cold scope).
+     */
+    querySessions(query: string, options: {
+        scope: MemoryScope;
+        scopeId: string;
+        topK: number;
+    }): Promise<QueriedSession[]>;
+    /** Compose the per-scope collection name. */
+    private collectionName;
+    /**
+     * Lazily create the collection with the embedding dimension from
+     * the first indexed vector. Idempotent on the `InMemoryVectorStore`
+     * implementation; other providers' `createCollection` variants
+     * honour `overwriteIfExists: false`.
+     */
+    private ensureCollection;
+}
+//# sourceMappingURL=SessionSummaryStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SessionSummaryStore.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/session/SessionSummaryStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EACV,YAAY,EAEb,MAAM,4CAA4C,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+CAA+C,CAAC;AACvF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,sDAAsD;IACtD,WAAW,EAAE,YAAY,CAAC;IAC1B,yFAAyF;IACzF,gBAAgB,EAAE,iBAAiB,CAAC;IACpC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,6FAA6F;IAC7F,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAe;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAoB;IACrD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,IAAI,EAAE,0BAA0B;IAM5C;;;;OAIG;IACG,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB3D;;;;OAIG;IACG,aAAa,CACjB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAC7D,OAAO,CAAC,cAAc,EAAE,CAAC;IAwB5B,6CAA6C;IAC7C,OAAO,CAAC,cAAc;IAItB;;;;;OAKG;YACW,gBAAgB;CAc/B"}