@mastra/memory 1.22.2 → 1.22.3-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/dist/{chunk-TB6SV7QK.js → chunk-5PG7DW2T.js} +4 -4
  3. package/dist/{chunk-TB6SV7QK.js.map → chunk-5PG7DW2T.js.map} +1 -1
  4. package/dist/{chunk-3JX4RMDN.cjs → chunk-G6PR4XBO.cjs} +4 -4
  5. package/dist/{chunk-3JX4RMDN.cjs.map → chunk-G6PR4XBO.cjs.map} +1 -1
  6. package/dist/docs/SKILL.md +3 -3
  7. package/dist/docs/assets/SOURCE_MAP.json +35 -35
  8. package/dist/docs/references/docs-agents-agent-approval.md +2 -2
  9. package/dist/docs/references/docs-agents-networks.md +1 -1
  10. package/dist/docs/references/docs-long-running-agents-background-tasks.md +2 -2
  11. package/dist/docs/references/docs-long-running-agents-goals.md +4 -4
  12. package/dist/docs/references/docs-memory-memory-processors.md +67 -0
  13. package/dist/docs/references/docs-memory-message-history.md +56 -2
  14. package/dist/docs/references/docs-memory-observational-memory.md +3 -3
  15. package/dist/docs/references/docs-memory-overview.md +3 -3
  16. package/dist/docs/references/docs-memory-semantic-recall.md +35 -1
  17. package/dist/docs/references/docs-storage-overview.md +214 -0
  18. package/dist/docs/references/reference-memory-observational-memory.md +1 -1
  19. package/dist/docs/references/reference-storage-dynamodb.md +1 -1
  20. package/dist/docs/references/reference-storage-mongodb.md +46 -46
  21. package/dist/docs/references/reference-vectors-mongodb.md +93 -4
  22. package/dist/index.cjs +13 -13
  23. package/dist/index.js +1 -1
  24. package/dist/{observational-memory-TEIGXE56.cjs → observational-memory-36K5KQCO.cjs} +28 -28
  25. package/dist/{observational-memory-TEIGXE56.cjs.map → observational-memory-36K5KQCO.cjs.map} +1 -1
  26. package/dist/{observational-memory-NNGAOKRQ.js → observational-memory-JABZ6XNI.js} +3 -3
  27. package/dist/{observational-memory-NNGAOKRQ.js.map → observational-memory-JABZ6XNI.js.map} +1 -1
  28. package/dist/processors/index.cjs +26 -26
  29. package/dist/processors/index.js +1 -1
  30. package/package.json +5 -5
  31. package/dist/docs/references/docs-memory-storage.md +0 -267
@@ -0,0 +1,214 @@
1
+ > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
+
3
+ # Storage overview
4
+
5
+ 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.
6
+
7
+ Storage powers:
8
+
9
+ - [Memory](https://mastra.ai/docs/memory/overview): Message history, threads, resources, and working memory.
10
+ - [Workflows](https://mastra.ai/docs/workflows/overview): Durable snapshots for suspended and resumed workflow runs.
11
+ - [Observability](https://mastra.ai/docs/observability/overview): Traces, spans, metrics, logs, and feedback.
12
+ - [Evals](https://mastra.ai/docs/evals/overview): Scores, datasets, experiments, and evaluation results.
13
+ - [Long-running agents](https://mastra.ai/docs/long-running-agents/durable-agents): Background tasks, schedules, goals, and thread state.
14
+
15
+ ## When to configure storage
16
+
17
+ 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.
18
+
19
+ Use storage when your application needs any of these behaviors:
20
+
21
+ - Agents remember past messages or user facts.
22
+ - Workflows suspend and resume after a restart.
23
+ - Traces, metrics, logs, scores, or feedback stay available for analysis.
24
+ - Schedules and background tasks continue across deployments.
25
+ - Multiple runtime processes read and write the same state.
26
+
27
+ ## How storage works
28
+
29
+ Mastra storage is organized into **domains**. A domain owns one type of runtime data, and a storage adapter implements one or more domains.
30
+
31
+ | Domain | What it stores |
32
+ | ----------------- | --------------------------------------------------------------------------- |
33
+ | `memory` | Threads, messages, resources, working memory, and other agent memory state. |
34
+ | `workflows` | Workflow snapshots used to suspend and resume runs. |
35
+ | `observability` | Traces, spans, metrics, logs, and feedback. |
36
+ | `scores` | Eval score records. |
37
+ | `datasets` | Dataset records and dataset items used by evals and experiments. |
38
+ | `experiments` | Experiment runs and per-item experiment results. |
39
+ | `backgroundTasks` | Background task records and execution state. |
40
+ | `schedules` | Schedule definitions and trigger history. |
41
+ | `threadState` | Durable task, goal, and thread state. |
42
+
43
+ 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).
44
+
45
+ ## Choose a backend by data shape
46
+
47
+ Different domains write and query different kinds of data. Pick a backend based on the domain's access pattern:
48
+
49
+ - `memory`: Reads and writes rows during every remembered agent call. Use a transactional database such as libSQL, PostgreSQL, or MongoDB.
50
+ - `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.
51
+ - `workflows`: Stores durable snapshots that must be available when a run resumes. Use a reliable persistent database.
52
+ - `scores`, `datasets`, and `experiments`: Store lower-frequency evaluation data that's often read later for analysis.
53
+ - `schedules`: Stores schedule definitions and fire history. Use an adapter that implements the schedules domain.
54
+
55
+ When domains have different operational needs, use [composite storage](#composite-storage) to route each domain to the right backend.
56
+
57
+ ## Get started locally
58
+
59
+ For local development, use libSQL with a file-backed database. It doesn't require a separate database server and persists state between restarts.
60
+
61
+ ```typescript
62
+ import { Mastra } from '@mastra/core'
63
+ import { LibSQLStore } from '@mastra/libsql'
64
+
65
+ export const mastra = new Mastra({
66
+ storage: new LibSQLStore({
67
+ id: 'mastra-storage',
68
+ url: 'file:./mastra.db',
69
+ }),
70
+ })
71
+ ```
72
+
73
+ > **Sharing the database with Studio:** When running `mastra dev` alongside your application, use an absolute path so both processes access the same database:
74
+ >
75
+ > ```typescript
76
+ > url: 'file:/absolute/path/to/your/project/mastra.db'
77
+ > ```
78
+ >
79
+ > Relative paths like `file:./mastra.db` resolve based on each process's working directory, which may differ.
80
+
81
+ Mastra initializes the required storage structures on first use.
82
+
83
+ ## Configure for production
84
+
85
+ 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.
86
+
87
+ Production guidance:
88
+
89
+ - Use a managed database with backups, monitoring, and connection pooling.
90
+ - Keep local file databases such as `file:./mastra.db` out of multi-process production deployments.
91
+ - Route high-volume domains, especially `observability`, to a dedicated backend with [composite storage](#composite-storage).
92
+ - 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.
93
+ - Choose providers based on the domains your application uses. For example, schedules require an adapter that implements the `schedules` domain.
94
+
95
+ ## Configuration scope
96
+
97
+ Storage can be configured at the Mastra instance level or at the agent level.
98
+
99
+ ### Instance-level storage
100
+
101
+ Instance-level storage is shared by agents, workflows, observability, evals, schedules, and other runtime features registered on the same Mastra instance.
102
+
103
+ **PostgreSQL**:
104
+
105
+ ```typescript
106
+ import { Mastra } from '@mastra/core'
107
+ import { PostgresStore } from '@mastra/pg'
108
+
109
+ export const mastra = new Mastra({
110
+ storage: new PostgresStore({
111
+ id: 'mastra-storage',
112
+ connectionString: process.env.DATABASE_URL,
113
+ }),
114
+ })
115
+ ```
116
+
117
+ **MongoDB**:
118
+
119
+ ```typescript
120
+ import { Mastra } from '@mastra/core'
121
+ import { MongoDBStore } from '@mastra/mongodb'
122
+
123
+ export const mastra = new Mastra({
124
+ storage: new MongoDBStore({
125
+ id: 'mastra-storage',
126
+ uri: process.env.MONGODB_URI,
127
+ dbName: process.env.MONGODB_DB_NAME,
128
+ }),
129
+ })
130
+ ```
131
+
132
+ Use instance-level storage when most runtime domains can share the same database.
133
+
134
+ ### Agent-level storage
135
+
136
+ Agent-level storage is configured on a `Memory` instance. It overrides instance-level storage for that agent's memory data only.
137
+
138
+ ```typescript
139
+ import { Agent } from '@mastra/core/agent'
140
+ import { Memory } from '@mastra/memory'
141
+ import { PostgresStore } from '@mastra/pg'
142
+
143
+ export const supportAgent = new Agent({
144
+ id: 'support-agent',
145
+ name: 'Support agent',
146
+ instructions: 'Answer customer support questions.',
147
+ model: 'openai/gpt-5.5',
148
+ memory: new Memory({
149
+ storage: new PostgresStore({
150
+ id: 'support-agent-storage',
151
+ connectionString: process.env.SUPPORT_AGENT_DATABASE_URL,
152
+ }),
153
+ }),
154
+ })
155
+ ```
156
+
157
+ Use agent-level storage when an agent needs an isolated memory boundary or a different memory backend.
158
+
159
+ ## Composite storage
160
+
161
+ [`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.
162
+
163
+ The following example uses libSQL as the default store and routes workflow state to PostgreSQL:
164
+
165
+ ```typescript
166
+ import { Mastra } from '@mastra/core'
167
+ import { MastraCompositeStore } from '@mastra/core/storage'
168
+ import { LibSQLStore } from '@mastra/libsql'
169
+ import { WorkflowsPG } from '@mastra/pg'
170
+
171
+ export const mastra = new Mastra({
172
+ storage: new MastraCompositeStore({
173
+ id: 'composite-storage',
174
+ default: new LibSQLStore({
175
+ id: 'default-storage',
176
+ url: 'file:./mastra.db',
177
+ }),
178
+ domains: {
179
+ workflows: new WorkflowsPG({
180
+ connectionString: process.env.DATABASE_URL,
181
+ }),
182
+ },
183
+ }),
184
+ })
185
+ ```
186
+
187
+ You can also route `observability` to a dedicated analytics backend. See [observability storage](https://mastra.ai/docs/observability/storage) for an observability-specific example.
188
+
189
+ ## Supported providers
190
+
191
+ Each provider page includes installation instructions, configuration parameters, and usage examples:
192
+
193
+ - [libSQL](https://mastra.ai/reference/storage/libsql)
194
+ - [PostgreSQL](https://mastra.ai/reference/storage/postgresql)
195
+ - [MongoDB](https://mastra.ai/reference/storage/mongodb)
196
+ - [Upstash](https://mastra.ai/reference/storage/upstash)
197
+ - [Redis](https://mastra.ai/reference/storage/redis)
198
+ - [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)
199
+ - [Cloudflare KV & Durable Objects](https://mastra.ai/reference/storage/cloudflare)
200
+ - [Convex](https://mastra.ai/reference/storage/convex)
201
+ - [DynamoDB](https://mastra.ai/reference/storage/dynamodb)
202
+ - [LanceDB](https://mastra.ai/reference/storage/lance)
203
+ - [Microsoft SQL Server](https://mastra.ai/reference/storage/mssql)
204
+ - [Google Cloud Spanner](https://mastra.ai/reference/storage/spanner)
205
+
206
+ > **Tip:** libSQL is the fastest path for local development because it doesn't require running a separate database server.
207
+
208
+ ## Next steps
209
+
210
+ - [Composite storage](https://mastra.ai/reference/storage/composite)
211
+ - [Storage retention](https://mastra.ai/reference/storage/retention)
212
+ - [Storage schemas](https://mastra.ai/reference/storage/overview)
213
+ - [Memory](https://mastra.ai/docs/memory/overview)
214
+ - [Observability storage](https://mastra.ai/docs/observability/storage)
@@ -171,7 +171,7 @@ const memory = new Memory({
171
171
  - Dynamic extractor functions receive runtime context, including `source`, `threadId`, `resourceId`, `mainAgent`, `memory`, and `requestContext` when available.
172
172
  - `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.
173
173
  - `observationalMemory.observation.manageWorkingMemory` adds `WorkingMemoryExtractor`, defaults `workingMemory.agentManaged` to `false`, and defaults `workingMemory.useStateSignals` to `true` when working memory is enabled.
174
- - Extraction failures are reported in OM marker data and do not discard other successful extracted values.
174
+ - Extraction failures are reported in OM marker data and don't discard other successful extracted values.
175
175
 
176
176
  ## Examples
177
177
 
@@ -6,7 +6,7 @@ The DynamoDB storage implementation provides a scalable and performant NoSQL dat
6
6
 
7
7
  > **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.
8
8
 
9
- > **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.
9
+ > **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.
10
10
 
11
11
  ## Features
12
12
 
@@ -32,7 +32,7 @@ bun add @mastra/mongodb@latest
32
32
 
33
33
  ## Usage
34
34
 
35
- Ensure you have a MongoDB Atlas Local (via Docker) or MongoDB Atlas Cloud instance with Atlas Search enabled. MongoDB 7.0+ is recommended.
35
+ 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.
36
36
 
37
37
  ```typescript
38
38
  import { MongoDBStore } from '@mastra/mongodb'
@@ -40,7 +40,7 @@ import { MongoDBStore } from '@mastra/mongodb'
40
40
  const storage = new MongoDBStore({
41
41
  id: 'mongodb-storage',
42
42
  uri: process.env.MONGODB_URI,
43
- dbName: process.env.MONGODB_DATABASE,
43
+ dbName: process.env.MONGODB_DB_NAME,
44
44
  })
45
45
  ```
46
46
 
@@ -54,7 +54,15 @@ const storage = new MongoDBStore({
54
54
 
55
55
  **dbName** (`string`): The name of the database you want the storage to use.
56
56
 
57
- **options** (`MongoClientOptions`): MongoDB client options for advanced configuration (SSL, connection pooling, etc.).
57
+ **options** (`MongoClientOptions`): MongoDB client options for advanced configuration (SSL, connection pooling, etc.). See Connection Options
58
+
59
+ **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.
60
+
61
+ **skipDefaultIndexes** (`boolean`): When true, default indexes will not be created during initialization. Useful when managing indexes separately or using only custom indexes.
62
+
63
+ **indexes** (`MongoDBIndexConfig[]`): Custom indexes to create during initialization. Each index must specify a collection, keys, and optional index options. See Indexes
64
+
65
+ **connectorHandler** (`ConnectorHandler`): Custom connection handler for advanced connection management. Alternative to providing uri/dbName directly.
58
66
 
59
67
  > **Deprecation Notice:** The `url` parameter is deprecated but still supported for backward compatibility. Please use `uri` instead in all new code.
60
68
 
@@ -84,6 +92,26 @@ const store2 = new MongoDBStore({
84
92
  socketTimeoutMS: 45000,
85
93
  },
86
94
  })
95
+
96
+ // With custom indexes
97
+ const store3 = new MongoDBStore({
98
+ id: 'mongodb-storage-03',
99
+ uri: 'mongodb+srv://user:password@cluster.mongodb.net',
100
+ dbName: 'mastra_storage',
101
+ indexes: [
102
+ { collection: 'mastra_threads', keys: { 'metadata.type': 1 } },
103
+ { collection: 'mastra_messages', keys: { 'metadata.status': 1 }, options: { sparse: true } },
104
+ ],
105
+ })
106
+
107
+ // For CI/CD with explicit initialization
108
+ const store4 = new MongoDBStore({
109
+ id: 'mongodb-storage-04',
110
+ uri: 'mongodb+srv://user:password@cluster.mongodb.net',
111
+ dbName: 'mastra_storage',
112
+ disableInit: true, // Disable auto-init
113
+ })
114
+ await store4.init() // Call init explicitly
87
115
  ```
88
116
 
89
117
  ## Additional notes
@@ -114,7 +142,7 @@ import { MongoDBStore } from '@mastra/mongodb'
114
142
  const storage = new MongoDBStore({
115
143
  id: 'mongodb-storage',
116
144
  uri: process.env.MONGODB_URI,
117
- dbName: process.env.MONGODB_DATABASE,
145
+ dbName: process.env.MONGODB_DB_NAME,
118
146
  })
119
147
 
120
148
  const mastra = new Mastra({
@@ -130,7 +158,7 @@ import { MongoDBStore } from '@mastra/mongodb'
130
158
  const storage = new MongoDBStore({
131
159
  id: 'mongodb-storage',
132
160
  uri: process.env.MONGODB_URI,
133
- dbName: process.env.MONGODB_DATABASE,
161
+ dbName: process.env.MONGODB_DB_NAME,
134
162
  })
135
163
 
136
164
  // Required when using storage directly
@@ -143,57 +171,28 @@ const thread = await memoryStore?.getThreadById({ threadId: '...' })
143
171
 
144
172
  > **Warning:** If `init()` isn't called, collections won't be created and storage operations will fail silently or throw errors.
145
173
 
146
- ## Vector search capabilities
147
-
148
- MongoDB storage includes built-in vector search capabilities for AI applications:
174
+ ### Connection Management
149
175
 
150
- ### Vector Index Creation
176
+ The `close()` method closes the MongoDB client connection. Call this when shutting down your application:
151
177
 
152
178
  ```typescript
153
- import { MongoDBVector } from '@mastra/mongodb'
179
+ import { MongoDBStore } from '@mastra/mongodb'
154
180
 
155
- const vectorStore = new MongoDBVector({
156
- id: 'mongodb-vector',
181
+ const storage = new MongoDBStore({
182
+ id: 'mongodb-storage',
157
183
  uri: process.env.MONGODB_URI,
158
- dbName: process.env.MONGODB_DATABASE,
184
+ dbName: process.env.MONGODB_DB_NAME,
159
185
  })
160
186
 
161
- // Create a vector index for embeddings
162
- await vectorStore.createIndex({
163
- indexName: 'document_embeddings',
164
- dimension: 1536,
165
- })
187
+ // Use storage...
188
+
189
+ // Clean up on shutdown
190
+ await storage.close()
166
191
  ```
167
192
 
168
- ### Vector Operations
193
+ ## Vector search capabilities
169
194
 
170
- ```typescript
171
- // Store vectors with metadata
172
- await vectorStore.upsert({
173
- indexName: "document_embeddings",
174
- vectors: [
175
- {
176
- id: "doc-1",
177
- values: [0.1, 0.2, 0.3, ...], // 1536-dimensional vector
178
- metadata: {
179
- title: "Document Title",
180
- category: "technical",
181
- source: "api-docs",
182
- },
183
- },
184
- ],
185
- });
186
-
187
- // Similarity search
188
- const results = await vectorStore.query({
189
- indexName: "document_embeddings",
190
- vector: queryEmbedding,
191
- topK: 5,
192
- filter: {
193
- category: "technical",
194
- },
195
- });
196
- ```
195
+ 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).
197
196
 
198
197
  ## Usage example
199
198
 
@@ -214,6 +213,7 @@ export const mongodbAgent = new Agent({
214
213
  model: 'openai/gpt-5.5',
215
214
  memory: new Memory({
216
215
  storage: new MongoDBStore({
216
+ id: 'mongodb-storage',
217
217
  uri: process.env.MONGODB_URI!,
218
218
  dbName: process.env.MONGODB_DB_NAME!,
219
219
  }),
@@ -38,7 +38,7 @@ import { MongoDBVector } from '@mastra/mongodb'
38
38
  const store = new MongoDBVector({
39
39
  id: 'mongodb-vector',
40
40
  uri: process.env.MONGODB_URI,
41
- dbName: process.env.MONGODB_DATABASE,
41
+ dbName: process.env.MONGODB_DB_NAME,
42
42
  })
43
43
  ```
44
44
 
@@ -52,7 +52,7 @@ import { MongoDBVector } from '@mastra/mongodb'
52
52
  const store = new MongoDBVector({
53
53
  id: 'mongodb-vector',
54
54
  uri: process.env.MONGODB_URI,
55
- dbName: process.env.MONGODB_DATABASE,
55
+ dbName: process.env.MONGODB_DB_NAME,
56
56
  embeddingFieldPath: 'text.contentEmbedding', // Store embeddings at text.contentEmbedding
57
57
  })
58
58
  ```
@@ -71,6 +71,14 @@ const store = new MongoDBVector({
71
71
 
72
72
  ## Methods
73
73
 
74
+ ### `connect()`
75
+
76
+ Establishes connection to the MongoDB server. This is called automatically on first use, but can be called explicitly if needed.
77
+
78
+ ```typescript
79
+ await store.connect()
80
+ ```
81
+
74
82
  ### `createIndex()`
75
83
 
76
84
  Creates a new vector index (collection) in MongoDB.
@@ -81,6 +89,16 @@ Creates a new vector index (collection) in MongoDB.
81
89
 
82
90
  **metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
83
91
 
92
+ ### `waitForIndexReady()`
93
+
94
+ Waits for an index to become ready after creation. Useful when you need to ensure an index is ready before performing operations.
95
+
96
+ **indexName** (`string`): Name of the index to wait for
97
+
98
+ **timeoutMs** (`number`): Maximum time to wait in milliseconds (Default: `60000`)
99
+
100
+ **checkIntervalMs** (`number`): Interval between status checks in milliseconds (Default: `2000`)
101
+
84
102
  ### `upsert()`
85
103
 
86
104
  Adds or updates vectors and their metadata in the collection.
@@ -93,6 +111,8 @@ Adds or updates vectors and their metadata in the collection.
93
111
 
94
112
  **ids** (`string[]`): Optional vector IDs (auto-generated if not provided)
95
113
 
114
+ **documents** (`string[]`): Optional document text content to store alongside vectors
115
+
96
116
  ### `query()`
97
117
 
98
118
  Searches for similar vectors with optional metadata filtering.
@@ -109,6 +129,8 @@ Searches for similar vectors with optional metadata filtering.
109
129
 
110
130
  **includeVector** (`boolean`): Whether to include vector data in results (Default: `false`)
111
131
 
132
+ **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)`)
133
+
112
134
  ### `describeIndex()`
113
135
 
114
136
  Returns information about the index (collection).
@@ -224,7 +246,7 @@ try {
224
246
 
225
247
  Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve related messages by meaning (not keywords).
226
248
 
227
- > **Note:** You must use a deployment hosted on MongoDB Atlas to successfully use the MongoDB Vector database.
249
+ > **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/).
228
250
 
229
251
  This setup uses FastEmbed, a local embedding model, to generate vector embeddings. To use this, install `@mastra/fastembed`:
230
252
 
@@ -290,6 +312,73 @@ export const mongodbAgent = new Agent({
290
312
  })
291
313
  ```
292
314
 
315
+ ### Vector embeddings with VoyageAI
316
+
317
+ VoyageAI provides specialized embedding models optimized for retrieval tasks. VoyageAI is also integrated with MongoDB Atlas for multimodal embeddings.
318
+
319
+ **npm**:
320
+
321
+ ```bash
322
+ npm install @mastra/voyageai@latest
323
+ ```
324
+
325
+ **pnpm**:
326
+
327
+ ```bash
328
+ pnpm add @mastra/voyageai@latest
329
+ ```
330
+
331
+ **Yarn**:
332
+
333
+ ```bash
334
+ yarn add @mastra/voyageai@latest
335
+ ```
336
+
337
+ **Bun**:
338
+
339
+ ```bash
340
+ bun add @mastra/voyageai@latest
341
+ ```
342
+
343
+ Basic usage example:
344
+
345
+ ```typescript
346
+ import { Memory } from '@mastra/memory'
347
+ import { Agent } from '@mastra/core/agent'
348
+ import { MongoDBStore, MongoDBVector } from '@mastra/mongodb'
349
+ import { voyage } from '@mastra/voyageai'
350
+
351
+ export const mongodbVoyageAgent = new Agent({
352
+ id: 'mongodb-voyage-agent',
353
+ name: 'MongoDB VoyageAI Agent',
354
+ instructions: 'You are an AI agent with semantic recall powered by VoyageAI and MongoDB.',
355
+ model: 'openai/gpt-5.5',
356
+ memory: new Memory({
357
+ storage: new MongoDBStore({
358
+ id: 'mongodb-storage',
359
+ uri: process.env.MONGODB_URI!,
360
+ dbName: process.env.MONGODB_DB_NAME!,
361
+ }),
362
+ vector: new MongoDBVector({
363
+ id: 'mongodb-vector',
364
+ uri: process.env.MONGODB_URI!,
365
+ dbName: process.env.MONGODB_DB_NAME!,
366
+ }),
367
+ embedder: voyage, // VoyageAI's default model (voyage-3.5, 1024 dimensions)
368
+ options: {
369
+ lastMessages: 10,
370
+ semanticRecall: {
371
+ topK: 5,
372
+ messageRange: 2,
373
+ },
374
+ },
375
+ }),
376
+ })
377
+ ```
378
+
379
+ For comprehensive VoyageAI embedding examples including specialized models, multimodal embeddings, and retrieval optimization, see the [VoyageAI embeddings documentation](https://mastra.ai/models/embeddings).
380
+
293
381
  ## Related
294
382
 
295
- - [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)
383
+ - [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)
384
+ - [VoyageAI Embeddings Documentation](https://mastra.ai/models/embeddings)
package/dist/index.cjs CHANGED
@@ -1,57 +1,57 @@
1
1
  'use strict';
2
2
 
3
- var chunk3JX4RMDN_cjs = require('./chunk-3JX4RMDN.cjs');
3
+ var chunkG6PR4XBO_cjs = require('./chunk-G6PR4XBO.cjs');
4
4
  var chunk43FJOLKM_cjs = require('./chunk-43FJOLKM.cjs');
5
5
 
6
6
 
7
7
 
8
8
  Object.defineProperty(exports, "Extractor", {
9
9
  enumerable: true,
10
- get: function () { return chunk3JX4RMDN_cjs.Extractor; }
10
+ get: function () { return chunkG6PR4XBO_cjs.Extractor; }
11
11
  });
12
12
  Object.defineProperty(exports, "Memory", {
13
13
  enumerable: true,
14
- get: function () { return chunk3JX4RMDN_cjs.Memory; }
14
+ get: function () { return chunkG6PR4XBO_cjs.Memory; }
15
15
  });
16
16
  Object.defineProperty(exports, "MessageHistory", {
17
17
  enumerable: true,
18
- get: function () { return chunk3JX4RMDN_cjs.MessageHistory; }
18
+ get: function () { return chunkG6PR4XBO_cjs.MessageHistory; }
19
19
  });
20
20
  Object.defineProperty(exports, "ModelByInputTokens", {
21
21
  enumerable: true,
22
- get: function () { return chunk3JX4RMDN_cjs.ModelByInputTokens; }
22
+ get: function () { return chunkG6PR4XBO_cjs.ModelByInputTokens; }
23
23
  });
24
24
  Object.defineProperty(exports, "SemanticRecall", {
25
25
  enumerable: true,
26
- get: function () { return chunk3JX4RMDN_cjs.SemanticRecall; }
26
+ get: function () { return chunkG6PR4XBO_cjs.SemanticRecall; }
27
27
  });
28
28
  Object.defineProperty(exports, "WorkingMemory", {
29
29
  enumerable: true,
30
- get: function () { return chunk3JX4RMDN_cjs.WorkingMemory; }
30
+ get: function () { return chunkG6PR4XBO_cjs.WorkingMemory; }
31
31
  });
32
32
  Object.defineProperty(exports, "WorkingMemoryExtractor", {
33
33
  enumerable: true,
34
- get: function () { return chunk3JX4RMDN_cjs.WorkingMemoryExtractor; }
34
+ get: function () { return chunkG6PR4XBO_cjs.WorkingMemoryExtractor; }
35
35
  });
36
36
  Object.defineProperty(exports, "deepMergeWorkingMemory", {
37
37
  enumerable: true,
38
- get: function () { return chunk3JX4RMDN_cjs.deepMergeWorkingMemory; }
38
+ get: function () { return chunkG6PR4XBO_cjs.deepMergeWorkingMemory; }
39
39
  });
40
40
  Object.defineProperty(exports, "extractWorkingMemoryContent", {
41
41
  enumerable: true,
42
- get: function () { return chunk3JX4RMDN_cjs.extractWorkingMemoryContent; }
42
+ get: function () { return chunkG6PR4XBO_cjs.extractWorkingMemoryContent; }
43
43
  });
44
44
  Object.defineProperty(exports, "extractWorkingMemoryTags", {
45
45
  enumerable: true,
46
- get: function () { return chunk3JX4RMDN_cjs.extractWorkingMemoryTags; }
46
+ get: function () { return chunkG6PR4XBO_cjs.extractWorkingMemoryTags; }
47
47
  });
48
48
  Object.defineProperty(exports, "getObservationsAsOf", {
49
49
  enumerable: true,
50
- get: function () { return chunk3JX4RMDN_cjs.getObservationsAsOf; }
50
+ get: function () { return chunkG6PR4XBO_cjs.getObservationsAsOf; }
51
51
  });
52
52
  Object.defineProperty(exports, "removeWorkingMemoryTags", {
53
53
  enumerable: true,
54
- get: function () { return chunk3JX4RMDN_cjs.removeWorkingMemoryTags; }
54
+ get: function () { return chunkG6PR4XBO_cjs.removeWorkingMemoryTags; }
55
55
  });
56
56
  Object.defineProperty(exports, "WORKING_MEMORY_STATE_ID", {
57
57
  enumerable: true,
package/dist/index.js CHANGED
@@ -1,4 +1,4 @@
1
- export { Extractor, Memory, MessageHistory, ModelByInputTokens, SemanticRecall, WorkingMemory, WorkingMemoryExtractor, deepMergeWorkingMemory, extractWorkingMemoryContent, extractWorkingMemoryTags, getObservationsAsOf, removeWorkingMemoryTags } from './chunk-TB6SV7QK.js';
1
+ export { Extractor, Memory, MessageHistory, ModelByInputTokens, SemanticRecall, WorkingMemory, WorkingMemoryExtractor, deepMergeWorkingMemory, extractWorkingMemoryContent, extractWorkingMemoryTags, getObservationsAsOf, removeWorkingMemoryTags } from './chunk-5PG7DW2T.js';
2
2
  export { WORKING_MEMORY_STATE_ID, WORKING_MEMORY_STATE_PROCESSOR_ID, WorkingMemoryStateProcessor } from './chunk-WCGXQIEN.js';
3
3
  //# sourceMappingURL=index.js.map
4
4
  //# sourceMappingURL=index.js.map