@mastra/memory 1.22.2 → 1.23.0-alpha.1

package/dist/docs/references/docs-storage-overview.md

@@ -0,0 +1,214 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Storage overview
+
+Storage is the persistence layer for the Mastra runtime. It keeps memory, workflow state, observability data, eval results, schedules, and long-running agent state available after a process restarts.
+
+Storage powers:
+
+- [Memory](https://mastra.ai/docs/memory/overview): Message history, threads, resources, and working memory.
+- [Workflows](https://mastra.ai/docs/workflows/overview): Durable snapshots for suspended and resumed workflow runs.
+- [Observability](https://mastra.ai/docs/observability/overview): Traces, spans, metrics, logs, and feedback.
+- [Evals](https://mastra.ai/docs/evals/overview): Scores, datasets, experiments, and evaluation results.
+- [Long-running agents](https://mastra.ai/docs/long-running-agents/durable-agents): Background tasks, schedules, goals, and thread state.
+
+## When to configure storage
+
+Configure a persistent storage adapter when state must survive restarts, be shared across processes, or be visible in Studio across sessions. The default in-memory store is useful for tests and short local experiments, but it loses data when the process exits.
+
+Use storage when your application needs any of these behaviors:
+
+- Agents remember past messages or user facts.
+- Workflows suspend and resume after a restart.
+- Traces, metrics, logs, scores, or feedback stay available for analysis.
+- Schedules and background tasks continue across deployments.
+- Multiple runtime processes read and write the same state.
+
+## How storage works
+
+Mastra storage is organized into **domains**. A domain owns one type of runtime data, and a storage adapter implements one or more domains.
+
+| Domain            | What it stores                                                              |
+| ----------------- | --------------------------------------------------------------------------- |
+| `memory`          | Threads, messages, resources, working memory, and other agent memory state. |
+| `workflows`       | Workflow snapshots used to suspend and resume runs.                         |
+| `observability`   | Traces, spans, metrics, logs, and feedback.                                 |
+| `scores`          | Eval score records.                                                         |
+| `datasets`        | Dataset records and dataset items used by evals and experiments.            |
+| `experiments`     | Experiment runs and per-item experiment results.                            |
+| `backgroundTasks` | Background task records and execution state.                                |
+| `schedules`       | Schedule definitions and trigger history.                                   |
+| `threadState`     | Durable task, goal, and thread state.                                       |
+
+Adapter support varies by domain. For the full domain list and built-in schemas, see the [storage overview reference](https://mastra.ai/reference/storage/overview).
+
+## Choose a backend by data shape
+
+Different domains write and query different kinds of data. Pick a backend based on the domain's access pattern:
+
+- `memory`: Reads and writes rows during every remembered agent call. Use a transactional database such as libSQL, PostgreSQL, or MongoDB.
+- `observability`: Writes high-volume telemetry and often queries aggregations. Use a dedicated observability store or an online analytical processing (OLAP) backend such as ClickHouse or DuckDB.
+- `workflows`: Stores durable snapshots that must be available when a run resumes. Use a reliable persistent database.
+- `scores`, `datasets`, and `experiments`: Store lower-frequency evaluation data that's often read later for analysis.
+- `schedules`: Stores schedule definitions and fire history. Use an adapter that implements the schedules domain.
+
+When domains have different operational needs, use [composite storage](#composite-storage) to route each domain to the right backend.
+
+## Get started locally
+
+For local development, use libSQL with a file-backed database. It doesn't require a separate database server and persists state between restarts.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: 'file:./mastra.db',
+  }),
+})
+```
+
+> **Sharing the database with Studio:** When running `mastra dev` alongside your application, use an absolute path so both processes access the same database:
+>
+> ```typescript
+> url: 'file:/absolute/path/to/your/project/mastra.db'
+> ```
+>
+> Relative paths like `file:./mastra.db` resolve based on each process's working directory, which may differ.
+
+Mastra initializes the required storage structures on first use.
+
+## Configure for production
+
+For production, use a persistent managed database. PostgreSQL is a good default for most teams because it works well for transactional runtime state and is widely available as a managed service.
+
+Production guidance:
+
+- Use a managed database with backups, monitoring, and connection pooling.
+- Keep local file databases such as `file:./mastra.db` out of multi-process production deployments.
+- Route high-volume domains, especially `observability`, to a dedicated backend with [composite storage](#composite-storage).
+- Configure [retention](https://mastra.ai/reference/storage/retention) policies on the storage adapter or composite store, then call `storage.prune()` from a scheduler or maintenance job.
+- Choose providers based on the domains your application uses. For example, schedules require an adapter that implements the `schedules` domain.
+
+## Configuration scope
+
+Storage can be configured at the Mastra instance level or at the agent level.
+
+### Instance-level storage
+
+Instance-level storage is shared by agents, workflows, observability, evals, schedules, and other runtime features registered on the same Mastra instance.
+
+**PostgreSQL**:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { PostgresStore } from '@mastra/pg'
+
+export const mastra = new Mastra({
+  storage: new PostgresStore({
+    id: 'mastra-storage',
+    connectionString: process.env.DATABASE_URL,
+  }),
+})
+```
+
+**MongoDB**:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MongoDBStore } from '@mastra/mongodb'
+
+export const mastra = new Mastra({
+  storage: new MongoDBStore({
+    id: 'mastra-storage',
+    uri: process.env.MONGODB_URI,
+    dbName: process.env.MONGODB_DB_NAME,
+  }),
+})
+```
+
+Use instance-level storage when most runtime domains can share the same database.
+
+### Agent-level storage
+
+Agent-level storage is configured on a `Memory` instance. It overrides instance-level storage for that agent's memory data only.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { PostgresStore } from '@mastra/pg'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support agent',
+  instructions: 'Answer customer support questions.',
+  model: 'openai/gpt-5.5',
+  memory: new Memory({
+    storage: new PostgresStore({
+      id: 'support-agent-storage',
+      connectionString: process.env.SUPPORT_AGENT_DATABASE_URL,
+    }),
+  }),
+})
+```
+
+Use agent-level storage when an agent needs an isolated memory boundary or a different memory backend.
+
+## Composite storage
+
+[`MastraCompositeStore`](https://mastra.ai/reference/storage/composite) routes domains to different backends. Use it when one database isn't the right fit for every domain.
+
+The following example uses libSQL as the default store and routes workflow state to PostgreSQL:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { LibSQLStore } from '@mastra/libsql'
+import { WorkflowsPG } from '@mastra/pg'
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite-storage',
+    default: new LibSQLStore({
+      id: 'default-storage',
+      url: 'file:./mastra.db',
+    }),
+    domains: {
+      workflows: new WorkflowsPG({
+        connectionString: process.env.DATABASE_URL,
+      }),
+    },
+  }),
+})
+```
+
+You can also route `observability` to a dedicated analytics backend. See [observability storage](https://mastra.ai/docs/observability/storage) for an observability-specific example.
+
+## Supported providers
+
+Each provider page includes installation instructions, configuration parameters, and usage examples:
+
+- [libSQL](https://mastra.ai/reference/storage/libsql)
+- [PostgreSQL](https://mastra.ai/reference/storage/postgresql)
+- [MongoDB](https://mastra.ai/reference/storage/mongodb)
+- [Upstash](https://mastra.ai/reference/storage/upstash)
+- [Redis](https://mastra.ai/reference/storage/redis)
+- [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)
+- [Cloudflare KV & Durable Objects](https://mastra.ai/reference/storage/cloudflare)
+- [Convex](https://mastra.ai/reference/storage/convex)
+- [DynamoDB](https://mastra.ai/reference/storage/dynamodb)
+- [LanceDB](https://mastra.ai/reference/storage/lance)
+- [Microsoft SQL Server](https://mastra.ai/reference/storage/mssql)
+- [Google Cloud Spanner](https://mastra.ai/reference/storage/spanner)
+
+> **Tip:** libSQL is the fastest path for local development because it doesn't require running a separate database server.
+
+## Next steps
+
+- [Composite storage](https://mastra.ai/reference/storage/composite)
+- [Storage retention](https://mastra.ai/reference/storage/retention)
+- [Storage schemas](https://mastra.ai/reference/storage/overview)
+- [Memory](https://mastra.ai/docs/memory/overview)
+- [Observability storage](https://mastra.ai/docs/observability/storage)

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

@@ -171,7 +171,7 @@ const memory = new Memory({
 - Dynamic extractor functions receive runtime context, including `source`, `threadId`, `resourceId`, `mainAgent`, `memory`, and `requestContext` when available.
 - `WorkingMemoryExtractor` uses the normal extractor pipeline to update working memory through the active `Memory` instance. It uses structured extraction when working memory has a JSON schema and skips OM metadata persistence, so the working memory payload isn't duplicated under OM extracted metadata.
 - `observationalMemory.observation.manageWorkingMemory` adds `WorkingMemoryExtractor`, defaults `workingMemory.agentManaged` to `false`, and defaults `workingMemory.useStateSignals` to `true` when working memory is enabled.
-- Extraction failures are reported in OM marker data and do not discard other successful extracted values.
+- Extraction failures are reported in OM marker data and don't discard other successful extracted values.
 
 ## Examples
 

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

@@ -0,0 +1,99 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# summarizeConversation()
+
+The standalone `summarizeConversation()` function summarizes a conversation in one shot. It distills the messages you pass in with the same Observer plumbing that powers [Observational Memory](https://mastra.ai/reference/memory/observational-memory) — without Observational Memory attached to an agent, and without reading from or writing to storage.
+
+Nothing is written back to memory. The summary and extracted values are returned to you (and to each extractor's `onExtracted` hook), so you decide where they go — for example your own database.
+
+Use this when you already have the messages in hand and want explicit control over what gets summarized. To summarize a stored thread by ID instead, use [`Memory.summarizeThread()`](https://mastra.ai/reference/memory/summarizeThread), which loads the messages for you.
+
+## Usage example
+
+```typescript
+import { summarizeConversation } from '@mastra/memory'
+
+const result = await summarizeConversation({
+  model: 'openai/gpt-5-mini',
+  messages,
+  instructions: 'Summarize this voicemail call for the business owner.',
+})
+```
+
+## Parameters
+
+**model** (`string | LanguageModel | DynamicModel`): Model that runs the summarization, such as a router string like '\_\_GATEWAY\_OPENAI\_MODEL\_MINI\_\_'.
+
+**messages** (`MastraDBMessage[]`): The conversation to summarize. When empty, the function returns an empty result without calling the model.
+
+**instructions** (`string`): Extra guidance appended to the summarizer's system prompt, such as what to focus on or who the summary is for.
+
+**extract** (`Extractor[]`): Extractors to run over the conversation. Extractors with a Zod schema run as a follow-up structured output call; schema-less extractors are extracted inline. Each extractor's onExtracted hook fires with the extracted value.
+
+**threadId** (`string`): Thread the conversation belongs to. Defaults to the first threadId found on messages. Passed to extractor contexts.
+
+**resourceId** (`string`): Resource (user) the conversation belongs to. Defaults to the first resourceId found on messages. Passed to extractor contexts.
+
+**memory** (`Memory`): Memory instance forwarded to extractor contexts. Set automatically when called through Memory.summarizeThread().
+
+**mastra** (`Mastra`): Mastra instance used to resolve custom gateway models. Set automatically when called through Memory.summarizeThread().
+
+**requestContext** (`RequestContext`): Request context forwarded to the summarizer model and extractor hooks.
+
+**abortSignal** (`AbortSignal`): Signal to cancel the summarization call.
+
+## Returns
+
+**summary** (`string`): The distilled observations produced from the conversation, in dense bullet form.
+
+**extracted** (`Record<string, unknown>`): Values produced by extract extractors, keyed by extractor slug.
+
+**extractionFailures** (`{ slug: string; error: string }[]`): Extractors that failed to produce a valid value, with the reason. Only present when at least one extractor failed.
+
+**usage** (`{ inputTokens?: number; outputTokens?: number; totalTokens?: number }`): Token usage of the summarization call.
+
+## Extended usage example
+
+The following example summarizes an in-flight voice session from messages the application already holds, and extracts a structured record:
+
+```typescript
+import { summarizeConversation, Extractor } from '@mastra/memory'
+import type { MastraDBMessage } from '@mastra/core/agent'
+import { z } from 'zod'
+import { sessionRecords } from './db'
+
+const sessionSummary = new Extractor({
+  name: 'session-summary',
+  instructions: 'Return a concise summary of the session.',
+  schema: z.object({
+    summary: z.string(),
+    sentiment: z.enum(['positive', 'neutral', 'negative']),
+    followUps: z.array(z.string()),
+  }),
+  metadataKeyPath: false, // don't persist into memory metadata — the hook owns storage
+  onExtracted: async ({ current, threadId }) => {
+    await sessionRecords.upsert({ sessionId: threadId, record: current })
+  },
+})
+
+export async function onSessionEnd(messages: MastraDBMessage[]) {
+  const { summary, extracted, extractionFailures } = await summarizeConversation({
+    model: 'openai/gpt-5-mini',
+    messages,
+    instructions: 'Summarize this support session for the account manager.',
+    extract: [sessionSummary],
+  })
+
+  if (extractionFailures?.length) {
+    console.warn('Some extractors failed', extractionFailures)
+  }
+
+  return { summary, extracted }
+}
+```
+
+### Related
+
+- [.summarizeThread()](https://mastra.ai/reference/memory/summarizeThread)
+- [Memory Class Reference](https://mastra.ai/reference/memory/memory-class)
+- [Observational Memory](https://mastra.ai/reference/memory/observational-memory)

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

@@ -0,0 +1,93 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Memory.summarizeThread()
+
+The `.summarizeThread()` method summarizes a thread's conversation in one shot. It loads the thread's messages from storage and distills them with the same Observer plumbing that powers [Observational Memory](https://mastra.ai/reference/memory/observational-memory) — as a standalone call, without Observational Memory attached to an agent.
+
+Messages load page-by-page starting from the newest, bounded by `lastMessages` and `maxInputTokens`, so summarizing a long thread doesn't read its entire history from storage.
+
+Nothing is written back to memory. The summary and extracted values are returned to you (and to each extractor's `onExtracted` hook), so you decide where they go — for example your own database.
+
+Use this when a session ends and you want a summary or structured extraction of the whole conversation, such as a voice call at hang-up. To summarize messages you already have in hand (without loading them from a thread), use the standalone [`summarizeConversation()`](https://mastra.ai/reference/memory/summarizeConversation) function instead — it takes the same options with `messages` in place of `threadId`.
+
+## Usage example
+
+```typescript
+const result = await memory.summarizeThread({
+  model: 'openai/gpt-5-mini',
+  threadId: 'thread-123',
+  instructions: 'Summarize this voicemail call for the business owner.',
+})
+```
+
+## Parameters
+
+**threadId** (`string`): The unique identifier of the thread to summarize.
+
+**model** (`string | LanguageModel | DynamicModel`): Model that runs the summarization, such as a router string like '\_\_GATEWAY\_OPENAI\_MODEL\_MINI\_\_'.
+
+**resourceId** (`string`): ID of the resource that owns the thread. If provided, validates thread ownership. Also passed to extractor contexts.
+
+**lastMessages** (`number`): Only summarize the last N messages of the thread. By default the whole thread is loaded, bounded by maxInputTokens.
+
+**maxInputTokens** (`number`): Stop loading older messages once the collected messages exceed this estimated token count. The newest message is always included. (Default: `1000000`)
+
+**instructions** (`string`): Extra guidance appended to the summarizer's system prompt, such as what to focus on or who the summary is for.
+
+**extract** (`Extractor[]`): Extractors to run over the conversation. Extractors with a Zod schema run as a follow-up structured output call; schema-less extractors are extracted inline. Each extractor's onExtracted hook fires with the extracted value.
+
+**requestContext** (`RequestContext`): Request context forwarded to the summarizer model and extractor hooks.
+
+**abortSignal** (`AbortSignal`): Signal to cancel the summarization call.
+
+## Returns
+
+**summary** (`string`): The distilled observations produced from the conversation, in dense bullet form.
+
+**extracted** (`Record<string, unknown>`): Values produced by extract extractors, keyed by extractor slug.
+
+**extractionFailures** (`{ slug: string; error: string }[]`): Extractors that failed to produce a valid value, with the reason. Only present when at least one extractor failed.
+
+**usage** (`{ inputTokens?: number; outputTokens?: number; totalTokens?: number }`): Token usage of the summarization call.
+
+## Extended usage example
+
+The following example summarizes a finished voice call and stores a structured record in the application's own database:
+
+```typescript
+import { Extractor } from '@mastra/memory'
+import { z } from 'zod'
+import { memory } from './mastra/memory'
+import { callRecords } from './db'
+
+const callSummary = new Extractor({
+  name: 'call-summary',
+  instructions: 'Return a concise summary of the call.',
+  schema: z.object({
+    summary: z.string(),
+    sentiment: z.enum(['positive', 'neutral', 'negative']),
+    requestedServices: z.array(z.string()),
+  }),
+  metadataKeyPath: false, // don't persist into memory metadata — the hook owns storage
+  onExtracted: async ({ current, threadId, resourceId }) => {
+    await callRecords.upsert({ callId: threadId, callerId: resourceId, record: current })
+  },
+})
+
+export async function onCallEnd(threadId: string, resourceId: string) {
+  await memory.summarizeThread({
+    model: 'openai/gpt-5-mini',
+    threadId,
+    resourceId,
+    instructions: 'Summarize this voicemail call for the business owner.',
+    extract: [callSummary],
+  })
+}
+```
+
+### Related
+
+- [summarizeConversation()](https://mastra.ai/reference/memory/summarizeConversation)
+- [Memory Class Reference](https://mastra.ai/reference/memory/memory-class)
+- [Observational Memory](https://mastra.ai/reference/memory/observational-memory)
+- [.recall()](https://mastra.ai/reference/memory/recall)

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

@@ -6,7 +6,7 @@ The DynamoDB storage implementation provides a scalable and performant NoSQL dat
 
 > **Observability Not Supported:** DynamoDB storage **doesn't support the observability domain**. Traces from the `MastraStorageExporter` can't be persisted to DynamoDB, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with DynamoDB as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse.
 
-> **Item Size Limit:** DynamoDB enforces a **400 KB maximum item size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/storage) for workarounds including uploading attachments to external storage.
+> **Item Size Limit:** DynamoDB enforces a **400 KB maximum item size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/memory-processors) for workarounds including uploading attachments to external storage.
 
 ## Features
 

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

@@ -32,7 +32,7 @@ bun add @mastra/mongodb@latest
 
 ## Usage
 
-Ensure you have a MongoDB Atlas Local (via Docker) or MongoDB Atlas Cloud instance with Atlas Search enabled. MongoDB 7.0+ is recommended.
+Ensure you have a [MongoDB Atlas Local (via Docker)](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-docker/) or [MongoDB Atlas Cloud](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-getting-started/) instance with Atlas Search enabled. MongoDB 7.0+ is recommended.
 
 ```typescript
 import { MongoDBStore } from '@mastra/mongodb'
@@ -40,7 +40,7 @@ import { MongoDBStore } from '@mastra/mongodb'
 const storage = new MongoDBStore({
   id: 'mongodb-storage',
   uri: process.env.MONGODB_URI,
-  dbName: process.env.MONGODB_DATABASE,
+  dbName: process.env.MONGODB_DB_NAME,
 })
 ```
 
@@ -54,7 +54,15 @@ const storage = new MongoDBStore({
 
 **dbName** (`string`): The name of the database you want the storage to use.
 
-**options** (`MongoClientOptions`): MongoDB client options for advanced configuration (SSL, connection pooling, etc.).
+**options** (`MongoClientOptions`): MongoDB client options for advanced configuration (SSL, connection pooling, etc.). See Connection Options
+
+**disableInit** (`boolean`): When true, automatic initialization (collection creation) is disabled. Useful for CI/CD pipelines where you want to run migrations explicitly. You must call storage.init() manually when this is true.
+
+**skipDefaultIndexes** (`boolean`): When true, default indexes will not be created during initialization. Useful when managing indexes separately or using only custom indexes.
+
+**indexes** (`MongoDBIndexConfig[]`): Custom indexes to create during initialization. Each index must specify a collection, keys, and optional index options. See Indexes
+
+**connectorHandler** (`ConnectorHandler`): Custom connection handler for advanced connection management. Alternative to providing uri/dbName directly.
 
 > **Deprecation Notice:** The `url` parameter is deprecated but still supported for backward compatibility. Please use `uri` instead in all new code.
 
@@ -84,6 +92,26 @@ const store2 = new MongoDBStore({
     socketTimeoutMS: 45000,
   },
 })
+
+// With custom indexes
+const store3 = new MongoDBStore({
+  id: 'mongodb-storage-03',
+  uri: 'mongodb+srv://user:password@cluster.mongodb.net',
+  dbName: 'mastra_storage',
+  indexes: [
+    { collection: 'mastra_threads', keys: { 'metadata.type': 1 } },
+    { collection: 'mastra_messages', keys: { 'metadata.status': 1 }, options: { sparse: true } },
+  ],
+})
+
+// For CI/CD with explicit initialization
+const store4 = new MongoDBStore({
+  id: 'mongodb-storage-04',
+  uri: 'mongodb+srv://user:password@cluster.mongodb.net',
+  dbName: 'mastra_storage',
+  disableInit: true, // Disable auto-init
+})
+await store4.init() // Call init explicitly
 ```
 
 ## Additional notes
@@ -114,7 +142,7 @@ import { MongoDBStore } from '@mastra/mongodb'
 const storage = new MongoDBStore({
   id: 'mongodb-storage',
   uri: process.env.MONGODB_URI,
-  dbName: process.env.MONGODB_DATABASE,
+  dbName: process.env.MONGODB_DB_NAME,
 })
 
 const mastra = new Mastra({
@@ -130,7 +158,7 @@ import { MongoDBStore } from '@mastra/mongodb'
 const storage = new MongoDBStore({
   id: 'mongodb-storage',
   uri: process.env.MONGODB_URI,
-  dbName: process.env.MONGODB_DATABASE,
+  dbName: process.env.MONGODB_DB_NAME,
 })
 
 // Required when using storage directly
@@ -143,57 +171,28 @@ const thread = await memoryStore?.getThreadById({ threadId: '...' })
 
 > **Warning:** If `init()` isn't called, collections won't be created and storage operations will fail silently or throw errors.
 
-## Vector search capabilities
-
-MongoDB storage includes built-in vector search capabilities for AI applications:
+### Connection Management
 
-### Vector Index Creation
+The `close()` method closes the MongoDB client connection. Call this when shutting down your application:
 
 ```typescript
-import { MongoDBVector } from '@mastra/mongodb'
+import { MongoDBStore } from '@mastra/mongodb'
 
-const vectorStore = new MongoDBVector({
-  id: 'mongodb-vector',
+const storage = new MongoDBStore({
+  id: 'mongodb-storage',
   uri: process.env.MONGODB_URI,
-  dbName: process.env.MONGODB_DATABASE,
+  dbName: process.env.MONGODB_DB_NAME,
 })
 
-// Create a vector index for embeddings
-await vectorStore.createIndex({
-  indexName: 'document_embeddings',
-  dimension: 1536,
-})
+// Use storage...
+
+// Clean up on shutdown
+await storage.close()
 ```
 
-### Vector Operations
+## Vector search capabilities
 
-```typescript
-// Store vectors with metadata
-await vectorStore.upsert({
-  indexName: "document_embeddings",
-  vectors: [
-    {
-      id: "doc-1",
-      values: [0.1, 0.2, 0.3, ...], // 1536-dimensional vector
-      metadata: {
-        title: "Document Title",
-        category: "technical",
-        source: "api-docs",
-      },
-    },
-  ],
-});
-
-// Similarity search
-const results = await vectorStore.query({
-  indexName: "document_embeddings",
-  vector: queryEmbedding,
-  topK: 5,
-  filter: {
-    category: "technical",
-  },
-});
-```
+MongoDB storage includes built-in vector search capabilities for AI applications. For detailed vector operations including index creation, upserting embeddings, similarity search, and metadata filtering, see the [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb).
 
 ## Usage example
 
@@ -214,6 +213,7 @@ export const mongodbAgent = new Agent({
   model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new MongoDBStore({
+      id: 'mongodb-storage',
       uri: process.env.MONGODB_URI!,
       dbName: process.env.MONGODB_DB_NAME!,
     }),