@mastra/memory 0.0.0-error-handler-fix-20251020202607 → 0.0.0-esbuild-bundle-worker-20260807182016

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

@@ -0,0 +1,567 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# MongoDB vector store
+
+The `MongoDBVector` class provides vector search using [MongoDB Atlas Vector Search](https://www.mongodb.com/docs/atlas/atlas-vector-search/). It enables efficient similarity search and metadata filtering within your MongoDB collections.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/mongodb@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/mongodb@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/mongodb@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/mongodb@latest
+```
+
+## Usage example
+
+```typescript
+import { MongoDBVector } from '@mastra/mongodb'
+
+const store = new MongoDBVector({
+  id: 'mongodb-vector',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DB_NAME,
+})
+```
+
+### Custom Embedding Field Path
+
+If you need to store embeddings in a nested field structure (e.g., to integrate with existing MongoDB collections), use the `embeddingFieldPath` option:
+
+```typescript
+import { MongoDBVector } from '@mastra/mongodb'
+
+const store = new MongoDBVector({
+  id: 'mongodb-vector',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DB_NAME,
+  embeddingFieldPath: 'text.contentEmbedding', // Store embeddings at text.contentEmbedding
+})
+```
+
+## Constructor options
+
+**id** (`string`): Unique identifier for this vector store instance
+
+**uri** (`string`): MongoDB connection string
+
+**dbName** (`string`): Name of the MongoDB database to use
+
+**options** (`MongoClientOptions`): Optional MongoDB client options
+
+**embeddingFieldPath** (`string`): Path to the field that stores vector embeddings. Supports nested paths using dot notation (e.g., 'text.contentEmbedding'). (Default: `embedding`)
+
+## Methods
+
+### `connect()`
+
+Establishes connection to the MongoDB server. This is called automatically on first use, but can be called explicitly if needed.
+
+```typescript
+await store.connect()
+```
+
+### `createIndex()`
+
+Creates a new vector index (collection) in MongoDB.
+
+**indexName** (`string`): Name of the collection to create
+
+**dimension** (`number`): Vector dimension (must match your embedding model)
+
+**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
+
+**filterFields** (`string[]`): Metadata field names to declare as filter fields in the Atlas vectorSearch index (registered as metadata.\<field>). Queries that filter only on declared fields are pushed directly into $vectorSearch instead of pre-filtering candidate \_ids, avoiding the 16 MB BSON limit on large result sets. Filters that reference an undeclared field, or use an operator $vectorSearch does not support, fall back to the pre-filter automatically.
+
+**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 Atlas 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`)
+
+### `waitForIndexReady()`
+
+Waits for an index to become ready after creation. Useful when you need to ensure an index is ready before performing operations.
+
+**indexName** (`string`): Name of the index to wait for
+
+**timeoutMs** (`number`): Maximum time to wait in milliseconds (Default: `60000`)
+
+**checkIntervalMs** (`number`): Interval between status checks in milliseconds (Default: `2000`)
+
+### `upsert()`
+
+Adds or updates vectors and their metadata in the collection. On a bring-your-own index, this requires `allowWrites: true` at `createIndex()` time because BYO collections are read-only by default.
+
+**indexName** (`string`): Name of the collection to insert into
+
+**vectors** (`number[][]`): Array of embedding vectors
+
+**metadata** (`Record<string, any>[]`): Metadata for each vector
+
+**ids** (`string[]`): Optional vector IDs (auto-generated if not provided)
+
+**documents** (`string[]`): Optional document text content to store alongside vectors
+
+### `query()`
+
+Searches for similar vectors with optional metadata filtering.
+
+**indexName** (`string`): Name of the collection to search in
+
+**queryVector** (`number[]`): Query vector to find similar vectors for
+
+**topK** (`number`): Number of results to return (Default: `10`)
+
+**filter** (`Record<string, any>`): Metadata filters (applies to the metadata field)
+
+**documentFilter** (`Record<string, any>`): Filters on original document fields (not just metadata)
+
+**includeVector** (`boolean`): Whether to include vector data in results (Default: `false`)
+
+**numCandidates** (`number`): Number of candidates the HNSW graph considers before selecting top-K results. Higher values improve recall at the cost of latency. See: https\://www\.mongodb.com/docs/atlas/atlas-vector-search/vector-search-stage/ (Default: `20 * topK (capped at 10000)`)
+
+**metadataMode** (`'field' | 'document'`): 'field' (default) projects the managed metadata/document fields, and filter fields are matched against the metadata subdocument. 'document' returns the full source document as metadata — use for bring-your-own operational collections whose documents have their own shape — and filter fields are matched against the \*\*root\*\* document (no metadata. prefix). The embedding field is omitted from metadata by default (to avoid payload bloat); set includeVector: true to retain it in metadata and also expose it as a top-level vector. (Default: `field`)
+
+### `createSearchIndex()`
+
+Provisions an Atlas Search (BM25/full-text) index on the collection backing an index and records it as the text-search index that `textQuery()` and `hybridQuery()` will target.
+
+**Managed vs. bring-your-own collections:**
+
+- For a **managed** index (created without `collectionName`), `createIndex()` already provisions a _dynamic_ full-text index named `${collectionName}_search_index` (covering all string fields). `createSearchIndex()` is therefore only needed when you want a **field-restricted** mapping or a **custom index name**.
+- For a **bring-your-own** index (created with `collectionName`), `createIndex()` doesn't auto-create any full-text index. Enabling `textQuery()`/`hybridQuery()` on a caller-owned operational collection is opt-in. Call `createSearchIndex()` explicitly to provision the (billable) text index. Until you do, `textQuery()`/`hybridQuery()` throw a clear error rather than querying a non-existent index.
+
+Naming:
+
+- When `fields` is provided **without** an explicit `searchIndexName`, the field-mapped index is created under a **distinct** default name (`${collectionName}_${indexName}_search_fields_index`, unique per logical index) so it doesn't collide with a managed collection's auto-created dynamic index and get silently ignored. This distinct index is persisted as the text-search index, so `textQuery()`/`hybridQuery()` use the restricted mapping automatically.
+- When `searchIndexName` is provided, that exact name is used and persisted. `textQuery()`/`hybridQuery()` resolve the persisted name automatically. You can also override the name per call via their `searchIndexName` / `textSearchIndexName` parameters.
+
+**indexName** (`string`): Name of the Mastra index whose collection will have the search index
+
+**fields** (`string[]`): Field names to index for full-text search. Omit for dynamic mapping (all string fields).
+
+**searchIndexName** (`string`): Name for the Atlas Search index. When fields is provided and this is omitted, a distinct default name that is unique per logical index is used, so the field mapping is not shadowed by the auto-created dynamic index and two logical indexes on the same collection do not collide. (Default: ``${collectionName}_search_index (or ${collectionName}_${indexName}_search_fields_index when `fields` is given)``)
+
+**waitUntilReady** (`boolean`): When true, block until the provisioned full-text index reports READY before resolving. Defaults to false to avoid surprising latency; call waitForSearchIndexReady() explicitly if you prefer to await separately. (Default: `false`)
+
+```typescript
+await store.createSearchIndex({
+  indexName: 'precedents',
+  fields: ['note', 'description'],
+})
+```
+
+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`).
+
+### `waitForSearchIndexReady()`
+
+Waits for the full-text (BM25) search index of an index to become READY. `waitForIndexReady()` polls only the vectorSearch index; `createSearchIndex()` returns while the Atlas Search full-text index is still building, so an immediate `textQuery()`/`hybridQuery()` can intermittently fail. Call this (or pass `waitUntilReady: true` to `createSearchIndex()`) to block until the resolved text index reports READY.
+
+**indexName** (`string`): Logical name of the index whose text index to wait for
+
+**searchIndexName** (`string`): Override the resolved text-search index name
+
+**timeoutMs** (`number`): Maximum time to wait in milliseconds (Default: `60000`)
+
+**checkIntervalMs** (`number`): Interval between status checks in milliseconds (Default: `2000`)
+
+```typescript
+await store.createSearchIndex({ indexName: 'precedents', fields: ['note'] })
+await store.waitForSearchIndexReady({ indexName: 'precedents' })
+```
+
+### `textQuery()`
+
+Runs a full-text (BM25) search against an Atlas Search index. By default it targets the text-search index recorded for this index (set by `createSearchIndex()`, or the dynamic `${collectionName}_search_index` auto-created by `createIndex()`). Pass `searchIndexName` to target a specific index for this call.
+
+Metadata filters here (like `hybridQuery()`) are applied via a `$match` stage. For the vector branch of `hybridQuery()`, filters on fields not declared via `filterFields` at index creation are transparently materialised as candidate `_id`s (the same fallback `query()` uses), so undeclared-field filters don't error.
+
+**indexName** (`string`): Name of the Mastra index to search
+
+**query** (`string`): Full-text search query string
+
+**paths** (`string[]`): Field paths to search in (e.g., \["note", "description"])
+
+**topK** (`number`): Number of results to return (Default: `10`)
+
+**filter** (`Record<string, any>`): Metadata filters (applies to the metadata field)
+
+**metadataMode** (`'field' | 'document'`): 'field' (default) projects the managed metadata/document fields. 'document' returns the full source document as metadata. (Default: `field`)
+
+**searchIndexName** (`string`): Override the resolved full-text search index name for this call. Defaults to the index persisted by createSearchIndex() / createIndex().
+
+```typescript
+const results = await store.textQuery({
+  indexName: 'precedents',
+  query: 'shell company offshore',
+  paths: ['note'],
+  topK: 10,
+})
+```
+
+### `hybridQuery()`
+
+Runs a hybrid search that fuses vector similarity and full-text results using MongoDB's server-side `$rankFusion`. It requires MongoDB >= 8.0 and is generally available from 8.1. On 8.0.x, it may need a MongoDB support case to enable, and it runs where enabled, such as Atlas 8.0.x. A full-text search index must exist: it's auto-created for managed indexes, but for a bring-your-own collection you must call `createSearchIndex()` first (opt-in).
+
+**indexName** (`string`): Name of the Mastra index to search
+
+**queryVector** (`number[]`): Query vector for similarity search
+
+**query** (`string`): Full-text search query string
+
+**paths** (`string[]`): Field paths to search in for full-text (e.g., \["note", "description"])
+
+**topK** (`number`): Number of results to return (Default: `10`)
+
+**filter** (`Record<string, any>`): Metadata filters (applies to both vector and text branches)
+
+**weights** (`{ vector?: number; text?: number }`): Relative weights for vector vs. text results in fusion (default: 1:1)
+
+**numCandidates** (`number`): Number of candidates for the vector search branch (Default: `20 * topK (capped at 10000)`)
+
+**metadataMode** (`'field' | 'document'`): 'field' (default) projects the managed metadata/document fields. 'document' returns the full source document as metadata. (Default: `field`)
+
+**textSearchIndexName** (`string`): Override the resolved full-text search index name for this call. Defaults to the index persisted by createSearchIndex() / createIndex().
+
+```typescript
+const results = await store.hybridQuery({
+  indexName: 'precedents',
+  queryVector: embedding,
+  query: 'shell company offshore',
+  paths: ['note'],
+  topK: 10,
+  weights: { vector: 1, text: 1.5 }, // Favor text matches
+})
+```
+
+`hybridQuery()` requires MongoDB >= 8.0 for the `$rankFusion` stage. The stage is generally available from 8.1. On 8.0.x, it may need a MongoDB support case to enable and runs where enabled, such as Atlas 8.0.x. If you're running an older version, or `$rankFusion` isn't enabled on your 8.0.x deployment, use `query()` and `textQuery()` separately and merge the results client-side.
+
+### `describeIndex()`
+
+Returns information about the index (collection).
+
+**indexName** (`string`): Name of the collection to describe
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number
+  count: number
+  metric: 'cosine' | 'euclidean' | 'dotproduct'
+}
+```
+
+### `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 Atlas vectorSearch index and, if one was provisioned via `createSearchIndex()`, the companion full-text search 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.
+
+**indexName** (`string`): Logical name of the index to delete
+
+### `listIndexes()`
+
+Lists the **logical** Mastra index names (the `indexName` values passed to `createIndex`), not physical collection names. For a bring-your-own index whose data lives in an operational collection, the logical index name is returned instead of the physical collection name. The value can be passed straight back into `deleteIndex()` / `describeIndex()`. Managed indexes created before durable metadata was introduced are still discovered via their `${name}_vector_index` search index. The internal registry collection is never listed.
+
+Returns: `Promise<string[]>`
+
+### `updateVector()`
+
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
+> **Bring-your-own collections are read-only by default.** `upsert()`, `updateVector()`, `deleteVector()`, and `deleteVectors()` throw a USER-category error on a BYO index unless it was created with `allowWrites: true`. See [Indexing an existing collection](#indexing-an-existing-collection).
+
+**indexName** (`string`): Name of the collection containing the vector
+
+**id** (`string`): ID of the vector entry to update (mutually exclusive with filter)
+
+**filter** (`Record<string, any>`): Metadata filter to identify vector(s) to update (mutually exclusive with id)
+
+**update** (`object`): Update data containing vector and/or metadata
+
+**update.vector** (`number[]`): New vector data to update
+
+**update.metadata** (`Record<string, any>`): New metadata to update
+
+### `deleteVector()`
+
+Deletes a specific vector entry from an index by its ID.
+
+**indexName** (`string`): Name of the collection containing the vector
+
+**id** (`string`): ID of the vector entry to delete
+
+### `deleteVectors()`
+
+Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
+
+**indexName** (`string`): Name of the collection containing the vectors to delete
+
+**ids** (`string[]`): Array of vector IDs to delete (mutually exclusive with filter)
+
+**filter** (`Record<string, any>`): Metadata filter to identify vectors to delete (mutually exclusive with ids)
+
+### `disconnect()`
+
+Closes the MongoDB client connection. Should be called when done using the store.
+
+## Response types
+
+Query results are returned in this format:
+
+```typescript
+interface QueryResult {
+  id: string
+  score: number
+  metadata: Record<string, any>
+  vector?: number[] // Only included if includeVector is true
+}
+```
+
+## Error handling
+
+The store throws typed errors that can be caught:
+
+```typescript
+try {
+  await store.query({
+    indexName: 'my_collection',
+    queryVector: queryVector,
+  })
+} catch (error) {
+  // Handle specific error cases
+  if (error.message.includes('Invalid collection name')) {
+    console.error(
+      'Collection name must start with a letter or underscore and contain only valid characters.',
+    )
+  } else if (error.message.includes('Collection not found')) {
+    console.error('The specified collection does not exist')
+  } else {
+    console.error('Vector store error:', error.message)
+  }
+}
+```
+
+## Indexing an existing collection
+
+You can create a vector index on an existing operational collection instead of using a managed collection. This is useful when you want to add vector search capabilities to documents that already exist in your MongoDB database.
+
+```typescript
+import { MongoDBVector } from '@mastra/mongodb'
+
+const store = new MongoDBVector({
+  id: 'mongodb-vector',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DB_NAME,
+})
+
+// Create a vector index on an existing 'transactions' collection
+await store.createIndex({
+  indexName: 'precedents',
+  dimension: 1024,
+  collectionName: 'transactions', // Use existing collection
+  searchIndexName: 'txn_vec_idx', // Custom search index name
+})
+
+// Wait for the index to be ready
+await store.waitForIndexReady({ indexName: 'precedents' })
+
+// Query using document mode to get full source documents
+const hits = await store.query({
+  indexName: 'precedents',
+  queryVector: embeddings,
+  topK: 5,
+  metadataMode: 'document', // Returns full document as metadata
+})
+
+// hits[0].metadata now contains all fields from the source document
+console.log(hits[0].metadata.amount, hits[0].metadata.customField)
+
+// Full-text / hybrid search on a BYO collection is opt-in: provision the text index first.
+await store.createSearchIndex({ indexName: 'precedents', fields: ['note'] })
+```
+
+**Important notes:**
+
+- The collection must already exist and contain documents with an `embedding` field (or the custom `embeddingFieldPath` you configured)
+- The collection is never created or dropped when using `collectionName`
+- **A BYO index is read-only by default.** `upsert()`, `updateVector()`, `deleteVector()`, and `deleteVectors()` throw a clear error rather than mutating caller-owned operational documents. To let the store write embeddings into (or delete documents from) your collection, opt in explicitly with `createIndex({ ..., allowWrites: true })`. The policy is persisted and survives restarts. Entries written by older versions without the flag are treated as read-only (fail closed).
+- Use `metadataMode: 'document'` when querying to retrieve the full source document as `metadata`
+- In `'document'` mode the embedding is omitted from `metadata` by default; pass `includeVector: true` to retain it (and also expose it as a top-level `vector`)
+- **Filtering in `'document'` mode operates on root document fields**, not a nested `metadata.` subdocument. `filter: { lane: 'fraud' }` matches the top-level `lane` field of your operational documents (in the default `'field'` mode, bare fields are rewritten to `metadata.<field>` for managed collections). Both the pushdown and `$match` fallback paths honor this.
+- **Native `ObjectId` `_id`s are supported.** Operational collections commonly key on `ObjectId`; query results coerce `_id` to a string (the `QueryResult.id` contract), and `deleteVector()`/`updateVector()`/`deleteVectors()` accept that string and match the underlying `ObjectId` document. Managed collections (string `_id`s) are unaffected.
+- Full-text and hybrid search on a BYO collection are **opt-in**: no full-text index is auto-created, so call `createSearchIndex()` before `textQuery()`/`hybridQuery()`. The full-text index builds asynchronously. Call `waitForSearchIndexReady()` (or pass `waitUntilReady: true`) before an immediate text/hybrid query.
+- `deleteIndex()` on a BYO index drops the vector index (and the text index if one was created) but **preserves** the collection and its documents
+
+## Best practices
+
+- Index metadata fields used in filters for optimal query performance.
+- Use consistent field naming in metadata to avoid unexpected query results.
+- Regularly monitor index and collection statistics to ensure efficient search.
+- When indexing existing collections, ensure all documents have the required `embedding` field.
+
+## Usage example
+
+### Vector embeddings with `MongoDB`
+
+Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve related messages by meaning (not keywords).
+
+> **Note:** MongoDB Atlas Vector Search is recommended for production use. For self-hosted deployments, Vector Search is available with [local Atlas deployments via the Atlas CLI](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-local/).
+
+This setup uses FastEmbed, a local embedding model, to generate vector embeddings. To use this, install `@mastra/fastembed`:
+
+**npm**:
+
+```bash
+npm install @mastra/fastembed@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/fastembed@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/fastembed@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/fastembed@latest
+```
+
+Add the following to your agent:
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+import { MongoDBStore, MongoDBVector } from '@mastra/mongodb'
+import { fastembed } from '@mastra/fastembed'
+
+export const mongodbAgent = new Agent({
+  id: 'mongodb-agent',
+  name: 'mongodb-agent',
+  instructions:
+    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({
+    storage: new MongoDBStore({
+      id: 'mongodb-storage',
+      uri: process.env.MONGODB_URI!,
+      dbName: process.env.MONGODB_DB_NAME!,
+    }),
+    vector: new MongoDBVector({
+      id: 'mongodb-vector',
+      uri: process.env.MONGODB_URI!,
+      dbName: process.env.MONGODB_DB_NAME!,
+    }),
+    embedder: fastembed,
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2,
+      },
+      generateTitle: true, // generates descriptive thread titles automatically
+    },
+  }),
+})
+```
+
+### Vector embeddings with VoyageAI
+
+VoyageAI provides specialized embedding models optimized for retrieval tasks. VoyageAI is also integrated with MongoDB Atlas for multimodal embeddings.
+
+**npm**:
+
+```bash
+npm install @mastra/voyageai@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/voyageai@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/voyageai@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/voyageai@latest
+```
+
+Basic usage example:
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+import { MongoDBStore, MongoDBVector } from '@mastra/mongodb'
+import { voyage } from '@mastra/voyageai'
+
+export const mongodbVoyageAgent = new Agent({
+  id: 'mongodb-voyage-agent',
+  name: 'MongoDB VoyageAI Agent',
+  instructions: 'You are an AI agent with semantic recall powered by VoyageAI and MongoDB.',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({
+    storage: new MongoDBStore({
+      id: 'mongodb-storage',
+      uri: process.env.MONGODB_URI!,
+      dbName: process.env.MONGODB_DB_NAME!,
+    }),
+    vector: new MongoDBVector({
+      id: 'mongodb-vector',
+      uri: process.env.MONGODB_URI!,
+      dbName: process.env.MONGODB_DB_NAME!,
+    }),
+    embedder: voyage, // VoyageAI's default model (voyage-3.5, 1024 dimensions)
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 5,
+        messageRange: 2,
+      },
+    },
+  }),
+})
+```
+
+For detailed VoyageAI embedding examples including specialized models, multimodal embeddings, and retrieval optimization, see the [VoyageAI embeddings documentation](https://mastra.ai/models/embeddings).
+
+## Related
+
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)
+- [VoyageAI Embeddings Documentation](https://mastra.ai/models/embeddings)