@framers/agentos 0.1.246 → 0.1.248

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

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

@@ -0,0 +1,142 @@
+/**
+ * @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
+ */
+/**
+ * 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 class SessionSummaryStore {
+    constructor(opts) {
+        this.vectorStore = opts.vectorStore;
+        this.embeddingManager = opts.embeddingManager;
+        this.collectionPrefix = opts.collectionPrefix ?? 'cogmem_sessions';
+    }
+    /**
+     * 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.
+     */
+    async indexSession(input) {
+        if (!input.summary || input.summary.trim().length === 0)
+            return;
+        const collection = this.collectionName(input.scope, input.scopeId);
+        const { embeddings } = await this.embeddingManager.generateEmbeddings({
+            texts: input.summary,
+        });
+        const embedding = embeddings[0];
+        await this.ensureCollection(collection, embedding.length);
+        const doc = {
+            id: input.sessionId,
+            textContent: input.summary,
+            embedding,
+            metadata: {
+                sessionId: input.sessionId,
+                scopeId: input.scopeId,
+                createdAt: Date.now(),
+                ...(input.sessionDate ? { sessionDate: input.sessionDate } : {}),
+            },
+        };
+        await this.vectorStore.upsert(collection, [doc]);
+    }
+    /**
+     * 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).
+     */
+    async querySessions(query, options) {
+        const collection = this.collectionName(options.scope, options.scopeId);
+        const exists = this.vectorStore.collectionExists
+            ? await this.vectorStore.collectionExists(collection)
+            : true;
+        if (!exists)
+            return [];
+        const { embeddings } = await this.embeddingManager.generateEmbeddings({ texts: query });
+        const queryEmbedding = embeddings[0];
+        try {
+            const results = await this.vectorStore.query(collection, queryEmbedding, {
+                topK: options.topK,
+                includeMetadata: true,
+            });
+            return results.documents.map((d) => ({
+                sessionId: d.metadata?.sessionId ?? d.id,
+                similarityScore: d.similarityScore ?? 0,
+            }));
+        }
+        catch {
+            // Collection may have been dropped between the existence check
+            // and the query. Degrade to empty rather than throwing.
+            return [];
+        }
+    }
+    /** Compose the per-scope collection name. */
+    collectionName(scope, scopeId) {
+        return `${this.collectionPrefix}_${scope}_${scopeId}`;
+    }
+    /**
+     * 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`.
+     */
+    async ensureCollection(collection, dim) {
+        try {
+            const exists = this.vectorStore.collectionExists
+                ? await this.vectorStore.collectionExists(collection)
+                : true;
+            if (!exists) {
+                await this.vectorStore.createCollection?.(collection, dim, {
+                    overwriteIfExists: false,
+                });
+            }
+        }
+        catch {
+            // Some providers auto-create on first upsert — swallow here.
+        }
+    }
+}
+//# sourceMappingURL=SessionSummaryStore.js.map

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

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

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

@@ -0,0 +1,12 @@
+/**
+ * @file index.ts
+ * @description Barrel exports for session-level hierarchical
+ * retrieval (Step 2 of the RAG stack sequenced rollout).
+ *
+ * @module agentos/memory/retrieval/session
+ */
+export { SessionSummaryStore } from './SessionSummaryStore.js';
+export type { SessionSummaryStoreOptions, IndexSessionInput, QueriedSession, } from './SessionSummaryStore.js';
+export { SessionRetriever } from './SessionRetriever.js';
+export type { SessionRetrieverOptions, SessionRetrieveOptions, } from './SessionRetriever.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EACV,0BAA0B,EAC1B,iBAAiB,EACjB,cAAc,GACf,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EACV,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,uBAAuB,CAAC"}

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

@@ -0,0 +1,10 @@
+/**
+ * @file index.ts
+ * @description Barrel exports for session-level hierarchical
+ * retrieval (Step 2 of the RAG stack sequenced rollout).
+ *
+ * @module agentos/memory/retrieval/session
+ */
+export { SessionSummaryStore } from './SessionSummaryStore.js';
+export { SessionRetriever } from './SessionRetriever.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAO/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/memory/retrieval/store/MemoryStore.d.ts

@@ -72,6 +72,15 @@ export declare class MemoryStore {
     query(queryText: string, currentMood: PADState, options?: CognitiveRetrievalOptions): Promise<{
         scored: ScoredMemoryTrace[];
         partial: PartiallyRetrievedTrace[];
+        /**
+         * Per-stage wall-clock timings. Surfaced so
+         * {@link CognitiveMemoryManager} can populate its diagnostics
+         * with real numbers instead of the former 0-placeholder.
+         */
+        timings: {
+            vectorSearchMs: number;
+            scoringMs: number;
+        };
     }>;
     /**
      * Record that a memory was accessed (retrieved).

package/dist/memory/retrieval/store/MemoryStore.d.ts.map

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

package/dist/memory/retrieval/store/MemoryStore.js

@@ -217,7 +217,7 @@ export class MemoryStore {
         // Determine which collections to search
         const scopes = options.scopes?.length ? options.scopes : this.getKnownScopes();
         if (scopes.length === 0) {
-            return { scored: [], partial: [] };
+            return { scored: [], partial: [], timings: { vectorSearchMs: 0, scoringMs: 0 } };
         }
         // Generate query embedding
         const embeddingResponse = await this.config.embeddingManager.generateEmbeddings({
@@ -237,6 +237,7 @@ export class MemoryStore {
         }
         // Search across scopes
         const allCandidates = [];
+        const vectorSearchStart = Date.now();
         for (const { scope, scopeId } of scopes) {
             const collection = collectionName(this.config.collectionPrefix, scope, scopeId);
             try {
@@ -275,6 +276,7 @@ export class MemoryStore {
                 // Collection may not exist yet; skip
             }
         }
+        const vectorSearchMs = Date.now() - vectorSearchStart;
         // Score and rank — optional per-call scoringWeights override
         // enables ablation studies (zero one signal at a time).
         const effectiveWeights = options.scoringWeights
@@ -287,14 +289,16 @@ export class MemoryStore {
             decayConfig: this.decay,
             weights: effectiveWeights,
         };
+        const scoringStart = Date.now();
         const scored = scoreAndRankTraces(allCandidates, scoringContext).slice(0, topK);
         const partial = detectPartiallyRetrieved(allCandidates, now);
+        const scoringMs = Date.now() - scoringStart;
         // Cognitive mechanisms: RIF + FOK
         if (this.mechanismsEngine && scored.length > 0) {
             const cutoff = scored[scored.length - 1].retrievalScore;
             this.mechanismsEngine.onRetrieval(scored, allCandidates, cutoff, []);
         }
-        return { scored, partial };
+        return { scored, partial, timings: { vectorSearchMs, scoringMs } };
     }
     // =========================================================================
     // Access tracking