@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.
Files changed (46) hide show
  1. package/CHANGELOG.md +176 -0
  2. package/dist/docs/SKILL.md +36 -26
  3. package/dist/docs/{SOURCE_MAP.json → assets/SOURCE_MAP.json} +1 -1
  4. package/dist/docs/{agents/03-agent-approval.md → references/docs-agents-agent-approval.md} +19 -19
  5. package/dist/docs/references/docs-agents-agent-memory.md +212 -0
  6. package/dist/docs/{agents/04-network-approval.md → references/docs-agents-network-approval.md} +13 -12
  7. package/dist/docs/{agents/02-networks.md → references/docs-agents-networks.md} +10 -12
  8. package/dist/docs/{memory/06-memory-processors.md → references/docs-memory-memory-processors.md} +6 -8
  9. package/dist/docs/{memory/03-message-history.md → references/docs-memory-message-history.md} +31 -20
  10. package/dist/docs/{memory/01-overview.md → references/docs-memory-overview.md} +8 -8
  11. package/dist/docs/{memory/05-semantic-recall.md → references/docs-memory-semantic-recall.md} +33 -17
  12. package/dist/docs/{memory/02-storage.md → references/docs-memory-storage.md} +29 -39
  13. package/dist/docs/{memory/04-working-memory.md → references/docs-memory-working-memory.md} +16 -27
  14. package/dist/docs/{observability/01-overview.md → references/docs-observability-overview.md} +4 -7
  15. package/dist/docs/{observability/02-default.md → references/docs-observability-tracing-exporters-default.md} +11 -14
  16. package/dist/docs/{rag/01-retrieval.md → references/docs-rag-retrieval.md} +26 -53
  17. package/dist/docs/{workflows/01-snapshots.md → references/docs-workflows-snapshots.md} +3 -5
  18. package/dist/docs/{guides/01-ai-sdk.md → references/guides-agent-frameworks-ai-sdk.md} +25 -9
  19. package/dist/docs/references/reference-core-getMemory.md +50 -0
  20. package/dist/docs/references/reference-core-listMemory.md +56 -0
  21. package/dist/docs/references/reference-core-mastra-class.md +66 -0
  22. package/dist/docs/{memory/07-reference.md → references/reference-memory-memory-class.md} +28 -14
  23. package/dist/docs/references/reference-storage-composite.md +235 -0
  24. package/dist/docs/references/reference-storage-dynamodb.md +282 -0
  25. package/dist/docs/references/reference-storage-libsql.md +135 -0
  26. package/dist/docs/{vectors/01-reference.md → references/reference-vectors-libsql.md} +105 -13
  27. package/dist/index.cjs +1676 -194
  28. package/dist/index.cjs.map +1 -1
  29. package/dist/index.js +1676 -196
  30. package/dist/index.js.map +1 -1
  31. package/dist/storage/db/index.d.ts.map +1 -1
  32. package/dist/storage/domains/agents/index.d.ts +9 -12
  33. package/dist/storage/domains/agents/index.d.ts.map +1 -1
  34. package/dist/storage/domains/memory/index.d.ts +7 -1
  35. package/dist/storage/domains/memory/index.d.ts.map +1 -1
  36. package/dist/storage/domains/prompt-blocks/index.d.ts +25 -0
  37. package/dist/storage/domains/prompt-blocks/index.d.ts.map +1 -0
  38. package/dist/storage/domains/scorer-definitions/index.d.ts +26 -0
  39. package/dist/storage/domains/scorer-definitions/index.d.ts.map +1 -0
  40. package/dist/storage/index.d.ts +3 -1
  41. package/dist/storage/index.d.ts.map +1 -1
  42. package/package.json +5 -6
  43. package/dist/docs/README.md +0 -39
  44. package/dist/docs/agents/01-agent-memory.md +0 -166
  45. package/dist/docs/core/01-reference.md +0 -151
  46. 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](./semantic-recall) help agents remember conversations, working memory allows them to maintain persistent information about users across interactions.
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 {11-15}
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
- <YouTube id="UMy_JHLf1n8" />
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 {5-28}
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
- `## Personal Info` or `- Name:`) so updates are easy to read and less likely to be truncated.
180
- - **Use consistent casing.** Inconsistent capitalization (`Timezone:` vs `timezone:`) can cause messy
181
- updates. Stick to Title Case or lower case for headings and bullet labels.
182
- - **Keep placeholder text simple.** Use hints such as `[e.g., Formal]` or `[Date]` to help the LLM
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 title="src/app/medical-consultation.ts"
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 title="src/app/medical-consultation.ts"
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 title="src/app/medical-consultation.ts"
367
+ ```typescript
379
368
  await memory.updateWorkingMemory({
380
369
  threadId: "thread-123",
381
370
  resourceId: "user-456", // Required for resource-scoped memory
@@ -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#storage-provider-support).
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#production-recommendations) for details.
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 title="src/mastra/index.ts"
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 title="src/mastra/index.ts"
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 | Preferred Strategy | Supported Strategies | Recommended Use |
123
- | ----------------------------------------------- | ------------------ | ----------------------------------------- | ------------------------------------- |
124
- | **ClickHouse** (`@mastra/clickhouse`) | insert-only | insert-only | Production (high-volume) |
125
- | **[PostgreSQL](https://mastra.ai/reference/storage/postgresql)** | batch-with-updates | batch-with-updates, insert-only | Production (low volume) |
126
- | **[MSSQL](https://mastra.ai/reference/storage/mssql)** | batch-with-updates | batch-with-updates, insert-only | Production (low volume) |
127
- | **[MongoDB](https://mastra.ai/reference/storage/mongodb)** | batch-with-updates | batch-with-updates, insert-only | Production (low volume) |
128
- | **[libSQL](https://mastra.ai/reference/storage/libsql)** | batch-with-updates | batch-with-updates, insert-only | Default storage, good for development |
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#specialized-storage-for-observability) is a columnar database designed for high-volume analytics workloads. It's the recommended choice for production observability because:
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#specialized-storage-for-observability) to route observability data to ClickHouse while keeping other data in your primary database.
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
- These configurations are for **query-time options** like namespaces, performance tuning, and filtering—not for database connection setup.
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
- **pgvector:**
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 title="vector-store.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 title="vector-store.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
- **chroma:**
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 title="vector-store.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 title="vector-store.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
- **upstash:**
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 title="vector-store.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 title="vector-store.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
- **opensearch:**
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 title="vector-store.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 title="src/mastra/index.ts"
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 {30-34} title="src/mastra/workflows/test-workflow.ts"
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 {14-20}
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
- > **Note:**
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
- ```bash npm2yarn
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 title="src/example.ts"
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 title="src/memory-example.ts"
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 title="src/combined-example.ts"
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)