@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.
- package/CHANGELOG.md +8 -0
- package/dist/{chunk-TB6SV7QK.js → chunk-5PG7DW2T.js} +4 -4
- package/dist/{chunk-TB6SV7QK.js.map → chunk-5PG7DW2T.js.map} +1 -1
- package/dist/{chunk-3JX4RMDN.cjs → chunk-G6PR4XBO.cjs} +4 -4
- package/dist/{chunk-3JX4RMDN.cjs.map → chunk-G6PR4XBO.cjs.map} +1 -1
- package/dist/docs/SKILL.md +3 -3
- package/dist/docs/assets/SOURCE_MAP.json +35 -35
- package/dist/docs/references/docs-agents-agent-approval.md +2 -2
- package/dist/docs/references/docs-agents-networks.md +1 -1
- package/dist/docs/references/docs-long-running-agents-background-tasks.md +2 -2
- package/dist/docs/references/docs-long-running-agents-goals.md +4 -4
- package/dist/docs/references/docs-memory-memory-processors.md +67 -0
- package/dist/docs/references/docs-memory-message-history.md +56 -2
- package/dist/docs/references/docs-memory-observational-memory.md +3 -3
- package/dist/docs/references/docs-memory-overview.md +3 -3
- package/dist/docs/references/docs-memory-semantic-recall.md +35 -1
- package/dist/docs/references/docs-storage-overview.md +214 -0
- package/dist/docs/references/reference-memory-observational-memory.md +1 -1
- package/dist/docs/references/reference-storage-dynamodb.md +1 -1
- package/dist/docs/references/reference-storage-mongodb.md +46 -46
- package/dist/docs/references/reference-vectors-mongodb.md +93 -4
- package/dist/index.cjs +13 -13
- package/dist/index.js +1 -1
- package/dist/{observational-memory-TEIGXE56.cjs → observational-memory-36K5KQCO.cjs} +28 -28
- package/dist/{observational-memory-TEIGXE56.cjs.map → observational-memory-36K5KQCO.cjs.map} +1 -1
- package/dist/{observational-memory-NNGAOKRQ.js → observational-memory-JABZ6XNI.js} +3 -3
- package/dist/{observational-memory-NNGAOKRQ.js.map → observational-memory-JABZ6XNI.js.map} +1 -1
- package/dist/processors/index.cjs +26 -26
- package/dist/processors/index.js +1 -1
- package/package.json +5 -5
- 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
|
|
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/
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
-
|
|
147
|
-
|
|
148
|
-
MongoDB storage includes built-in vector search capabilities for AI applications:
|
|
174
|
+
### Connection Management
|
|
149
175
|
|
|
150
|
-
|
|
176
|
+
The `close()` method closes the MongoDB client connection. Call this when shutting down your application:
|
|
151
177
|
|
|
152
178
|
```typescript
|
|
153
|
-
import {
|
|
179
|
+
import { MongoDBStore } from '@mastra/mongodb'
|
|
154
180
|
|
|
155
|
-
const
|
|
156
|
-
id: 'mongodb-
|
|
181
|
+
const storage = new MongoDBStore({
|
|
182
|
+
id: 'mongodb-storage',
|
|
157
183
|
uri: process.env.MONGODB_URI,
|
|
158
|
-
dbName: process.env.
|
|
184
|
+
dbName: process.env.MONGODB_DB_NAME,
|
|
159
185
|
})
|
|
160
186
|
|
|
161
|
-
//
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
})
|
|
187
|
+
// Use storage...
|
|
188
|
+
|
|
189
|
+
// Clean up on shutdown
|
|
190
|
+
await storage.close()
|
|
166
191
|
```
|
|
167
192
|
|
|
168
|
-
|
|
193
|
+
## Vector search capabilities
|
|
169
194
|
|
|
170
|
-
|
|
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.
|
|
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.
|
|
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:**
|
|
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
|
|
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
|
|
10
|
+
get: function () { return chunkG6PR4XBO_cjs.Extractor; }
|
|
11
11
|
});
|
|
12
12
|
Object.defineProperty(exports, "Memory", {
|
|
13
13
|
enumerable: true,
|
|
14
|
-
get: function () { return
|
|
14
|
+
get: function () { return chunkG6PR4XBO_cjs.Memory; }
|
|
15
15
|
});
|
|
16
16
|
Object.defineProperty(exports, "MessageHistory", {
|
|
17
17
|
enumerable: true,
|
|
18
|
-
get: function () { return
|
|
18
|
+
get: function () { return chunkG6PR4XBO_cjs.MessageHistory; }
|
|
19
19
|
});
|
|
20
20
|
Object.defineProperty(exports, "ModelByInputTokens", {
|
|
21
21
|
enumerable: true,
|
|
22
|
-
get: function () { return
|
|
22
|
+
get: function () { return chunkG6PR4XBO_cjs.ModelByInputTokens; }
|
|
23
23
|
});
|
|
24
24
|
Object.defineProperty(exports, "SemanticRecall", {
|
|
25
25
|
enumerable: true,
|
|
26
|
-
get: function () { return
|
|
26
|
+
get: function () { return chunkG6PR4XBO_cjs.SemanticRecall; }
|
|
27
27
|
});
|
|
28
28
|
Object.defineProperty(exports, "WorkingMemory", {
|
|
29
29
|
enumerable: true,
|
|
30
|
-
get: function () { return
|
|
30
|
+
get: function () { return chunkG6PR4XBO_cjs.WorkingMemory; }
|
|
31
31
|
});
|
|
32
32
|
Object.defineProperty(exports, "WorkingMemoryExtractor", {
|
|
33
33
|
enumerable: true,
|
|
34
|
-
get: function () { return
|
|
34
|
+
get: function () { return chunkG6PR4XBO_cjs.WorkingMemoryExtractor; }
|
|
35
35
|
});
|
|
36
36
|
Object.defineProperty(exports, "deepMergeWorkingMemory", {
|
|
37
37
|
enumerable: true,
|
|
38
|
-
get: function () { return
|
|
38
|
+
get: function () { return chunkG6PR4XBO_cjs.deepMergeWorkingMemory; }
|
|
39
39
|
});
|
|
40
40
|
Object.defineProperty(exports, "extractWorkingMemoryContent", {
|
|
41
41
|
enumerable: true,
|
|
42
|
-
get: function () { return
|
|
42
|
+
get: function () { return chunkG6PR4XBO_cjs.extractWorkingMemoryContent; }
|
|
43
43
|
});
|
|
44
44
|
Object.defineProperty(exports, "extractWorkingMemoryTags", {
|
|
45
45
|
enumerable: true,
|
|
46
|
-
get: function () { return
|
|
46
|
+
get: function () { return chunkG6PR4XBO_cjs.extractWorkingMemoryTags; }
|
|
47
47
|
});
|
|
48
48
|
Object.defineProperty(exports, "getObservationsAsOf", {
|
|
49
49
|
enumerable: true,
|
|
50
|
-
get: function () { return
|
|
50
|
+
get: function () { return chunkG6PR4XBO_cjs.getObservationsAsOf; }
|
|
51
51
|
});
|
|
52
52
|
Object.defineProperty(exports, "removeWorkingMemoryTags", {
|
|
53
53
|
enumerable: true,
|
|
54
|
-
get: function () { return
|
|
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-
|
|
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
|