@mastra/mongodb 1.24.1-alpha.0 → 1.24.1

package/dist/_types/@internal_core/dist/memory/index.d.ts

@@ -1,4 +1,3 @@
-//#region src/memory/index.d.ts
 /**
  * Shared rules for observational memory lifecycle writes. Every storage adapter applies
  * these inside its own atomic section (lock, transaction, or conditional update), so the
@@ -97,5 +96,4 @@ export declare function assertActiveObservationsApplied(result: UpdateActiveObse
  * (equal, or only appended to since).
  */
 export declare function isAppendOnlySince(storedObservations: string, snapshotObservations: string): boolean;
-//#endregion
 //# sourceMappingURL=index.d.ts.map

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.24.1-alpha.0"
+  version: "1.24.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -4,7 +4,11 @@
 
 # Semantic recall
 
-If you ask your friend what they did last weekend, they will search in their memory for events associated with "last weekend" and then tell you what they did. That's sort of like how semantic recall works in Mastra.
+Semantic recall is a built-in form of Retrieval-Augmented Generation (RAG) for agent memory. When a user sends a message, Mastra searches earlier messages for ones with a similar meaning and adds the most relevant ones to the agent's context.
+
+Matching on meaning matters because people often remember the idea behind something, not the exact words they used. A user might ask "What did we decide about the refund?" after originally writing "Let's give them their money back." A keyword search misses that connection, but semantic recall finds it.
+
+Use semantic recall when your agent needs details from earlier in a long conversation, or from a user's other conversations, that are no longer in [recent message history](https://mastra.ai/docs/memory/message-history).
 
 > **📹 Watch:** Watch [Mastra semantic recall](https://www.youtube.com/watch?v=UVZtK8cK8xQ\&pp=ygUVbWFzdHJhIHdvcmtpbmcgbWVtb3J5) to see how agents retrieve relevant messages from past conversations.
 
@@ -452,8 +456,10 @@ const agent = new Agent({
         indexConfig: {
           type: 'hnsw', // Use HNSW for better performance
           metric: 'dotproduct', // Best for OpenAI embeddings
-          m: 16, // Number of bi-directional links (default: 16)
-          efConstruction: 64, // Size of candidate list during construction (default: 64)
+          hnsw: {
+            m: 16, // Number of bi-directional links (default: 16)
+            efConstruction: 64, // Size of candidate list during construction (default: 64)
+          },
         },
       },
     },

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

@@ -382,6 +382,7 @@ Vector store prompts define query patterns and filtering capabilities for each v
 
 ```ts
 import { MONGODB_PROMPT } from '@mastra/mongodb'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -416,6 +417,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { PINECONE_PROMPT } from '@mastra/pinecone'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -433,6 +435,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { QDRANT_PROMPT } from '@mastra/qdrant'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -450,6 +453,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { CHROMA_PROMPT } from '@mastra/chroma'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -467,6 +471,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { ASTRA_PROMPT } from '@mastra/astra'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -484,6 +489,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { LIBSQL_PROMPT } from '@mastra/libsql'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -501,6 +507,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { UPSTASH_PROMPT } from '@mastra/upstash'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -518,6 +525,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { VECTORIZE_PROMPT } from '@mastra/vectorize'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -535,6 +543,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { OPENSEARCH_PROMPT } from '@mastra/opensearch'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -552,6 +561,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { ORACLEDB_PROMPT } from '@mastra/oracledb'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',
@@ -569,6 +579,7 @@ export const ragAgent = new Agent({
 
 ```ts
 import { S3VECTORS_PROMPT } from '@mastra/s3vectors'
+import { Agent } from '@mastra/core/agent'
 
 export const ragAgent = new Agent({
   id: 'rag-agent',

package/dist/docs/references/reference-storage-retention.md

@@ -294,7 +294,7 @@ const storage = new MongoDBStore({
 
 ## Reclaiming disk
 
-`prune()` deletes rows but doesn't shrink the database file. On SQLite/libSQL the freed pages go on a freelist and are reused by future writes, so the file stops growing: for most users this alone solves the unbounded-growth problem.
+`prune()` deletes rows but doesn't shrink the database file. On SQLite/libSQL the freed pages go on a freelist for reuse by future writes. Reusing these pages prevents unbounded file growth for most users.
 
 Handing that free space back to the OS is a separate concern that Mastra doesn't manage. If you specifically need to shrink the file, run the underlying database's compaction (for example `VACUUM` on self-hosted libSQL) yourself in a maintenance window. A full `VACUUM` locks the file and needs roughly twice the file size in free disk. On PostgreSQL, autovacuum reclaims dead tuples for reuse automatically. A manual `VACUUM FULL` is only needed if you must return disk to the OS.
 

package/dist/docs/references/reference-vectors-mongodb.md

@@ -97,7 +97,7 @@ Creates a new vector index (collection) in MongoDB.
 
 **collectionName** (`string`): Store the vectors on an existing (operational) collection instead of a managed collection named after the index. The collection is never created or dropped by this store when set. Defaults to indexName.
 
-**searchIndexName** (`string`): Name for the MongoDB vectorSearch index created on the collection. Defaults to ${indexName}\_vector\_index.
+**searchIndexName** (`string`): Name for the MongoDB vectorSearch index created on the collection. Defaults to ${indexName}\_vector_index.
 
 **allowWrites** (`boolean`): Opt-in to write operations (upsert, updateVector, deleteVector, deleteVectors) on a bring-your-own collection. By default a BYO index is read-only: the store never modifies or deletes caller-owned operational documents. Ignored for managed collections, which are always writable. The policy is persisted with the index registration and survives restarts. (Default: `false`)
 
@@ -178,7 +178,7 @@ await store.createSearchIndex({
 })
 ```
 
-The field-mapped index name includes the logical `indexName`, so two logical indexes on the same collection get distinct text indexes. Recreating the _same_ logical index with different `fields` still requires dropping the existing index first (`IndexAlreadyExists`).
+The field-mapped index name includes the logical `indexName`, so two logical indexes on the same collection get distinct text indexes. Calling `createSearchIndex()` again for the _same_ logical index with different `fields` updates the existing text index definition in place. You don't need to drop it first.
 
 ### `waitForSearchIndexReady()`
 
@@ -279,18 +279,18 @@ Returns:
 interface IndexStats {
   dimension: number
   count: number
-  metric: 'cosine' | 'euclidean' | 'dotproduct'
+  metric?: 'cosine' | 'euclidean' | 'dotproduct'
 }
 ```
 
-On an `autoEmbed` index, `dimension` is read from the index definition and reports MongoDB's default of `1024` when the index doesn't pin one. `count` counts documents that carry the embedded text field, since the generated vectors aren't stored on your documents.
+On an `autoEmbed` index, `dimension` is read from the index definition and reports MongoDB's default of `1024` when the index doesn't pin one. `metric` is omitted when the `autoEmbed` index doesn't specify a similarity. `count` counts documents that carry the embedded text field, since the generated vectors aren't stored on your documents.
 
 ### `deleteIndex()`
 
 Deletes a vector index. Behavior depends on how the index was created:
 
 - **Managed index** (created without `collectionName`): drops the entire collection and all its data.
-- **Bring-your-own index** (created with `collectionName`): drops the MongoDB vectorSearch index. If `createSearchIndex()` provisioned a companion full-text search index, it drops that index too. The caller's operational collection and its documents are preserved. This store never drops a collection it didn't create.
+- **Bring-your-own index** (created with `collectionName`): drops the MongoDB vectorSearch index. If `createSearchIndex()` provisioned a companion full-text search index, it drops that index too. A vectorSearch or full-text index that another logical index on the same collection still references is kept for that index. The caller's operational collection and its documents are preserved. This store never drops a collection it didn't create.
 
 The BYO classification is recorded durably when the index is created, so it's applied correctly even by a different process (e.g. an index created by a setup job and later deleted by a long-lived service). Always pass the **logical index name** (the `indexName` used at `createIndex`), not the physical collection name.
 
@@ -350,7 +350,7 @@ Query results are returned in this format:
 interface QueryResult {
   id: string
   score: number
-  metadata: Record<string, any>
+  metadata?: Record<string, any>
   vector?: number[] // Only included if includeVector is true
   document?: string // Source text stored with the vector, when available
 }

package/dist/index.cjs

@@ -9,10 +9,9 @@ let crypto$1 = require("crypto");
 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.24.1-alpha.0";
-//#endregion
-//#region src/vector/filter.ts
+// package.json
+var version = "1.24.1";
+// src/vector/filter.ts
 /**
 * Translator for MongoDB filter queries.
 * Maintains MongoDB-compatible syntax while ensuring proper validation
@@ -47,10 +46,9 @@ var MongoDBFilterTranslator = class extends _mastra_core_vector_filter.BaseFilte
 				if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("$not operator requires an object");
 				if (this.isEmpty(value)) throw new Error("$not operator cannot be empty");
 				return this.translateNode(value);
-			} else {
-				if (!Array.isArray(value)) throw new Error(`Value for logical operator ${operator} must be an array`);
-				return value.map((item) => this.translateNode(item));
 			}
+			if (!Array.isArray(value)) throw new Error(`Value for logical operator ${operator} must be an array`);
+			return value.map((item) => this.translateNode(item));
 		}
 		if (this.isBasicOperator(operator) || this.isNumericOperator(operator)) {
 			if (value instanceof Date) return value.toISOString();
@@ -82,8 +80,7 @@ var MongoDBFilterTranslator = class extends _mastra_core_vector_filter.BaseFilte
 		return filter === void 0 || filter === null || typeof filter === "object" && Object.keys(filter).length === 0;
 	}
 };
-//#endregion
-//#region src/vector/index.ts
+// src/vector/index.ts
 /** Name an index's embedding mode for a conflict message. */
 function describeEmbedding(config) {
 	return config ? `autoEmbed (path "${config.path}", model "${config.model}")` : "client-side vectors";
@@ -1566,8 +1563,7 @@ var MongoDBVector = class MongoDBVector extends _mastra_core_vector.MastraVector
 		return true;
 	}
 };
-//#endregion
-//#region src/storage/connectors/MongoDBConnector.ts
+// src/storage/connectors/MongoDBConnector.ts
 var MongoDBConnector = class MongoDBConnector {
 	#client;
 	#dbName;
@@ -1678,8 +1674,7 @@ var MongoDBConnector = class MongoDBConnector {
 		if (this.#handler) await this.#handler.close();
 	}
 };
-//#endregion
-//#region src/storage/db/index.ts
+// src/storage/db/index.ts
 /**
 * Resolves a config to a MongoDBConnector instance.
 * Accepts both MongoDBConfig (main store) and MongoDBDomainConfig (domains).
@@ -1724,8 +1719,7 @@ function resolveMongoDBConfig(config) {
 		}, error);
 	}
 }
-//#endregion
-//#region src/storage/domains/agents/index.ts
+// src/storage/domains/agents/index.ts
 /**
 * The set of fields from StorageAgentSnapshotType that live on version rows.
 * Used to strip snapshot config from version documents when transforming.
@@ -2423,8 +2417,7 @@ function resolveTargets({ policies, descriptor, order, encodings }) {
 	}
 	return targets;
 }
-//#endregion
-//#region src/storage/domains/background-tasks/index.ts
+// src/storage/domains/background-tasks/index.ts
 function toDoc(task) {
 	return {
 		id: task.id,
@@ -2674,8 +2667,7 @@ var BackgroundTasksStorageMongoDB = class BackgroundTasksStorageMongoDB extends
 		});
 	}
 };
-//#endregion
-//#region src/storage/domains/blobs/index.ts
+// src/storage/domains/blobs/index.ts
 var MongoDBBlobStore = class MongoDBBlobStore extends _mastra_core_storage.BlobStore {
 	#connector;
 	#skipDefaultIndexes;
@@ -2832,8 +2824,7 @@ var MongoDBBlobStore = class MongoDBBlobStore extends _mastra_core_storage.BlobS
 		};
 	}
 };
-//#endregion
-//#region src/storage/domains/utils.ts
+// src/storage/domains/utils.ts
 function formatDateForMongoDB(date) {
 	return typeof date === "string" ? new Date(date) : date;
 }
@@ -2850,8 +2841,7 @@ function applyTenancyFilter(filter, filters) {
 	if (filters.organizationId !== void 0) filter.organizationId = filters.organizationId;
 	if (filters.projectId !== void 0) filter.projectId = filters.projectId;
 }
-//#endregion
-//#region src/storage/domains/datasets/index.ts
+// src/storage/domains/datasets/index.ts
 const MANAGED_COLLECTIONS = [
 	_mastra_core_storage.TABLE_DATASETS,
 	_mastra_core_storage.TABLE_DATASET_ITEMS,
@@ -4037,8 +4027,7 @@ var MongoDBDatasetsStorage = class extends _mastra_core_storage.DatasetsStorage
 		}, failures[0].reason);
 	}
 };
-//#endregion
-//#region src/storage/domains/experiments/index.ts
+// src/storage/domains/experiments/index.ts
 function toDate(value) {
 	if (value instanceof Date) return value;
 	if (typeof value === "string" || typeof value === "number") return new Date(value);
@@ -4770,8 +4759,7 @@ var MongoDBExperimentsStorage = class MongoDBExperimentsStorage extends _mastra_
 		} catch {}
 	}
 };
-//#endregion
-//#region src/storage/domains/knowledge/index.ts
+// src/storage/domains/knowledge/index.ts
 let assertDescriptionWithinBound;
 async function assertKnowledgeDescriptionWithinBoundCompat(description) {
 	let assertWithinBound = assertDescriptionWithinBound;
@@ -5612,8 +5600,7 @@ var KnowledgeMongoDB = class KnowledgeMongoDB extends _mastra_core_storage.Knowl
 		return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 	}
 };
-//#endregion
-//#region src/storage/domains/mcp-clients/index.ts
+// src/storage/domains/mcp-clients/index.ts
 /**
 * Snapshot config fields that live on MCP client version documents.
 */
@@ -6058,8 +6045,7 @@ var MongoDBMCPClientsStorage = class MongoDBMCPClientsStorage extends _mastra_co
 		return result;
 	}
 };
-//#endregion
-//#region src/storage/domains/mcp-servers/index.ts
+// src/storage/domains/mcp-servers/index.ts
 /**
 * Snapshot config fields that live on MCP server version documents.
 */
@@ -6514,8 +6500,7 @@ var MongoDBMCPServersStorage = class MongoDBMCPServersStorage extends _mastra_co
 		return result;
 	}
 };
-//#endregion
-//#region ../../packages/_internal-core/dist/memory/index.js
+// ../../packages/_internal-core/dist/memory/index.js
 /**
 * A buffered chunk stores `lastObservedAt = max message time + 1ms`. It is wholly covered
 * (every message it observed is already at or before the cursor) iff
@@ -6579,8 +6564,7 @@ function isAppendOnlySince(storedObservations, snapshotObservations) {
 	const snapshot = snapshotObservations ?? "";
 	return stored === snapshot || stored.startsWith(snapshot);
 }
-//#endregion
-//#region src/storage/domains/run-fencing.ts
+// src/storage/domains/run-fencing.ts
 async function getRunClaims(connector, name) {
 	return await connector.getCollection(name);
 }
@@ -6613,8 +6597,7 @@ async function withRunFence(connector, check, write) {
 		return write(session);
 	});
 }
-//#endregion
-//#region src/storage/domains/memory/index.ts
+// src/storage/domains/memory/index.ts
 /**
 * Local constant for the observational memory table name.
 * Defined locally to avoid a static import that crashes on older @mastra/core
@@ -8731,8 +8714,7 @@ var MemoryStorageMongoDB = class MemoryStorageMongoDB extends _mastra_core_stora
 		}
 	}
 };
-//#endregion
-//#region src/storage/domains/notifications/index.ts
+// src/storage/domains/notifications/index.ts
 /** Ids per updateMany/find command — keeps the `$in` filter far below MongoDB's 16 MiB BSON limit. */
 const BULK_ID_BATCH_SIZE = 500;
 const statusTimestamp = (status, now) => {
@@ -9110,8 +9092,7 @@ const dueTime = (record) => {
 	if (deliverAt !== void 0 && summaryAt !== void 0) return Math.min(deliverAt, summaryAt);
 	return deliverAt ?? summaryAt ?? Number.POSITIVE_INFINITY;
 };
-//#endregion
-//#region src/storage/domains/observability/index.ts
+// src/storage/domains/observability/index.ts
 var ObservabilityMongoDB = class ObservabilityMongoDB extends _mastra_core_storage.ObservabilityStorage {
 	#connector;
 	#skipDefaultIndexes;
@@ -9783,8 +9764,7 @@ MIGRATION REQUIRED: Duplicate spans detected in ${_mastra_core_storage.TABLE_SPA
 		return span;
 	}
 };
-//#endregion
-//#region src/storage/domains/prompt-blocks/index.ts
+// src/storage/domains/prompt-blocks/index.ts
 /**
 * Snapshot config fields that live on prompt block version documents.
 */
@@ -10231,8 +10211,7 @@ var MongoDBPromptBlocksStorage = class MongoDBPromptBlocksStorage extends _mastr
 		return result;
 	}
 };
-//#endregion
-//#region src/storage/domains/schedules/index.ts
+// src/storage/domains/schedules/index.ts
 function scheduleToDoc(schedule) {
 	return {
 		id: schedule.id,
@@ -10486,8 +10465,7 @@ var SchedulesMongoDB = class SchedulesMongoDB extends _mastra_core_storage.Sched
 		return (await cursor.toArray()).map(docToTrigger);
 	}
 };
-//#endregion
-//#region src/storage/domains/scorer-definitions/index.ts
+// src/storage/domains/scorer-definitions/index.ts
 /**
 * Snapshot config fields that live on scorer definition version documents.
 */
@@ -10937,8 +10915,7 @@ var MongoDBScorerDefinitionsStorage = class MongoDBScorerDefinitionsStorage exte
 		return result;
 	}
 };
-//#endregion
-//#region src/storage/domains/scores/index.ts
+// src/storage/domains/scores/index.ts
 /**
 * MongoDB-specific score row transformation.
 * Converts timestamp strings to Date objects.
@@ -11314,8 +11291,7 @@ var ScoresStorageMongoDB = class ScoresStorageMongoDB extends _mastra_core_stora
 		}
 	}
 };
-//#endregion
-//#region src/storage/domains/skills/index.ts
+// src/storage/domains/skills/index.ts
 /**
 * Snapshot config fields that live on skill version documents.
 */
@@ -11814,8 +11790,7 @@ var MongoDBSkillsStorage = class MongoDBSkillsStorage extends _mastra_core_stora
 		return result;
 	}
 };
-//#endregion
-//#region src/storage/domains/workflow-definitions/index.ts
+// src/storage/domains/workflow-definitions/index.ts
 function docToDefinition(doc) {
 	const def = {
 		id: String(doc.id),
@@ -11952,8 +11927,7 @@ var MongoDBWorkflowDefinitionsStore = class MongoDBWorkflowDefinitionsStore exte
 		await (await this.getCollection(_mastra_core_storage.TABLE_WORKFLOW_DEFINITIONS)).deleteOne({ id });
 	}
 };
-//#endregion
-//#region src/storage/domains/workflows/index.ts
+// src/storage/domains/workflows/index.ts
 const RUN_OWNER_PROJECTION = {
 	generation: 1,
 	ownerId: 1,
@@ -12463,8 +12437,7 @@ var WorkflowsStorageMongoDB = class WorkflowsStorageMongoDB extends _mastra_core
 		};
 	}
 };
-//#endregion
-//#region src/storage/domains/workspaces/index.ts
+// src/storage/domains/workspaces/index.ts
 /**
 * Snapshot config fields that live on workspace version documents.
 */
@@ -12963,8 +12936,7 @@ var MongoDBWorkspacesStorage = class MongoDBWorkspacesStorage extends _mastra_co
 		return result;
 	}
 };
-//#endregion
-//#region src/storage/index.ts
+// src/storage/index.ts
 /**
 * MongoDB storage adapter for Mastra.
 *
@@ -13057,8 +13029,7 @@ var MongoDBStore = class extends _mastra_core_storage.MastraCompositeStore {
 		}
 	}
 };
-//#endregion
-//#region src/vector/prompt.ts
+// src/vector/prompt.ts
 /**
 * Vector store specific prompt that details supported operators and examples.
 * This prompt helps users construct valid filters for MongoDB Vector.
@@ -13156,7 +13127,6 @@ Example Complex Query:
     { "$not": { "status": "discontinued" } }
   ]
 }`;
-//#endregion
 exports.BackgroundTasksStorageMongoDB = BackgroundTasksStorageMongoDB;
 exports.KnowledgeMongoDB = KnowledgeMongoDB;
 exports.MONGODB_PROMPT = MONGODB_PROMPT;