@mastra/memory 1.23.1 → 1.24.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @mastra/memory
 
+## 1.24.0
+
+### Minor Changes
+
+- Added exact metadata filtering to message history queries across Memory APIs and supported storage providers. ([#19991](https://github.com/mastra-ai/mastra/pull/19991))
+
+  ```ts
+  const messages = await memory.recall({
+    threadId: 'thread-1',
+    filter: {
+      metadata: {
+        status: 'done',
+        priority: 'high',
+      },
+    },
+  });
+  ```
+
+  Multiple fields use AND semantics. Supported values are strings, finite numbers, booleans, and `null`.
+
+### Patch Changes
+
+- Updated dependencies [[`ce93a3c`](https://github.com/mastra-ai/mastra/commit/ce93a3c114ea1cbfbd576f3db41d7c26c9844f5b), [`5718a22`](https://github.com/mastra-ai/mastra/commit/5718a229281dcfd36bcd1f42a242e3717e510a33), [`a211d09`](https://github.com/mastra-ai/mastra/commit/a211d09185dc65a746534914cf38b67f21ee9bac), [`0dca9d0`](https://github.com/mastra-ai/mastra/commit/0dca9d0b1356024a53b72ea6f040db528b126caa), [`6218217`](https://github.com/mastra-ai/mastra/commit/62182171b6cfca0b099f1c6a77a2e65e7639ab86), [`5807d3a`](https://github.com/mastra-ai/mastra/commit/5807d3ae1d259b8b7d6df7e5bf2b485c694af9c8), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`05db566`](https://github.com/mastra-ai/mastra/commit/05db566fcbdcbf33d0bffca0c72ec30129e2e3ca), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`5718a22`](https://github.com/mastra-ai/mastra/commit/5718a229281dcfd36bcd1f42a242e3717e510a33), [`57661af`](https://github.com/mastra-ai/mastra/commit/57661afeca52ff9af4e72675ede2134fa503d5a5), [`d1b7e3a`](https://github.com/mastra-ai/mastra/commit/d1b7e3a978a309a5653eeaa490d2d6c7c53bd093), [`29c584a`](https://github.com/mastra-ai/mastra/commit/29c584a13a88831e5ed1fdeb0ff8e82eae180433), [`c093146`](https://github.com/mastra-ai/mastra/commit/c0931466404d3c521308ea119cb165bb7e695155), [`8124754`](https://github.com/mastra-ai/mastra/commit/8124754ae89fbc69f8136d1df4a91904d0f84c4e), [`d12b2e4`](https://github.com/mastra-ai/mastra/commit/d12b2e4023fd9e3d3e93a9169f5088bcee2a849c)]:
+  - @mastra/core@1.54.0
+
+## 1.24.0-alpha.0
+
+### Minor Changes
+
+- Added exact metadata filtering to message history queries across Memory APIs and supported storage providers. ([#19991](https://github.com/mastra-ai/mastra/pull/19991))
+
+  ```ts
+  const messages = await memory.recall({
+    threadId: 'thread-1',
+    filter: {
+      metadata: {
+        status: 'done',
+        priority: 'high',
+      },
+    },
+  });
+  ```
+
+  Multiple fields use AND semantics. Supported values are strings, finite numbers, booleans, and `null`.
+
+### Patch Changes
+
+- Updated dependencies [[`0dca9d0`](https://github.com/mastra-ai/mastra/commit/0dca9d0b1356024a53b72ea6f040db528b126caa)]:
+  - @mastra/core@1.54.0-alpha.0
+
 ## 1.23.1
 
 ### Patch Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-memory
 description: Documentation for @mastra/memory. Use when working with @mastra/memory APIs, configuration, or implementation.
 metadata:
   package: "@mastra/memory"
-  version: "1.23.1"
+  version: "1.24.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,213 +1,11 @@
 {
-  "version": "1.23.1",
+  "version": "1.24.0",
   "package": "@mastra/memory",
-  "exports": {
-    "Extractor": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 316
-    },
-    "ModelByInputTokens": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 1354
-    },
-    "OBSERVER_SYSTEM_PROMPT": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js"
-    },
-    "ObservationalMemory": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 28549
-    },
-    "ObservationalMemoryProcessor": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 31183
-    },
-    "TokenCounter": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 22331
-    },
-    "WorkingMemoryExtractor": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 22998
-    },
-    "buildObserverPrompt": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 4504
-    },
-    "buildObserverSystemPrompt": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 3771
-    },
-    "combineObservationGroupRanges": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 1446
-    },
-    "deriveObservationGroupProvenance": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 1480
-    },
-    "extractCurrentTask": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 4627
-    },
-    "formatMessagesForObserver": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 4226
-    },
-    "getObservationsAsOf": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 31405
-    },
-    "hasCurrentTaskSection": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 4615
-    },
-    "injectAnchorIds": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 3326
-    },
-    "optimizeObservationsForContext": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 4638
-    },
-    "parseAnchorId": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 3299
-    },
-    "parseObservationGroups": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 1415
-    },
-    "parseObserverOutput": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 4518
-    },
-    "reconcileObservationGroupsFromReflection": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 1504
-    },
-    "renderObservationGroupsForReflection": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 1460
-    },
-    "stripEphemeralAnchorIds": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 3356
-    },
-    "stripObservationGroups": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 1437
-    },
-    "summarizeConversation": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js"
-    },
-    "wrapInObservationGroup": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 1408
-    },
-    "OBSERVATIONAL_MEMORY_DEFAULTS": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LSJJAJAF.js"
-    },
-    "OBSERVATION_CONTEXT_INSTRUCTIONS": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LSJJAJAF.js"
-    },
-    "OBSERVATION_CONTEXT_PROMPT": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LSJJAJAF.js"
-    },
-    "OBSERVATION_CONTINUATION_HINT": {
-      "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-LSJJAJAF.js"
-    },
-    "Memory": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 24423
-    },
-    "MessageHistory": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js"
-    },
-    "SUMMARIZE_THREAD_DEFAULTS": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js"
-    },
-    "SemanticRecall": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js"
-    },
-    "WorkingMemory": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js"
-    },
-    "deepMergeWorkingMemory": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 24062
-    },
-    "extractWorkingMemoryContent": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 24378
-    },
-    "extractWorkingMemoryTags": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 24346
-    },
-    "removeWorkingMemoryTags": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-XOCZP6LJ.js",
-      "line": 24359
-    },
-    "WORKING_MEMORY_STATE_ID": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-WCGXQIEN.js"
-    },
-    "WORKING_MEMORY_STATE_PROCESSOR_ID": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-WCGXQIEN.js"
-    },
-    "WorkingMemoryStateProcessor": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-WCGXQIEN.js",
-      "line": 7
-    }
-  },
+  "exports": {},
   "modules": {
     "processors": {
       "index": "dist/processors/index.js",
-      "chunks": [
-        "chunk-XOCZP6LJ.js",
-        "chunk-LSJJAJAF.js"
-      ]
+      "chunks": []
     }
   }
 }

package/dist/docs/references/docs-memory-message-history.md

@@ -124,7 +124,7 @@ You can use this history in two ways:
 
 ## Thread title generation
 
-Mastra can automatically generate descriptive thread titles based on the user's first message when `generateTitle` is enabled. Use this option when you build a chat interface that renders conversation titles in a thread list or sidebar.
+Mastra can automatically generate descriptive thread titles from the conversation transcript when `generateTitle` is enabled. Use this option when you build a chat interface that renders conversation titles in a thread list or sidebar.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -263,6 +263,24 @@ const { messages } = await memory.recall({
 })
 ```
 
+Filter by shallow message metadata:
+
+```typescript
+const { messages } = await memory.recall({
+  threadId: 'thread-123',
+  filter: {
+    metadata: {
+      category: 'billing',
+      escalated: true,
+      priority: 2,
+      archivedAt: null,
+    },
+  },
+})
+```
+
+Metadata filters match shallow scalar values only: `string`, finite `number`, `boolean`, and `null`. All specified metadata keys must match with AND semantics, and `null` matches an explicit `null` value, not a missing metadata key. Metadata keys must start with a letter or underscore, may contain only alphanumeric characters and underscores, must be 128 characters or fewer, and can't use reserved prototype keys such as `__proto__`, `constructor`, or `prototype`. Performance depends on the storage backend. Some backends can push parts of the filter into the database, while others scan candidate messages after thread, resource, and date constraints are applied but before pagination.
+
 Fetch a single message by ID:
 
 ```typescript

package/dist/docs/references/reference-memory-memory-class.md

@@ -47,7 +47,7 @@ export const agent = new Agent({
 
 **options.observationalMemory** (`boolean | ObservationalMemoryOptions`): Enable Observational Memory for long-context agentic memory. Set to true for defaults, or pass a config object to customize token budgets, models, and scope. See Observational Memory reference for configuration details.
 
-**options.generateTitle** (`boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> }`): Controls automatic thread title generation from the user's first message. Can be a boolean or an object with custom model and instructions.
+**options.generateTitle** (`boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> }`): Controls automatic thread title generation from the conversation transcript. Can be a boolean or an object with custom model and instructions.
 
 ## Returns
 

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

@@ -91,6 +91,12 @@ Creates a new vector index (collection) in MongoDB.
 
 **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.
@@ -103,7 +109,7 @@ Waits for an index to become ready after creation. Useful when you need to ensur
 
 ### `upsert()`
 
-Adds or updates vectors and their metadata in the collection.
+Adds or updates vectors and their metadata in the collection. On a bring-your-own index this requires `allowWrites: true` at `createIndex()` time — BYO collections are read-only by default.
 
 **indexName** (`string`): Name of the collection to insert into
 
@@ -133,6 +139,122 @@ Searches for similar vectors with optional metadata filtering.
 
 **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()` does **not** 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 does not collide with — and get silently ignored by — a managed collection's auto-created dynamic index. 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'],
+})
+```
+
+> **Note:** 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.
+
+**Note:** 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 do not 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` (requires MongoDB >= 8.0; generally available from 8.1, and on 8.0.x it may need a MongoDB support case to enable — it runs where enabled, e.g. Atlas 8.0.x). A full-text search index must exist: it is 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
+})
+```
+
+**Note:** `hybridQuery()` requires MongoDB >= 8.0 for the `$rankFusion` stage (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` is not 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).
@@ -151,13 +273,18 @@ interface IndexStats {
 
 ### `deleteIndex()`
 
-Deletes a collection and all its data.
+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 did not create.
+
+The BYO classification is recorded durably when the index is created, so it is 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`): Name of the collection to delete
+**indexName** (`string`): Logical name of the index to delete
 
 ### `listIndexes()`
 
-Lists all vector collections in the MongoDB database.
+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 — never the physical collection name — so 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[]>`
 
@@ -165,6 +292,8 @@ Returns: `Promise<string[]>`
 
 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)
@@ -236,11 +365,63 @@ try {
 }
 ```
 
+## 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