@mastra/libsql 1.2.0-alpha.0 → 1.3.0-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 +176 -0
- package/dist/docs/SKILL.md +36 -26
- package/dist/docs/{SOURCE_MAP.json → assets/SOURCE_MAP.json} +1 -1
- package/dist/docs/{agents/03-agent-approval.md → references/docs-agents-agent-approval.md} +19 -19
- package/dist/docs/references/docs-agents-agent-memory.md +212 -0
- package/dist/docs/{agents/04-network-approval.md → references/docs-agents-network-approval.md} +13 -12
- package/dist/docs/{agents/02-networks.md → references/docs-agents-networks.md} +10 -12
- package/dist/docs/{memory/06-memory-processors.md → references/docs-memory-memory-processors.md} +6 -8
- package/dist/docs/{memory/03-message-history.md → references/docs-memory-message-history.md} +31 -20
- package/dist/docs/{memory/01-overview.md → references/docs-memory-overview.md} +8 -8
- package/dist/docs/{memory/05-semantic-recall.md → references/docs-memory-semantic-recall.md} +33 -17
- package/dist/docs/{memory/02-storage.md → references/docs-memory-storage.md} +29 -39
- package/dist/docs/{memory/04-working-memory.md → references/docs-memory-working-memory.md} +16 -27
- package/dist/docs/{observability/01-overview.md → references/docs-observability-overview.md} +4 -7
- package/dist/docs/{observability/02-default.md → references/docs-observability-tracing-exporters-default.md} +11 -14
- package/dist/docs/{rag/01-retrieval.md → references/docs-rag-retrieval.md} +26 -53
- package/dist/docs/{workflows/01-snapshots.md → references/docs-workflows-snapshots.md} +3 -5
- package/dist/docs/{guides/01-ai-sdk.md → references/guides-agent-frameworks-ai-sdk.md} +25 -9
- package/dist/docs/references/reference-core-getMemory.md +50 -0
- package/dist/docs/references/reference-core-listMemory.md +56 -0
- package/dist/docs/references/reference-core-mastra-class.md +66 -0
- package/dist/docs/{memory/07-reference.md → references/reference-memory-memory-class.md} +28 -14
- package/dist/docs/references/reference-storage-composite.md +235 -0
- package/dist/docs/references/reference-storage-dynamodb.md +282 -0
- package/dist/docs/references/reference-storage-libsql.md +135 -0
- package/dist/docs/{vectors/01-reference.md → references/reference-vectors-libsql.md} +105 -13
- package/dist/index.cjs +1676 -194
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +1676 -196
- package/dist/index.js.map +1 -1
- package/dist/storage/db/index.d.ts.map +1 -1
- package/dist/storage/domains/agents/index.d.ts +9 -12
- package/dist/storage/domains/agents/index.d.ts.map +1 -1
- package/dist/storage/domains/memory/index.d.ts +7 -1
- package/dist/storage/domains/memory/index.d.ts.map +1 -1
- package/dist/storage/domains/prompt-blocks/index.d.ts +25 -0
- package/dist/storage/domains/prompt-blocks/index.d.ts.map +1 -0
- package/dist/storage/domains/scorer-definitions/index.d.ts +26 -0
- package/dist/storage/domains/scorer-definitions/index.d.ts.map +1 -0
- package/dist/storage/index.d.ts +3 -1
- package/dist/storage/index.d.ts.map +1 -1
- package/package.json +5 -6
- package/dist/docs/README.md +0 -39
- package/dist/docs/agents/01-agent-memory.md +0 -166
- package/dist/docs/core/01-reference.md +0 -151
- package/dist/docs/storage/01-reference.md +0 -556
|
@@ -1,8 +1,6 @@
|
|
|
1
|
-
> Learn how to configure working memory in Mastra to store persistent user data, preferences.
|
|
2
|
-
|
|
3
1
|
# Working Memory
|
|
4
2
|
|
|
5
|
-
While [message history](https://mastra.ai/docs/memory/message-history) and [semantic recall](
|
|
3
|
+
While [message history](https://mastra.ai/docs/memory/message-history) and [semantic recall](https://mastra.ai/docs/memory/semantic-recall) help agents remember conversations, working memory allows them to maintain persistent information about users across interactions.
|
|
6
4
|
|
|
7
5
|
Think of it as the agent's active thoughts or scratchpad – the key information they keep available about the user or task. It's similar to how a person would naturally remember someone's name, preferences, or important details during a conversation.
|
|
8
6
|
|
|
@@ -19,7 +17,7 @@ Working memory can persist at two different scopes:
|
|
|
19
17
|
|
|
20
18
|
Here's a minimal example of setting up an agent with working memory:
|
|
21
19
|
|
|
22
|
-
```typescript
|
|
20
|
+
```typescript
|
|
23
21
|
import { Agent } from "@mastra/core/agent";
|
|
24
22
|
import { Memory } from "@mastra/memory";
|
|
25
23
|
|
|
@@ -43,7 +41,7 @@ const agent = new Agent({
|
|
|
43
41
|
|
|
44
42
|
Working memory is a block of Markdown text that the agent is able to update over time to store continuously relevant information:
|
|
45
43
|
|
|
46
|
-
|
|
44
|
+
[YouTube video player](https://www.youtube-nocookie.com/embed/UMy_JHLf1n8)
|
|
47
45
|
|
|
48
46
|
## Memory Persistence Scopes
|
|
49
47
|
|
|
@@ -136,7 +134,7 @@ Templates guide the agent on what information to track and update in working mem
|
|
|
136
134
|
|
|
137
135
|
Here's an example of a custom template. In this example the agent will store the users name, location, timezone, etc as soon as the user sends a message containing any of the info:
|
|
138
136
|
|
|
139
|
-
```typescript
|
|
137
|
+
```typescript
|
|
140
138
|
const memory = new Memory({
|
|
141
139
|
options: {
|
|
142
140
|
workingMemory: {
|
|
@@ -172,19 +170,13 @@ const memory = new Memory({
|
|
|
172
170
|
|
|
173
171
|
## Designing Effective Templates
|
|
174
172
|
|
|
175
|
-
A well-structured template keeps the information easy for the agent to parse and update. Treat the
|
|
176
|
-
template as a short form that you want the assistant to keep up to date.
|
|
173
|
+
A well-structured template keeps the information easy for the agent to parse and update. Treat the template as a short form that you want the assistant to keep up to date.
|
|
177
174
|
|
|
178
|
-
- **Short, focused labels.** Avoid paragraphs or very long headings. Keep labels brief (for example
|
|
179
|
-
|
|
180
|
-
- **
|
|
181
|
-
|
|
182
|
-
- **
|
|
183
|
-
fill in the correct spots.
|
|
184
|
-
- **Abbreviate very long values.** If you only need a short form, include guidance like
|
|
185
|
-
`- Name: [First name or nickname]` or `- Address (short):` rather than the full legal text.
|
|
186
|
-
- **Mention update rules in `instructions`.** You can instruct how and when to fill or clear parts of
|
|
187
|
-
the template directly in the agent's `instructions` field.
|
|
175
|
+
- **Short, focused labels.** Avoid paragraphs or very long headings. Keep labels brief (for example `## Personal Info` or `- Name:`) so updates are easy to read and less likely to be truncated.
|
|
176
|
+
- **Use consistent casing.** Inconsistent capitalization (`Timezone:` vs `timezone:`) can cause messy updates. Stick to Title Case or lower case for headings and bullet labels.
|
|
177
|
+
- **Keep placeholder text simple.** Use hints such as `[e.g., Formal]` or `[Date]` to help the LLM fill in the correct spots.
|
|
178
|
+
- **Abbreviate very long values.** If you only need a short form, include guidance like `- Name: [First name or nickname]` or `- Address (short):` rather than the full legal text.
|
|
179
|
+
- **Mention update rules in `instructions`.** You can instruct how and when to fill or clear parts of the template directly in the agent's `instructions` field.
|
|
188
180
|
|
|
189
181
|
### Alternative Template Styles
|
|
190
182
|
|
|
@@ -281,8 +273,7 @@ Schema-based working memory uses **merge semantics**, meaning the agent only nee
|
|
|
281
273
|
|
|
282
274
|
## Example: Multi-step Retention
|
|
283
275
|
|
|
284
|
-
Below is a simplified view of how the `User Profile` template updates across a short user
|
|
285
|
-
conversation:
|
|
276
|
+
Below is a simplified view of how the `User Profile` template updates across a short user conversation:
|
|
286
277
|
|
|
287
278
|
```nohighlight
|
|
288
279
|
# User Profile
|
|
@@ -308,11 +299,9 @@ conversation:
|
|
|
308
299
|
- Timezone: CET
|
|
309
300
|
```
|
|
310
301
|
|
|
311
|
-
The agent can now refer to `Sam` or `Berlin` in later responses without requesting the information
|
|
312
|
-
again because it has been stored in working memory.
|
|
302
|
+
The agent can now refer to `Sam` or `Berlin` in later responses without requesting the information again because it has been stored in working memory.
|
|
313
303
|
|
|
314
|
-
If your agent is not properly updating working memory when you expect it to, you can add system
|
|
315
|
-
instructions on _how_ and _when_ to use this template in your agent's `instructions` setting.
|
|
304
|
+
If your agent is not properly updating working memory when you expect it to, you can add system instructions on _how_ and _when_ to use this template in your agent's `instructions` setting.
|
|
316
305
|
|
|
317
306
|
## Setting Initial Working Memory
|
|
318
307
|
|
|
@@ -322,7 +311,7 @@ While agents typically update working memory through the `updateWorkingMemory` t
|
|
|
322
311
|
|
|
323
312
|
When creating a thread, you can provide initial working memory through the metadata's `workingMemory` key:
|
|
324
313
|
|
|
325
|
-
```typescript
|
|
314
|
+
```typescript
|
|
326
315
|
// Create a thread with initial working memory
|
|
327
316
|
const thread = await memory.createThread({
|
|
328
317
|
threadId: "thread-123",
|
|
@@ -353,7 +342,7 @@ await agent.generate("What's my blood type?", {
|
|
|
353
342
|
|
|
354
343
|
You can also update an existing thread's working memory:
|
|
355
344
|
|
|
356
|
-
```typescript
|
|
345
|
+
```typescript
|
|
357
346
|
// Update thread metadata to add/modify working memory
|
|
358
347
|
await memory.updateThread({
|
|
359
348
|
id: "thread-123",
|
|
@@ -375,7 +364,7 @@ await memory.updateThread({
|
|
|
375
364
|
|
|
376
365
|
Alternatively, use the `updateWorkingMemory` method directly:
|
|
377
366
|
|
|
378
|
-
```typescript
|
|
367
|
+
```typescript
|
|
379
368
|
await memory.updateWorkingMemory({
|
|
380
369
|
threadId: "thread-123",
|
|
381
370
|
resourceId: "user-456", // Required for resource-scoped memory
|
package/dist/docs/{observability/01-overview.md → references/docs-observability-overview.md}
RENAMED
|
@@ -1,5 +1,3 @@
|
|
|
1
|
-
> Monitor and debug applications with Mastra
|
|
2
|
-
|
|
3
1
|
# Observability Overview
|
|
4
2
|
|
|
5
3
|
Mastra provides observability features for AI applications. Monitor LLM operations, trace agent decisions, and debug complex workflows with tools that understand AI-specific patterns.
|
|
@@ -17,15 +15,15 @@ Specialized tracing for AI operations that captures:
|
|
|
17
15
|
|
|
18
16
|
## Storage Requirements
|
|
19
17
|
|
|
20
|
-
The `DefaultExporter` persists traces to your configured storage backend. Not all storage providers support observability—for the full list, see [Storage Provider Support](https://mastra.ai/docs/observability/tracing/exporters/default
|
|
18
|
+
The `DefaultExporter` persists traces to your configured storage backend. Not all storage providers support observability—for the full list, see [Storage Provider Support](https://mastra.ai/docs/observability/tracing/exporters/default).
|
|
21
19
|
|
|
22
|
-
For production environments with high traffic, we recommend using **ClickHouse** for the observability domain via [composite storage](https://mastra.ai/reference/storage/composite). See [Production Recommendations](https://mastra.ai/docs/observability/tracing/exporters/default
|
|
20
|
+
For production environments with high traffic, we recommend using **ClickHouse** for the observability domain via [composite storage](https://mastra.ai/reference/storage/composite). See [Production Recommendations](https://mastra.ai/docs/observability/tracing/exporters/default) for details.
|
|
23
21
|
|
|
24
22
|
## Quick Start
|
|
25
23
|
|
|
26
24
|
Configure Observability in your Mastra instance:
|
|
27
25
|
|
|
28
|
-
```typescript
|
|
26
|
+
```typescript
|
|
29
27
|
import { Mastra } from "@mastra/core";
|
|
30
28
|
import { PinoLogger } from "@mastra/loggers";
|
|
31
29
|
import { LibSQLStore } from "@mastra/libsql";
|
|
@@ -59,8 +57,7 @@ export const mastra = new Mastra({
|
|
|
59
57
|
});
|
|
60
58
|
```
|
|
61
59
|
|
|
62
|
-
> **Serverless environments
|
|
63
|
-
The `file:./mastra.db` storage URL uses the local filesystem, which doesn't work in serverless environments like Vercel, AWS Lambda, or Cloudflare Workers. For serverless deployments, use external storage. See the [Vercel deployment guide](https://mastra.ai/guides/deployment/vercel-deployer#observability) for a complete example.
|
|
60
|
+
> **Serverless environments:** The `file:./mastra.db` storage URL uses the local filesystem, which doesn't work in serverless environments like Vercel, AWS Lambda, or Cloudflare Workers. For serverless deployments, use external storage. See the [Vercel deployment guide](https://mastra.ai/guides/deployment/vercel) for a complete example.
|
|
64
61
|
|
|
65
62
|
With this basic setup, you will see Traces and Logs in both Studio and in Mastra Cloud.
|
|
66
63
|
|
|
@@ -1,11 +1,8 @@
|
|
|
1
|
-
> Store traces locally for development and debugging
|
|
2
|
-
|
|
3
1
|
# Default Exporter
|
|
4
2
|
|
|
5
3
|
The `DefaultExporter` persists traces to your configured storage backend, making them accessible through Studio. It's automatically enabled when using the default observability configuration and requires no external services.
|
|
6
4
|
|
|
7
|
-
> **Production Observability**
|
|
8
|
-
Observability data can quickly overwhelm general-purpose databases in production. For high-traffic applications, we recommend using **ClickHouse** for the observability storage domain via [composite storage](https://mastra.ai/reference/storage/composite). See [Production Recommendations](#production-recommendations) for details.
|
|
5
|
+
> **Production Observability:** Observability data can quickly overwhelm general-purpose databases in production. For high-traffic applications, we recommend using **ClickHouse** for the observability storage domain via [composite storage](https://mastra.ai/reference/storage/composite). See [Production Recommendations](#production-recommendations) for details.
|
|
9
6
|
|
|
10
7
|
## Configuration
|
|
11
8
|
|
|
@@ -16,7 +13,7 @@ Observability data can quickly overwhelm general-purpose databases in production
|
|
|
16
13
|
|
|
17
14
|
### Basic Setup
|
|
18
15
|
|
|
19
|
-
```typescript
|
|
16
|
+
```typescript
|
|
20
17
|
import { Mastra } from "@mastra/core";
|
|
21
18
|
import { Observability, DefaultExporter } from "@mastra/observability";
|
|
22
19
|
import { LibSQLStore } from "@mastra/libsql";
|
|
@@ -119,13 +116,13 @@ If you set the strategy to `'auto'`, the `DefaultExporter` automatically selects
|
|
|
119
116
|
|
|
120
117
|
### Providers with Observability Support
|
|
121
118
|
|
|
122
|
-
| Storage Provider
|
|
123
|
-
|
|
|
124
|
-
| **ClickHouse** (`@mastra/clickhouse`)
|
|
125
|
-
| **[PostgreSQL](https://mastra.ai/reference/storage/postgresql)** | batch-with-updates | batch-with-updates, insert-only
|
|
126
|
-
| **[MSSQL](https://mastra.ai/reference/storage/mssql)** | batch-with-updates | batch-with-updates, insert-only
|
|
127
|
-
| **[MongoDB](https://mastra.ai/reference/storage/mongodb)** | batch-with-updates | batch-with-updates, insert-only
|
|
128
|
-
| **[libSQL](https://mastra.ai/reference/storage/libsql)** | batch-with-updates | batch-with-updates, insert-only
|
|
119
|
+
| Storage Provider | Preferred Strategy | Supported Strategies | Recommended Use |
|
|
120
|
+
| ---------------------------------------------------------------- | ------------------ | ------------------------------- | ------------------------------------- |
|
|
121
|
+
| **ClickHouse** (`@mastra/clickhouse`) | insert-only | insert-only | Production (high-volume) |
|
|
122
|
+
| **[PostgreSQL](https://mastra.ai/reference/storage/postgresql)** | batch-with-updates | batch-with-updates, insert-only | Production (low volume) |
|
|
123
|
+
| **[MSSQL](https://mastra.ai/reference/storage/mssql)** | batch-with-updates | batch-with-updates, insert-only | Production (low volume) |
|
|
124
|
+
| **[MongoDB](https://mastra.ai/reference/storage/mongodb)** | batch-with-updates | batch-with-updates, insert-only | Production (low volume) |
|
|
125
|
+
| **[libSQL](https://mastra.ai/reference/storage/libsql)** | batch-with-updates | batch-with-updates, insert-only | Default storage, good for development |
|
|
129
126
|
|
|
130
127
|
### Providers without Observability Support
|
|
131
128
|
|
|
@@ -150,7 +147,7 @@ Observability data grows quickly in production environments. A single agent inte
|
|
|
150
147
|
|
|
151
148
|
### Recommended: ClickHouse for High-Volume Production
|
|
152
149
|
|
|
153
|
-
[ClickHouse](https://mastra.ai/reference/storage/composite
|
|
150
|
+
[ClickHouse](https://mastra.ai/reference/storage/composite) is a columnar database designed for high-volume analytics workloads. It's the recommended choice for production observability because:
|
|
154
151
|
|
|
155
152
|
- **Optimized for writes**: Handles millions of inserts per second
|
|
156
153
|
- **Efficient compression**: Reduces storage costs for trace data
|
|
@@ -159,7 +156,7 @@ Observability data grows quickly in production environments. A single agent inte
|
|
|
159
156
|
|
|
160
157
|
### Using Composite Storage
|
|
161
158
|
|
|
162
|
-
If you're using a provider without observability support (like Convex or DynamoDB) or want to optimize performance, use [composite storage](https://mastra.ai/reference/storage/composite
|
|
159
|
+
If you're using a provider without observability support (like Convex or DynamoDB) or want to optimize performance, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to ClickHouse while keeping other data in your primary database.
|
|
163
160
|
|
|
164
161
|
## Batching Behavior
|
|
165
162
|
|
|
@@ -1,5 +1,3 @@
|
|
|
1
|
-
> Guide on retrieval processes in Mastra
|
|
2
|
-
|
|
3
1
|
# Retrieval in RAG Systems
|
|
4
2
|
|
|
5
3
|
After storing embeddings, you need to retrieve relevant chunks to answer user queries.
|
|
@@ -168,10 +166,9 @@ This is particularly useful when:
|
|
|
168
166
|
|
|
169
167
|
The Vector Query Tool supports database-specific configurations that enable you to leverage unique features and optimizations of different vector stores.
|
|
170
168
|
|
|
171
|
-
> **Note:**
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
Connection credentials (URLs, auth tokens) are configured when you instantiate the vector store class (e.g., `new LibSQLVector({ url: '...' })`).
|
|
169
|
+
> **Note:** These configurations are for **query-time options** like namespaces, performance tuning, and filtering—not for database connection setup.
|
|
170
|
+
>
|
|
171
|
+
> Connection credentials (URLs, auth tokens) are configured when you instantiate the vector store class (e.g., `new LibSQLVector({ url: '...' })`).
|
|
175
172
|
|
|
176
173
|
```ts
|
|
177
174
|
import { createVectorQueryTool } from "@mastra/rag";
|
|
@@ -268,10 +265,9 @@ For detailed configuration options and advanced usage, see the [Vector Query Too
|
|
|
268
265
|
|
|
269
266
|
### Vector Store Prompts
|
|
270
267
|
|
|
271
|
-
Vector store prompts define query patterns and filtering capabilities for each vector database implementation.
|
|
272
|
-
When implementing filtering, these prompts are required in the agent's instructions to specify valid operators and syntax for each vector store implementation.
|
|
268
|
+
Vector store prompts define query patterns and filtering capabilities for each vector database implementation. When implementing filtering, these prompts are required in the agent's instructions to specify valid operators and syntax for each vector store implementation.
|
|
273
269
|
|
|
274
|
-
|
|
270
|
+
**pgVector**:
|
|
275
271
|
|
|
276
272
|
```ts
|
|
277
273
|
import { PGVECTOR_PROMPT } from "@mastra/pg";
|
|
@@ -288,11 +284,9 @@ export const ragAgent = new Agent({
|
|
|
288
284
|
});
|
|
289
285
|
```
|
|
290
286
|
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
**pinecone:**
|
|
287
|
+
**Pinecone**:
|
|
294
288
|
|
|
295
|
-
```ts
|
|
289
|
+
```ts
|
|
296
290
|
import { PINECONE_PROMPT } from "@mastra/pinecone";
|
|
297
291
|
|
|
298
292
|
export const ragAgent = new Agent({
|
|
@@ -307,11 +301,9 @@ export const ragAgent = new Agent({
|
|
|
307
301
|
});
|
|
308
302
|
```
|
|
309
303
|
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
**qdrant:**
|
|
304
|
+
**Qdrant**:
|
|
313
305
|
|
|
314
|
-
```ts
|
|
306
|
+
```ts
|
|
315
307
|
import { QDRANT_PROMPT } from "@mastra/qdrant";
|
|
316
308
|
|
|
317
309
|
export const ragAgent = new Agent({
|
|
@@ -326,11 +318,9 @@ export const ragAgent = new Agent({
|
|
|
326
318
|
});
|
|
327
319
|
```
|
|
328
320
|
|
|
329
|
-
|
|
321
|
+
**Chroma**:
|
|
330
322
|
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
```ts title="vector-store.ts"
|
|
323
|
+
```ts
|
|
334
324
|
import { CHROMA_PROMPT } from "@mastra/chroma";
|
|
335
325
|
|
|
336
326
|
export const ragAgent = new Agent({
|
|
@@ -345,11 +335,9 @@ export const ragAgent = new Agent({
|
|
|
345
335
|
});
|
|
346
336
|
```
|
|
347
337
|
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
**astra:**
|
|
338
|
+
**Astra**:
|
|
351
339
|
|
|
352
|
-
```ts
|
|
340
|
+
```ts
|
|
353
341
|
import { ASTRA_PROMPT } from "@mastra/astra";
|
|
354
342
|
|
|
355
343
|
export const ragAgent = new Agent({
|
|
@@ -364,11 +352,9 @@ export const ragAgent = new Agent({
|
|
|
364
352
|
});
|
|
365
353
|
```
|
|
366
354
|
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
**libsql:**
|
|
355
|
+
**libSQL**:
|
|
370
356
|
|
|
371
|
-
```ts
|
|
357
|
+
```ts
|
|
372
358
|
import { LIBSQL_PROMPT } from "@mastra/libsql";
|
|
373
359
|
|
|
374
360
|
export const ragAgent = new Agent({
|
|
@@ -383,11 +369,9 @@ export const ragAgent = new Agent({
|
|
|
383
369
|
});
|
|
384
370
|
```
|
|
385
371
|
|
|
386
|
-
|
|
372
|
+
**Upstash**:
|
|
387
373
|
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
```ts title="vector-store.ts"
|
|
374
|
+
```ts
|
|
391
375
|
import { UPSTASH_PROMPT } from "@mastra/upstash";
|
|
392
376
|
|
|
393
377
|
export const ragAgent = new Agent({
|
|
@@ -402,11 +386,9 @@ export const ragAgent = new Agent({
|
|
|
402
386
|
});
|
|
403
387
|
```
|
|
404
388
|
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
**vectorize:**
|
|
389
|
+
**Vectorize**:
|
|
408
390
|
|
|
409
|
-
```ts
|
|
391
|
+
```ts
|
|
410
392
|
import { VECTORIZE_PROMPT } from "@mastra/vectorize";
|
|
411
393
|
|
|
412
394
|
export const ragAgent = new Agent({
|
|
@@ -421,11 +403,9 @@ export const ragAgent = new Agent({
|
|
|
421
403
|
});
|
|
422
404
|
```
|
|
423
405
|
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
**mongodb:**
|
|
406
|
+
**MongoDB**:
|
|
427
407
|
|
|
428
|
-
```ts
|
|
408
|
+
```ts
|
|
429
409
|
import { MONGODB_PROMPT } from "@mastra/mongodb";
|
|
430
410
|
|
|
431
411
|
export const ragAgent = new Agent({
|
|
@@ -440,11 +420,9 @@ export const ragAgent = new Agent({
|
|
|
440
420
|
});
|
|
441
421
|
```
|
|
442
422
|
|
|
443
|
-
|
|
423
|
+
**OpenSearch**:
|
|
444
424
|
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
```ts title="vector-store.ts"
|
|
425
|
+
```ts
|
|
448
426
|
import { OPENSEARCH_PROMPT } from "@mastra/opensearch";
|
|
449
427
|
|
|
450
428
|
export const ragAgent = new Agent({
|
|
@@ -459,11 +437,9 @@ export const ragAgent = new Agent({
|
|
|
459
437
|
});
|
|
460
438
|
```
|
|
461
439
|
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
**s3vectors:**
|
|
440
|
+
**S3Vectors**:
|
|
465
441
|
|
|
466
|
-
```ts
|
|
442
|
+
```ts
|
|
467
443
|
import { S3VECTORS_PROMPT } from "@mastra/s3vectors";
|
|
468
444
|
|
|
469
445
|
export const ragAgent = new Agent({
|
|
@@ -478,8 +454,6 @@ export const ragAgent = new Agent({
|
|
|
478
454
|
});
|
|
479
455
|
```
|
|
480
456
|
|
|
481
|
-
|
|
482
|
-
|
|
483
457
|
### Re-ranking
|
|
484
458
|
|
|
485
459
|
Initial vector similarity search can sometimes miss nuanced relevance. Re-ranking is a more computationally expensive process, but more accurate algorithm that improves results by:
|
|
@@ -528,8 +502,7 @@ The weights control how different factors influence the final ranking:
|
|
|
528
502
|
- `vector`: Higher values favor the original vector similarity scores
|
|
529
503
|
- `position`: Higher values help maintain the original ordering of results
|
|
530
504
|
|
|
531
|
-
> **Note:**
|
|
532
|
-
For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
|
|
505
|
+
> **Note:** For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
|
|
533
506
|
|
|
534
507
|
You can also use other relevance score providers like Cohere or ZeroEntropy:
|
|
535
508
|
|
|
@@ -1,5 +1,3 @@
|
|
|
1
|
-
> Learn how to save and resume workflow execution state with snapshots in Mastra
|
|
2
|
-
|
|
3
1
|
# Snapshots
|
|
4
2
|
|
|
5
3
|
In Mastra, a snapshot is a serializable representation of a workflow's complete execution state at a specific point in time. Snapshots capture all the information needed to resume a workflow from exactly where it left off, including:
|
|
@@ -125,7 +123,7 @@ console.log(snapshot);
|
|
|
125
123
|
|
|
126
124
|
Snapshots are persisted using a `storage` instance configured on the `Mastra` class. This storage layer is shared across all workflows registered to that instance. Mastra supports multiple storage options for flexibility in different environments.
|
|
127
125
|
|
|
128
|
-
```typescript
|
|
126
|
+
```typescript
|
|
129
127
|
import { Mastra } from "@mastra/core";
|
|
130
128
|
import { LibSQLStore } from "@mastra/libsql";
|
|
131
129
|
import { approvalWorkflow } from "./workflows";
|
|
@@ -159,7 +157,7 @@ export const mastra = new Mastra({
|
|
|
159
157
|
|
|
160
158
|
You can attach custom metadata when suspending a workflow by defining a `suspendSchema`. This metadata is stored in the snapshot and made available when the workflow is resumed.
|
|
161
159
|
|
|
162
|
-
```typescript
|
|
160
|
+
```typescript
|
|
163
161
|
import { createWorkflow, createStep } from "@mastra/core/workflows";
|
|
164
162
|
import { z } from "zod";
|
|
165
163
|
|
|
@@ -208,7 +206,7 @@ const approvalStep = createStep({
|
|
|
208
206
|
|
|
209
207
|
Use `resumeData` to pass structured input when resuming a suspended step. It must match the step’s `resumeSchema`.
|
|
210
208
|
|
|
211
|
-
```typescript
|
|
209
|
+
```typescript
|
|
212
210
|
const workflow = mastra.getWorkflow("approvalWorkflow");
|
|
213
211
|
|
|
214
212
|
const run = await workflow.createRun();
|
|
@@ -1,28 +1,44 @@
|
|
|
1
|
-
> Use Mastra processors and memory with the Vercel AI SDK
|
|
2
|
-
|
|
3
1
|
# AI SDK
|
|
4
2
|
|
|
5
3
|
If you're already using the [Vercel AI SDK](https://sdk.vercel.ai) directly and want to add Mastra capabilities like [processors](https://mastra.ai/docs/agents/processors) or [memory](https://mastra.ai/docs/memory/memory-processors) without switching to the full Mastra agent API, [`withMastra()`](https://mastra.ai/reference/ai-sdk/with-mastra) lets you wrap any AI SDK model with these features. This is useful when you want to keep your existing AI SDK code but add input/output processing, conversation persistence, or content filtering.
|
|
6
4
|
|
|
7
|
-
> **
|
|
8
|
-
|
|
9
|
-
If you want to use Mastra together with AI SDK UI (e.g. `useChat()`), visit the [AI SDK UI guide](https://mastra.ai/guides/build-your-ui/ai-sdk-ui).
|
|
5
|
+
> **Tip:** If you want to use Mastra together with AI SDK UI (e.g. `useChat()`), visit the [AI SDK UI guide](https://mastra.ai/guides/build-your-ui/ai-sdk-ui).
|
|
10
6
|
|
|
11
7
|
## Installation
|
|
12
8
|
|
|
13
9
|
Install `@mastra/ai-sdk` to begin using the `withMastra()` function.
|
|
14
10
|
|
|
15
|
-
|
|
11
|
+
**npm**:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
16
14
|
npm install @mastra/ai-sdk@latest
|
|
17
15
|
```
|
|
18
16
|
|
|
17
|
+
**pnpm**:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
pnpm add @mastra/ai-sdk@latest
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
**Yarn**:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
yarn add @mastra/ai-sdk@latest
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
**Bun**:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
bun add @mastra/ai-sdk@latest
|
|
33
|
+
```
|
|
34
|
+
|
|
19
35
|
## Examples
|
|
20
36
|
|
|
21
37
|
### With Processors
|
|
22
38
|
|
|
23
39
|
Processors let you transform messages before they're sent to the model (`processInput`) and after responses are received (`processOutputResult`). This example creates a logging processor that logs message counts at each stage, then wraps an OpenAI model with it.
|
|
24
40
|
|
|
25
|
-
```typescript
|
|
41
|
+
```typescript
|
|
26
42
|
import { openai } from '@ai-sdk/openai';
|
|
27
43
|
import { generateText } from 'ai';
|
|
28
44
|
import { withMastra } from '@mastra/ai-sdk';
|
|
@@ -55,7 +71,7 @@ const { text } = await generateText({
|
|
|
55
71
|
|
|
56
72
|
Memory automatically loads previous messages from storage before the LLM call and saves new messages after. This example configures a libSQL storage backend to persist conversation history, loading the last 10 messages for context.
|
|
57
73
|
|
|
58
|
-
```typescript
|
|
74
|
+
```typescript
|
|
59
75
|
import { openai } from '@ai-sdk/openai';
|
|
60
76
|
import { generateText } from 'ai';
|
|
61
77
|
import { withMastra } from '@mastra/ai-sdk';
|
|
@@ -86,7 +102,7 @@ const { text } = await generateText({
|
|
|
86
102
|
|
|
87
103
|
You can combine processors and memory together. Input processors run after memory loads historical messages, and output processors run before memory saves the response.
|
|
88
104
|
|
|
89
|
-
```typescript
|
|
105
|
+
```typescript
|
|
90
106
|
import { openai } from '@ai-sdk/openai';
|
|
91
107
|
import { generateText } from 'ai';
|
|
92
108
|
import { withMastra } from '@mastra/ai-sdk';
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Mastra.getMemory()
|
|
2
|
+
|
|
3
|
+
The `.getMemory()` method retrieves a memory instance from the Mastra registry by its key. Memory instances are registered in the Mastra constructor and can be referenced by stored agents.
|
|
4
|
+
|
|
5
|
+
## Usage example
|
|
6
|
+
|
|
7
|
+
```typescript
|
|
8
|
+
const memory = mastra.getMemory("conversationMemory");
|
|
9
|
+
|
|
10
|
+
// Use the memory instance
|
|
11
|
+
const thread = await memory.createThread({
|
|
12
|
+
resourceId: "user-123",
|
|
13
|
+
title: "New Conversation",
|
|
14
|
+
});
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Parameters
|
|
18
|
+
|
|
19
|
+
**key:** (`TMemoryKey extends keyof TMemory`): The registry key of the memory instance to retrieve. Must match a key used when registering memory in the Mastra constructor.
|
|
20
|
+
|
|
21
|
+
## Returns
|
|
22
|
+
|
|
23
|
+
**memory:** (`TMemory[TMemoryKey]`): The memory instance with the specified key. Throws an error if the memory is not found.
|
|
24
|
+
|
|
25
|
+
## Example: Registering and Retrieving Memory
|
|
26
|
+
|
|
27
|
+
```typescript
|
|
28
|
+
import { Mastra } from "@mastra/core";
|
|
29
|
+
import { Memory } from "@mastra/memory";
|
|
30
|
+
import { LibSQLStore } from "@mastra/libsql";
|
|
31
|
+
|
|
32
|
+
const conversationMemory = new Memory({
|
|
33
|
+
storage: new LibSQLStore({ id: 'conversation-store', url: ":memory:" }),
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
const mastra = new Mastra({
|
|
37
|
+
memory: {
|
|
38
|
+
conversationMemory,
|
|
39
|
+
},
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
// Later, retrieve the memory instance
|
|
43
|
+
const memory = mastra.getMemory("conversationMemory");
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Related
|
|
47
|
+
|
|
48
|
+
- [Mastra.listMemory()](https://mastra.ai/reference/core/listMemory)
|
|
49
|
+
- [Memory overview](https://mastra.ai/docs/memory/overview)
|
|
50
|
+
- [Agent Memory](https://mastra.ai/docs/agents/agent-memory)
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Mastra.listMemory()
|
|
2
|
+
|
|
3
|
+
The `.listMemory()` method returns all memory instances registered with the Mastra instance.
|
|
4
|
+
|
|
5
|
+
## Usage example
|
|
6
|
+
|
|
7
|
+
```typescript
|
|
8
|
+
const memoryInstances = mastra.listMemory();
|
|
9
|
+
|
|
10
|
+
for (const [key, memory] of Object.entries(memoryInstances)) {
|
|
11
|
+
console.log(`Memory "${key}": ${memory.id}`);
|
|
12
|
+
}
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Parameters
|
|
16
|
+
|
|
17
|
+
This method takes no parameters.
|
|
18
|
+
|
|
19
|
+
## Returns
|
|
20
|
+
|
|
21
|
+
**memory:** (`Record<string, MastraMemory>`): An object containing all registered memory instances, keyed by their registry keys.
|
|
22
|
+
|
|
23
|
+
## Example: Checking Registered Memory
|
|
24
|
+
|
|
25
|
+
```typescript
|
|
26
|
+
import { Mastra } from "@mastra/core";
|
|
27
|
+
import { Memory } from "@mastra/memory";
|
|
28
|
+
import { LibSQLStore } from "@mastra/libsql";
|
|
29
|
+
|
|
30
|
+
const conversationMemory = new Memory({
|
|
31
|
+
id: "conversation-memory",
|
|
32
|
+
storage: new LibSQLStore({ id: 'conversation-store', url: ":memory:" }),
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
const analyticsMemory = new Memory({
|
|
36
|
+
id: "analytics-memory",
|
|
37
|
+
storage: new LibSQLStore({ id: 'analytics-store', url: ":memory:" }),
|
|
38
|
+
});
|
|
39
|
+
|
|
40
|
+
const mastra = new Mastra({
|
|
41
|
+
memory: {
|
|
42
|
+
conversationMemory,
|
|
43
|
+
analyticsMemory,
|
|
44
|
+
},
|
|
45
|
+
});
|
|
46
|
+
|
|
47
|
+
// List all registered memory instances
|
|
48
|
+
const allMemory = mastra.listMemory();
|
|
49
|
+
console.log(Object.keys(allMemory)); // ["conversationMemory", "analyticsMemory"]
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Related
|
|
53
|
+
|
|
54
|
+
- [Mastra.getMemory()](https://mastra.ai/reference/core/getMemory)
|
|
55
|
+
- [Memory overview](https://mastra.ai/docs/memory/overview)
|
|
56
|
+
- [Agent Memory](https://mastra.ai/docs/agents/agent-memory)
|