@mastra/mongodb 1.22.0 → 1.23.0-alpha.1

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-mongodb
 description: Documentation for @mastra/mongodb. Use when working with @mastra/mongodb APIs, configuration, or implementation.
 metadata:
   package: "@mastra/mongodb"
-  version: "1.22.0"
+  version: "1.23.0-alpha.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.22.0",
+  "version": "1.23.0-alpha.1",
   "package": "@mastra/mongodb",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-memory-semantic-recall.md

@@ -411,11 +411,11 @@ PostgreSQL supports both IVFFlat and HNSW indexes. By default, Mastra creates an
 
 ```typescript
 import { Memory } from '@mastra/memory'
-import { PgStore, PgVector } from '@mastra/pg'
+import { PostgresStore, PgVector } from '@mastra/pg'
 
 const agent = new Agent({
   memory: new Memory({
-    storage: new PgStore({
+    storage: new PostgresStore({
       id: 'agent-storage',
       connectionString: process.env.DATABASE_URL,
     }),

package/dist/docs/references/docs-memory-working-memory.md

@@ -272,6 +272,22 @@ Schema-based working memory uses **merge semantics**, meaning the agent only nee
 - **Set a field to `null` to delete it:** This explicitly removes the field from memory
 - **Arrays are replaced entirely:** When an array field is provided, it replaces the existing array (arrays aren't merged element-by-element)
 
+### Concurrent updates
+
+With `scope: 'resource'` and a storage adapter that supports atomic merges (currently `@mastra/pg`), each merge runs inside a row-locked database transaction. Concurrent updates to different fields from separate processes are all kept. Other adapters merge in the application, which only serializes writers inside a single process.
+
+To merge a partial update from your own code, call `memory.mergeWorkingMemory()`:
+
+```typescript
+await memory.mergeWorkingMemory({
+  threadId: 'thread-1',
+  resourceId: 'user-123',
+  workingMemory: { preferences: { tone: 'formal' } },
+})
+```
+
+It throws if working memory isn't schema-based and resource-scoped, or if the storage adapter doesn't support atomic merges. Check `await memory.supportsAtomicWorkingMemoryMerge()` first if you need to fall back.
+
 ## Choosing between template and schema
 
 - Use a **template** (Markdown) if you want the agent to maintain memory as a free-form text block, such as a user profile or scratchpad. Templates use **replace semantics**: the agent must provide the complete memory content on each update.

package/dist/docs/references/reference-rag-retrieval.md

@@ -50,23 +50,25 @@ console.log(results)
 
 The `topK` parameter specifies the maximum number of most similar results to return from the vector search.
 
-Results include both the text content and a similarity score:
+Each result includes an `id`, a similarity `score`, and the stored `metadata`. When you store chunk text in metadata, it's available as `metadata.text`:
 
 ```ts
 [
   {
-    text: 'Climate change poses significant challenges...',
+    id: 'chunk-1',
     score: 0.89,
-    metadata: { source: 'article1.txt' },
+    metadata: { text: 'Climate change poses significant challenges...', source: 'article1.txt' },
   },
   {
-    text: 'Rising temperatures affect crop yields...',
+    id: 'chunk-2',
     score: 0.82,
-    metadata: { source: 'article1.txt' },
+    metadata: { text: 'Rising temperatures affect crop yields...', source: 'article1.txt' },
   },
 ]
 ```
 
+Results can also include `vector` when you set `includeVector: true`, and `document` when the store returns the original document (Chroma only).
+
 ## Advanced retrieval options
 
 ### Metadata Filtering

package/dist/docs/references/reference-rag-vector-databases.md

@@ -230,7 +230,7 @@ await store.upsert({
 **libSQL**:
 
 ```ts
-import { LibSQLVector } from '@mastra/core/vector/libsql'
+import { LibSQLVector } from '@mastra/libsql'
 
 const store = new LibSQLVector({
   id: 'libsql-vector',

package/dist/index.cjs

@@ -9,7 +9,7 @@ let _mastra_core_agent = require("@mastra/core/agent");
 let _mastra_core_evals = require("@mastra/core/evals");
 let _mastra_core_storage_domains_skills = require("@mastra/core/storage/domains/skills");
 //#region package.json
-var version = "1.22.0";
+var version = "1.23.0-alpha.1";
 //#endregion
 //#region src/vector/filter.ts
 /**
@@ -4764,13 +4764,26 @@ async function assertKnowledgeDescriptionWithinBoundCompat(description) {
 	}
 	assertWithinBound(description);
 }
+let assertRecordTextWithinBound;
+async function assertKnowledgeRecordTextWithinBoundCompat(text) {
+	if (!assertRecordTextWithinBound) assertRecordTextWithinBound = (await import("@mastra/core/storage")).assertKnowledgeRecordTextWithinBound ?? ((value) => {
+		if (value.length > 1e3) throw new Error("Knowledge record text exceeds the 1000 UTF-16 code unit limit; split it into separate facts or summarize it");
+	});
+	assertRecordTextWithinBound(text);
+}
 const cloneScope = (scope) => [...scope];
 const canonicalName = (name) => name.trim().toLocaleLowerCase();
 const nodeReferenceId = (node) => typeof node === "string" ? node : node.id;
 const sessionOptions = (session) => session ? { session } : {};
 function visibleScopeKeys(scope) {
 	const canonical = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(scope);
-	return canonical.map((_, index) => (0, _mastra_core_storage.knowledgeScopeKey)(canonical.slice(0, index + 1)));
+	const subsets = [[]];
+	for (const entry of canonical) subsets.push(...subsets.map((subset) => [...subset, entry]));
+	const keys = /* @__PURE__ */ new Set();
+	for (const subset of subsets.slice(1)) try {
+		keys.add((0, _mastra_core_storage.knowledgeScopeKey)(subset));
+	} catch {}
+	return [...keys];
 }
 function recordCursorFilter(cursor, expected) {
 	const parsed = (0, _mastra_core_storage.parseKnowledgeNodeCursor)(cursor, expected);
@@ -4806,7 +4819,6 @@ function recordFromDocument(row) {
 		sourceThreadId: String(row.sourceThreadId),
 		capturedAt: new Date(row.capturedAt),
 		when: row.when ? new Date(row.when) : void 0,
-		maxScope: row.maxScope ?? void 0,
 		metadata: row.metadata ?? void 0,
 		deletedAt: row.deletedAt ? new Date(row.deletedAt) : void 0,
 		deletedBy: row.deletedBy ?? void 0
@@ -4829,12 +4841,12 @@ function outboxFromDocument(row) {
 		completedAt: row.completedAt ? new Date(row.completedAt) : void 0
 	};
 }
+const KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE = "Knowledge curation cursors were removed: observation-time curate is the only Knowledge writer and needs no cursor.";
 var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.KnowledgeStorage {
 	static MANAGED_COLLECTIONS = [
 		_mastra_core_storage.TABLE_KNOWLEDGE_NODES,
 		_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS,
 		_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS,
-		_mastra_core_storage.TABLE_KNOWLEDGE_CURSORS,
 		_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY,
 		_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX
 	];
@@ -4847,7 +4859,6 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 		const nodes = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_NODES);
 		const knowledge = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_RECORDS);
 		const mentions = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS);
-		const cursors = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_CURSORS);
 		const activity = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY);
 		const outbox = await this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_SEMANTIC_OUTBOX);
 		await Promise.all([
@@ -4860,6 +4871,10 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 				scopeKey: 1,
 				type: 1
 			}),
+			nodes.createIndex({
+				type: 1,
+				canonicalName: 1
+			}),
 			knowledge.createIndex({
 				node: 1,
 				id: -1
@@ -4868,6 +4883,10 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 				sourceThreadId: 1,
 				id: -1
 			}),
+			knowledge.createIndex({
+				scopeKey: 1,
+				id: -1
+			}),
 			mentions.createIndex({
 				sourceType: 1,
 				sourceId: 1,
@@ -4878,11 +4897,11 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 				sourceType: 1,
 				sourceId: 1
 			}),
-			cursors.createIndex({
-				sourceThreadId: 1,
-				agent: 1
-			}, { unique: true }),
 			activity.createIndex({ id: -1 }),
+			activity.createIndex({
+				scopeKey: 1,
+				id: -1
+			}),
 			outbox.createIndex({ idempotencyKey: 1 }, { unique: true }),
 			outbox.createIndex({
 				status: 1,
@@ -4898,6 +4917,11 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 	}
 	async createNode(input) {
 		await assertKnowledgeDescriptionWithinBoundCompat(input.description);
+		if (input.scopeAddresses?.length) {
+			const error = /* @__PURE__ */ new Error("This Knowledge storage adapter does not expose structural scope placement.");
+			error.name = "KnowledgeUnsupportedCapabilityError";
+			throw error;
+		}
 		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
 		return this.#connector.withTransaction(async (session) => {
 			const existing = await this.#getNodeByName(input.name, scope, session);
@@ -5090,9 +5114,9 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 		});
 	}
 	async appendKnowledge(input) {
+		await assertKnowledgeRecordTextWithinBoundCompat(input.text);
 		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
 		const defaultScope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.defaultScope);
-		(0, _mastra_core_storage.assertKnowledgeScopeWithinCeiling)(scope, input.maxScope);
 		return this.#connector.withTransaction(async (session) => {
 			const parent = await this.#resolveTerminalNode(nodeReferenceId(input.node), session);
 			if (!parent) throw new _mastra_core_storage.KnowledgeNotFoundError("node", nodeReferenceId(input.node));
@@ -5107,14 +5131,12 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 				sourceThreadId: input.sourceThreadId,
 				capturedAt: /* @__PURE__ */ new Date(),
 				when: input.when,
-				maxScope: input.maxScope,
 				metadata: input.metadata
 			};
 			await (await this.#knowledge()).insertOne({
 				...record,
 				scopeKey: (0, _mastra_core_storage.knowledgeScopeKey)(scope),
 				when: record.when ?? null,
-				maxScope: record.maxScope ?? null,
 				deletedAt: null,
 				deletedBy: null
 			}, sessionOptions(session));
@@ -5199,7 +5221,6 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 		return this.#connector.withTransaction(async (session) => {
 			const record = await this.#getKnowledge(input.id, true, session);
 			if (!record) throw new _mastra_core_storage.KnowledgeNotFoundError("record", input.id);
-			(0, _mastra_core_storage.assertKnowledgeScopeWithinCeiling)(scope, record.maxScope);
 			await (await this.#knowledge()).updateOne({ id: input.id }, { $set: {
 				scope,
 				scopeKey: (0, _mastra_core_storage.knowledgeScopeKey)(scope)
@@ -5213,17 +5234,6 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 			};
 		});
 	}
-	async raiseKnowledgeCeiling(input) {
-		const record = await this.#getKnowledge(input.id, true);
-		if (!record) throw new _mastra_core_storage.KnowledgeNotFoundError("record", input.id);
-		(0, _mastra_core_storage.assertKnowledgeScopeWithinCeiling)(record.scope, input.maxScope);
-		(0, _mastra_core_storage.assertKnowledgeCeilingRaised)(record.maxScope, input.maxScope);
-		await (await this.#knowledge()).updateOne({ id: input.id }, { $set: { maxScope: input.maxScope ?? null } });
-		return {
-			...record,
-			maxScope: input.maxScope
-		};
-	}
 	async search(input) {
 		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
 		const query = input.query.trim();
@@ -5263,7 +5273,7 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 				results.push({
 					type: "record",
 					id: record.id,
-					recordId: record.node,
+					recordId: parentVisible ? record.node : record.id,
 					name: parentVisible ? parent.name : "(private node)",
 					text: record.text,
 					scope: cloneScope(record.scope)
@@ -5272,36 +5282,19 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 		}
 		return results.slice(0, limit);
 	}
-	async getCurationCursor(input) {
-		const row = await (await this.#cursors()).findOne(input);
-		return row ? {
-			sourceThreadId: row.sourceThreadId,
-			agent: row.agent,
-			lastKnowledgeId: row.lastKnowledgeId,
-			updatedAt: new Date(row.updatedAt)
-		} : null;
-	}
-	async advanceCurationCursor(input) {
-		const row = await (await this.#cursors()).findOneAndUpdate({
-			sourceThreadId: input.sourceThreadId,
-			agent: input.agent
-		}, {
-			$max: { lastKnowledgeId: input.lastKnowledgeId },
-			$set: { updatedAt: /* @__PURE__ */ new Date() },
-			$setOnInsert: {
-				sourceThreadId: input.sourceThreadId,
-				agent: input.agent
-			}
-		}, {
-			upsert: true,
-			returnDocument: "after"
-		});
-		return {
-			sourceThreadId: row.sourceThreadId,
-			agent: row.agent,
-			lastKnowledgeId: row.lastKnowledgeId,
-			updatedAt: new Date(row.updatedAt)
-		};
+	/**
+	* @deprecated Curation cursors were removed. Observation-time curate is the only Knowledge writer and needs no
+	* cursor. Always throws.
+	*/
+	async getCurationCursor(_input) {
+		throw new Error(KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE);
+	}
+	/**
+	* @deprecated Curation cursors were removed. Observation-time curate is the only Knowledge writer and needs no
+	* cursor. Always throws.
+	*/
+	async advanceCurationCursor(_input) {
+		throw new Error(KNOWLEDGE_CURATION_CURSOR_REMOVED_MESSAGE);
 	}
 	async listActivity(input) {
 		const scope = (0, _mastra_core_storage.canonicalizeKnowledgeScope)(input.scope);
@@ -5422,9 +5415,6 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 	#mentions() {
 		return this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_MENTIONS);
 	}
-	#cursors() {
-		return this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_CURSORS);
-	}
 	#activityCollection() {
 		return this.#collection(_mastra_core_storage.TABLE_KNOWLEDGE_ACTIVITY);
 	}
@@ -5447,12 +5437,14 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 		return row ? nodeFromDocument(row) : null;
 	}
 	async #resolveNode(name, scope, session) {
-		for (let length = scope.length; length > 0; length--) {
-			const node = await this.#getNodeByName(name, scope.slice(0, length), session);
-			if (node) {
-				const terminal = await this.#resolveTerminalNode(node.id, session);
-				if (terminal && (0, _mastra_core_storage.isKnowledgeScopeVisible)(terminal.scope, scope)) return terminal;
-			}
+		const candidates = (await (await this.#nodes()).find({
+			type: "node",
+			canonicalName: canonicalName(name),
+			$or: [{ scopeKey: { $in: visibleScopeKeys(scope) } }, { mergedInto: { $ne: null } }]
+		}, sessionOptions(session)).toArray()).map(nodeFromDocument).sort((left, right) => right.scope.length - left.scope.length);
+		for (const candidate of candidates) {
+			const terminal = await this.#resolveTerminalNode(candidate.id, session);
+			if (terminal && (0, _mastra_core_storage.isKnowledgeScopeVisible)(terminal.scope, scope)) return terminal;
 		}
 		return null;
 	}
@@ -11592,10 +11584,12 @@ var WorkflowsStorageMongoDB = class WorkflowsStorageMongoDB extends _mastra_core
 	async dangerouslyClearAll() {
 		await (await this.getCollection(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT)).deleteMany({});
 	}
-	async updateWorkflowResults({ workflowName, runId, stepId, result, requestContext }) {
+	async updateWorkflowResults({ workflowName, runId, stepId, result, requestContext, state }) {
 		try {
 			const collection = await this.getCollection(_mastra_core_storage.TABLE_WORKFLOW_SNAPSHOT);
 			const now = /* @__PURE__ */ new Date();
+			const contextUpdate = { [stepId]: result };
+			if (state !== void 0) contextUpdate.__state = state;
 			const defaultSnapshot = {
 				context: {},
 				activePaths: [],
@@ -11618,7 +11612,7 @@ var WorkflowsStorageMongoDB = class WorkflowsStorageMongoDB extends _mastra_core
 				run_id: runId,
 				snapshot: { $mergeObjects: [
 					{ $ifNull: ["$snapshot", defaultSnapshot] },
-					{ context: { $mergeObjects: [{ $ifNull: [{ $ifNull: ["$snapshot.context", {}] }, {}] }, { [stepId]: result }] } },
+					{ context: { $mergeObjects: [{ $ifNull: [{ $ifNull: ["$snapshot.context", {}] }, {}] }, contextUpdate] } },
 					{ requestContext: { $mergeObjects: [{ $ifNull: [{ $ifNull: ["$snapshot.requestContext", {}] }, {}] }, requestContext] } }
 				] },
 				updatedAt: now,