@framers/agentos 0.1.247 → 0.1.249

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@framers/agentos",
-  "version": "0.1.247",
+  "version": "0.1.249",
   "description": "Modular AgentOS orchestration library",
   "type": "module",
   "main": "dist/index.js",