@mastra/mcp-docs-server 1.0.0-beta.14 → 1.0.0-beta.16

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 (63) hide show
  1. package/.docs/organized/changelogs/%40mastra%2Fagent-builder.md +41 -41
  2. package/.docs/organized/changelogs/%40mastra%2Fai-sdk.md +51 -51
  3. package/.docs/organized/changelogs/%40mastra%2Fclickhouse.md +235 -235
  4. package/.docs/organized/changelogs/%40mastra%2Fclient-js.md +85 -85
  5. package/.docs/organized/changelogs/%40mastra%2Fcloudflare-d1.md +235 -235
  6. package/.docs/organized/changelogs/%40mastra%2Fcloudflare.md +235 -235
  7. package/.docs/organized/changelogs/%40mastra%2Fconvex.md +258 -0
  8. package/.docs/organized/changelogs/%40mastra%2Fcore.md +338 -338
  9. package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloud.md +27 -27
  10. package/.docs/organized/changelogs/%40mastra%2Fdeployer.md +67 -67
  11. package/.docs/organized/changelogs/%40mastra%2Fdynamodb.md +235 -235
  12. package/.docs/organized/changelogs/%40mastra%2Fevals.md +10 -10
  13. package/.docs/organized/changelogs/%40mastra%2Ffastembed.md +6 -0
  14. package/.docs/organized/changelogs/%40mastra%2Flance.md +235 -235
  15. package/.docs/organized/changelogs/%40mastra%2Flibsql.md +235 -235
  16. package/.docs/organized/changelogs/%40mastra%2Fmcp-docs-server.md +16 -16
  17. package/.docs/organized/changelogs/%40mastra%2Fmcp.md +30 -30
  18. package/.docs/organized/changelogs/%40mastra%2Fmemory.md +168 -168
  19. package/.docs/organized/changelogs/%40mastra%2Fmongodb.md +259 -259
  20. package/.docs/organized/changelogs/%40mastra%2Fmssql.md +259 -259
  21. package/.docs/organized/changelogs/%40mastra%2Fpg.md +279 -279
  22. package/.docs/organized/changelogs/%40mastra%2Fplayground-ui.md +108 -108
  23. package/.docs/organized/changelogs/%40mastra%2Freact.md +77 -77
  24. package/.docs/organized/changelogs/%40mastra%2Fserver.md +180 -180
  25. package/.docs/organized/changelogs/%40mastra%2Fupstash.md +235 -235
  26. package/.docs/organized/changelogs/create-mastra.md +11 -11
  27. package/.docs/organized/changelogs/mastra.md +40 -40
  28. package/.docs/organized/code-examples/agent-v6.md +70 -11
  29. package/.docs/organized/code-examples/client-side-tools.md +1 -1
  30. package/.docs/raw/agents/adding-voice.mdx +8 -3
  31. package/.docs/raw/deployment/overview.mdx +3 -4
  32. package/.docs/raw/deployment/workflow-runners.mdx +14 -0
  33. package/.docs/raw/getting-started/studio.mdx +1 -1
  34. package/.docs/raw/guides/deployment/inngest.mdx +198 -140
  35. package/.docs/raw/guides/migrations/upgrade-to-v1/memory.mdx +11 -3
  36. package/.docs/raw/guides/migrations/upgrade-to-v1/processors.mdx +11 -0
  37. package/.docs/raw/guides/migrations/upgrade-to-v1/storage.mdx +68 -0
  38. package/.docs/raw/mastra-cloud/deployment.mdx +39 -0
  39. package/.docs/raw/mastra-cloud/observability.mdx +9 -15
  40. package/.docs/raw/mastra-cloud/overview.mdx +14 -44
  41. package/.docs/raw/mastra-cloud/setup.mdx +64 -0
  42. package/.docs/raw/mastra-cloud/studio.mdx +35 -0
  43. package/.docs/raw/reference/client-js/workflows.mdx +15 -0
  44. package/.docs/raw/reference/logging/pino-logger.mdx +1 -1
  45. package/.docs/raw/reference/processors/token-limiter-processor.mdx +39 -18
  46. package/.docs/raw/reference/storage/cloudflare-d1.mdx +4 -2
  47. package/.docs/raw/reference/storage/composite.mdx +223 -0
  48. package/.docs/raw/reference/storage/lance.mdx +3 -2
  49. package/.docs/raw/reference/storage/libsql.mdx +5 -2
  50. package/.docs/raw/reference/storage/mongodb.mdx +4 -2
  51. package/.docs/raw/reference/storage/mssql.mdx +4 -2
  52. package/.docs/raw/reference/storage/postgresql.mdx +4 -2
  53. package/.docs/raw/reference/tools/mcp-server.mdx +9 -0
  54. package/.docs/raw/reference/workflows/run-methods/cancel.mdx +51 -3
  55. package/.docs/raw/reference/workflows/run.mdx +8 -2
  56. package/.docs/raw/voice/overview.mdx +1 -1
  57. package/.docs/raw/workflows/overview.mdx +1 -1
  58. package/.docs/raw/workflows/snapshots.mdx +2 -1
  59. package/CHANGELOG.md +15 -0
  60. package/package.json +5 -5
  61. package/.docs/raw/mastra-cloud/dashboard.mdx +0 -96
  62. package/.docs/raw/mastra-cloud/setting-up.mdx +0 -106
  63. package/.docs/raw/workflows/inngest-workflow.mdx +0 -362
@@ -1,46 +1,40 @@
1
1
  ---
2
- title: "Understanding Tracing and Logs | Mastra Cloud"
2
+ title: "Observability | Mastra Cloud"
3
3
  description: Monitoring and debugging tools for Mastra Cloud deployments
4
4
  ---
5
5
 
6
- # Understanding Tracing and Logs
6
+ # Observability
7
7
 
8
- Mastra Cloud provides full observability for production applications, giving you insight into how your agents and workflows behave. Observability can be enabled whether your application is deployed to Mastra Cloud, running locally, or hosted on your own infrastructure. Any Mastra project can send traces and logs to the platform regardless of where it's running.
8
+ Cloud provides observability for production applications, giving you insight into how your agents and workflows behave. Observability works whether your application is deployed to Mastra Cloud, running locally, or hosted on your own infrastructure. Any Mastra project can send traces and logs to the platform regardless of where it's running.
9
9
 
10
10
  For details on configuring observability, see the [Cloud Exporter](/docs/v1/observability/tracing/exporters/cloud) docs.
11
11
 
12
12
  ## Traces
13
13
 
14
- More detailed traces are available for both agents and workflows by enabling [observability](/docs/v1/observability/tracing/overview) using one of our [supported providers](/docs/v1/observability/tracing/overview#exporters).
14
+ Traces are available for both agents and workflows by enabling [observability](/docs/v1/observability/tracing/overview) using one of the [supported providers](/docs/v1/observability/tracing/overview#exporters).
15
15
 
16
16
  ### Agents
17
17
 
18
- With observability enabled, you can view detailed outputs from your agents in the **Traces** section in Studio.
18
+ With observability enabled, you can view detailed outputs from your agents in the **Traces** section in [Studio](/docs/v1/mastra-cloud/studio).
19
19
 
20
20
  ![observability agents](/img/mastra-cloud/mastra-cloud-observability-agents.jpg)
21
21
 
22
- Key features:
23
-
24
- Agent traces break a run into clear steps, model calls, tool calls, and intermediate chunks, each with timing, inputs, outputs, and errors. You can drill into any span to inspect prompts, token usage, and results, making it easy to diagnose issues and understand how the agent produced its output.
22
+ Agent traces break a run into clear steps: model calls, tool calls, and intermediate chunks. Each includes timing, inputs, outputs, and errors. Drill into any span to inspect prompts, token usage, and results.
25
23
 
26
24
  ### Workflows
27
25
 
28
- With observability enabled, you can view detailed outputs from your workflows in the **Traces** section in Studio.
26
+ With observability enabled, you can view detailed outputs from your workflows in the **Traces** section in [Studio](/docs/v1/mastra-cloud/studio).
29
27
 
30
28
  ![observability workflows](/img/mastra-cloud/mastra-cloud-observability-workflows.jpg)
31
29
 
32
- Key features:
33
-
34
- Workflow traces capture each step in the run, including transitions, branching, timing, and any tool calls inside the workflow. You can inspect inputs, outputs, and errors for every step, making it easy to debug long-running or multi-step processes and understand how data flows through the workflow.
30
+ Workflow traces capture each step in the run, including transitions, branching, timing, and any tool calls. Inspect inputs, outputs, and errors for every step to debug long-running or multi-step processes.
35
31
 
36
32
  ## Logs
37
33
 
38
- You can view detailed logs for debugging and monitoring your application's behavior on the [Logs](/docs/v1/mastra-cloud/dashboard#logs) page of the Dashboard.
34
+ The **Logs** page in the [project dashboard](/docs/v1/mastra-cloud/deployment#project-dashboard) displays detailed information for debugging and monitoring your application's behavior.
39
35
 
40
36
  ![Dashboard logs](/img/mastra-cloud/mastra-cloud-dashboard-logs.jpg)
41
37
 
42
- Key features:
43
-
44
38
  Each log entry includes its severity level and a detailed message showing agent, workflow, or storage activity.
45
39
 
46
40
  ## Next steps
@@ -5,57 +5,27 @@ description: Deployment and monitoring service for Mastra applications
5
5
 
6
6
  # Mastra Cloud
7
7
 
8
- [Mastra Cloud](https://mastra.ai/cloud) is a platform for deploying, managing, monitoring, and debugging Mastra applications. When you [deploy](/docs/v1/mastra-cloud/setting-up) your application, Mastra Cloud exposes your agents, tools, and workflows as REST API endpoints.
8
+ [Mastra Cloud](https://cloud.mastra.ai) is a platform for deploying, managing, and monitoring Mastra applications. [Import your project](/docs/v1/mastra-cloud/setup) to get started.
9
9
 
10
- ## Platform features
10
+ ## Studio
11
11
 
12
- Deploy and manage your applications with automated builds, organized projects, and no additional configuration.
12
+ Run [Studio](/docs/v1/mastra-cloud/studio) in the cloud and share access with your team via a link. Team members can test agents and workflows, tweak system prompts, and give feedback without running the project locally.
13
13
 
14
- ![Platform features](/img/mastra-cloud/mastra-cloud-platform-features.jpg)
14
+ ## Deploy
15
15
 
16
- Key features:
16
+ Enable [deployments](/docs/v1/mastra-cloud/deployment) and Mastra Cloud hosts your server for you. Connect your GitHub repository for automatic deployments whenever you push to your configured branch. Mastra Cloud exposes your agents, tools, and workflows as REST API endpoints.
17
17
 
18
- Mastra Cloud supports zero-config deployment, continuous integration with GitHub, and atomic deployments that package agents, tools, and workflows together.
18
+ Once deployed, the project dashboard gives you visibility into:
19
19
 
20
- ## Project Dashboard
20
+ - Deployment status and history
21
+ - Build logs and configuration
22
+ - Environment variables and settings
21
23
 
22
- Monitor and debug your applications with detailed output logs, deployment state, and interactive tools.
24
+ ## Observability
23
25
 
24
- ![Project dashboard](/img/mastra-cloud/mastra-cloud-project-dashboard.jpg)
26
+ [Observability](/docs/v1/mastra-cloud/observability) provides insight into how your agents and workflows behave in production. View detailed traces of agent runs, workflow executions, and logs to debug issues and understand performance.
25
27
 
26
- Key features:
28
+ :::info
29
+ You don’t need to deploy to Mastra Cloud to use Observability. You can send traces to Mastra from any environment
30
+ :::
27
31
 
28
- The Project Dashboard gives you an overview of your application's status and deployments, with access to logs and a Studio for testing agents and workflows.
29
-
30
- ## Project structure
31
-
32
- Use a standard Mastra project structure for proper detection and deployment.
33
-
34
- ```shell
35
- src
36
- └── mastra
37
- ├── agents
38
- │ └── agent-name.ts
39
- ├── tools
40
- │ └── tool-name.ts
41
- ├── workflows
42
- │ └── workflow-name.ts
43
- └── index.ts
44
- package.json
45
- ```
46
-
47
- Mastra Cloud scans your repository for:
48
-
49
- - **Agents**: Defined using: `new Agent({...})`
50
- - **Tools**: Defined using: `createTool({...})`
51
- - **Workflows**: Defined using: `createWorkflow({...})`
52
- - **Steps**: Defined using: `createStep({...})`
53
- - **Environment Variables**: API keys and configuration variables
54
-
55
- ## Technical implementation
56
-
57
- Mastra Cloud is purpose-built for Mastra agents, tools, and workflows. It handles long-running requests, records detailed traces for every execution, and includes built-in support for evals.
58
-
59
- ## Next steps
60
-
61
- - [Setting Up and Deploying](/docs/v1/mastra-cloud/setting-up)
@@ -0,0 +1,64 @@
1
+ ---
2
+ title: "Setup | Mastra Cloud"
3
+ description: Import your Mastra project to Mastra Cloud
4
+ ---
5
+
6
+ import Steps from "@site/src/components/Steps";
7
+ import StepItem from "@site/src/components/StepItem";
8
+
9
+ # Setup
10
+
11
+ Import your Mastra project to [Mastra Cloud](https://cloud.mastra.ai) to use [Studio](/docs/v1/mastra-cloud/studio) and optionally [deploy](/docs/v1/mastra-cloud/deployment) your agent.
12
+
13
+ ## Before you begin
14
+
15
+ - [Sign in](https://cloud.mastra.ai) to Cloud
16
+ - Push your [Mastra project](/docs/v1/getting-started/start) to GitHub
17
+
18
+ ## Options
19
+
20
+
21
+ ![Select project type](/img/mastra-cloud/mastra-cloud-select.png)
22
+
23
+ When you create a new project, you can choose from three options:
24
+
25
+ 1. **Create from GitHub** - Import a Mastra project from GitHub
26
+ 2. **Create from your server** - Connect a self-hosted Mastra instance to [Studio](/docs/v1/mastra-cloud/studio)
27
+ 3. **Create from template** - Start from a [pre-built template](https://mastra.ai/templates)
28
+
29
+
30
+ To create a project from GitHub, follow these steps:
31
+
32
+ ## Create from GitHub
33
+
34
+ <Steps>
35
+
36
+ <StepItem>
37
+ Connect to GitHub when prompted
38
+
39
+ ![Deployment details](/img/mastra-cloud/mastra-cloud-connect.png)
40
+ </StepItem>
41
+
42
+ <StepItem>
43
+ Search for your repository and click **Import**
44
+
45
+ ![Deployment details](/img/mastra-cloud/mastra-cloud-import-git-repository.jpg)
46
+ </StepItem>
47
+
48
+ <StepItem>
49
+ Configure your project settings. Mastra Cloud auto-detects most settings, but you'll still need to enter the environment variables for your configured [model provider](/models/v1):
50
+
51
+ ![Deployment details](/img/mastra-cloud/mastra-cloud-deployment-details.jpg)
52
+ </StepItem>
53
+
54
+ <StepItem>
55
+
56
+ Click **Create Project**
57
+ </StepItem>
58
+ </Steps>
59
+
60
+ ## Next steps
61
+
62
+ Once your project is imported, [Studio](/docs/v1/mastra-cloud/studio) automatically creates a sandbox where you can interact with your agents and share access with your team.
63
+
64
+ When you're ready for production, enable [Deployment](/docs/v1/mastra-cloud/deployment) settings and hit deploy!
@@ -0,0 +1,35 @@
1
+ ---
2
+ title: "Studio | Mastra Cloud"
3
+ description: Run Studio in the cloud for team collaboration
4
+ ---
5
+
6
+ import YouTube from "@site/src/components/YouTube-player";
7
+
8
+ # Studio
9
+
10
+ <YouTube id="ojGu6Bi4wYk" />
11
+
12
+ Mastra Cloud provides a hosted version of [Studio](/docs/v1/getting-started/studio) that gives your team a shared environment for interacting with and testing your agents. Team members can chat with agents, review traces, give feedback, and tweak system prompts - without needing to run the project locally.
13
+
14
+ [Set up your project](/docs/v1/mastra-cloud/setup) to access Studio in the cloud.
15
+
16
+ See the [Studio documentation](/docs/v1/getting-started/studio) for details on features like the Agents playground, Workflows runner, Tools testing, and MCP Servers.
17
+
18
+ :::note
19
+ You don't need to deploy your agent to use Studio. Studio runs in a sandbox environment separate from your production deployment
20
+ :::
21
+
22
+ ## Sharing access
23
+
24
+ To invite team members, go to [Mastra Cloud](https://cloud.mastra.ai), click **Team Settings**, then **Members** to add them. Once invited, they can sign in and access your project's Studio.
25
+
26
+ ![Invite team members](/img/mastra-cloud/mastra-cloud-invite.png)
27
+
28
+ :::warning
29
+ Team members can view environment variables and delete projects. Only invite people you trust.
30
+ :::
31
+
32
+ ## Next steps
33
+
34
+ - [Deployment](/docs/v1/mastra-cloud/deployment) - Manage deployments and settings
35
+ - [Observability](/docs/v1/mastra-cloud/observability) - Monitor traces and logs
@@ -145,6 +145,21 @@ await run.resume({
145
145
  });
146
146
  ```
147
147
 
148
+ ### cancel()
149
+
150
+ Cancel a running workflow:
151
+
152
+ ```typescript
153
+ const run = await workflow.createRun({ runId: existingRunId });
154
+
155
+ const result = await run.cancel();
156
+ // Returns: { message: 'Workflow run canceled' }
157
+ ```
158
+
159
+ This method stops any running steps and prevents subsequent steps from executing. Steps that check the `abortSignal` parameter can respond to cancellation by cleaning up resources (timeouts, network requests, etc.).
160
+
161
+ See the [Run.cancel()](/reference/v1/workflows/run-methods/cancel) reference for detailed information about how cancellation works and how to write steps that respond to cancellation.
162
+
148
163
  ### stream()
149
164
 
150
165
  Stream workflow execution for real-time updates:
@@ -7,7 +7,7 @@ description: Documentation for PinoLogger, which provides methods to record even
7
7
 
8
8
  A Logger instance is created using `new PinoLogger()` and provides methods to record events at various severity levels.
9
9
 
10
- When deploying to Mastra Cloud, logs are displayed on the [Logs](/docs/v1/mastra-cloud/dashboard#logs) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
10
+ When deploying to Mastra Cloud, logs are displayed on the [Logs](/docs/v1/mastra-cloud/observability#logs) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
11
11
 
12
12
  ## Usage example
13
13
 
@@ -1,11 +1,14 @@
1
1
  ---
2
2
  title: "Reference: Token Limiter Processor | Processors"
3
- description: "Documentation for the TokenLimiterProcessor in Mastra, which limits the number of tokens in AI responses."
3
+ description: "Documentation for the TokenLimiterProcessor in Mastra, which limits the number of tokens in messages."
4
4
  ---
5
5
 
6
6
  # TokenLimiterProcessor
7
7
 
8
- The `TokenLimiterProcessor` is an **output processor** that limits the number of tokens in AI responses. This processor helps control response length by implementing token counting with configurable strategies for handling exceeded limits, including truncation and abortion options for both streaming and non-streaming scenarios.
8
+ The `TokenLimiterProcessor` limits the number of tokens in messages. It can be used as both an input and output processor:
9
+
10
+ - **Input processor**: Filters historical messages to fit within the context window, prioritizing recent messages
11
+ - **Output processor**: Limits generated response tokens via streaming or non-streaming with configurable strategies for handling exceeded limits
9
12
 
10
13
  ## Usage example
11
14
 
@@ -82,6 +85,12 @@ const processor = new TokenLimiterProcessor({
82
85
  description: "Optional processor display name",
83
86
  isOptional: true,
84
87
  },
88
+ {
89
+ name: "processInput",
90
+ type: "(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>",
91
+ description: "Filters input messages to fit within token limit, prioritizing recent messages while preserving system messages",
92
+ isOptional: false,
93
+ },
85
94
  {
86
95
  name: "processOutputStream",
87
96
  type: "(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never }) => Promise<ChunkType | null>",
@@ -90,22 +99,10 @@ const processor = new TokenLimiterProcessor({
90
99
  },
91
100
  {
92
101
  name: "processOutputResult",
93
- type: "(args: { messages: MastraMessageV2[]; abort: (reason?: string) => never }) => Promise<MastraMessageV2[]>",
102
+ type: "(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>",
94
103
  description: "Processes final output results to limit token count in non-streaming scenarios",
95
104
  isOptional: false,
96
105
  },
97
- {
98
- name: "reset",
99
- type: "() => void",
100
- description: "Reset the token counter (useful for testing or reusing the processor)",
101
- isOptional: false,
102
- },
103
- {
104
- name: "getCurrentTokens",
105
- type: "() => number",
106
- description: "Get the current token count",
107
- isOptional: false,
108
- },
109
106
  {
110
107
  name: "getMaxTokens",
111
108
  type: "() => number",
@@ -117,14 +114,38 @@ const processor = new TokenLimiterProcessor({
117
114
 
118
115
  ## Extended usage example
119
116
 
120
- ```typescript title="src/mastra/agents/limited-agent.ts"
117
+ ### As an input processor (limit context window)
118
+
119
+ Use `inputProcessors` to limit historical messages sent to the model, which helps stay within context window limits:
120
+
121
+ ```typescript title="src/mastra/agents/context-limited-agent.ts"
122
+ import { Agent } from "@mastra/core/agent";
123
+ import { Memory } from "@mastra/memory";
124
+ import { TokenLimiterProcessor } from "@mastra/core/processors";
125
+
126
+ export const agent = new Agent({
127
+ name: "context-limited-agent",
128
+ instructions: "You are a helpful assistant",
129
+ model: "openai/gpt-4o",
130
+ memory: new Memory({ /* ... */ }),
131
+ inputProcessors: [
132
+ new TokenLimiterProcessor({ limit: 4000 }) // Limits historical messages to ~4000 tokens
133
+ ]
134
+ });
135
+ ```
136
+
137
+ ### As an output processor (limit response length)
138
+
139
+ Use `outputProcessors` to limit the length of generated responses:
140
+
141
+ ```typescript title="src/mastra/agents/response-limited-agent.ts"
121
142
  import { Agent } from "@mastra/core/agent";
122
143
  import { TokenLimiterProcessor } from "@mastra/core/processors";
123
144
 
124
145
  export const agent = new Agent({
125
- name: "limited-agent",
146
+ name: "response-limited-agent",
126
147
  instructions: "You are a helpful assistant",
127
- model: "openai/gpt-5.1",
148
+ model: "openai/gpt-4o",
128
149
  outputProcessors: [
129
150
  new TokenLimiterProcessor({
130
151
  limit: 1000,
@@ -118,14 +118,16 @@ If you're using storage directly without Mastra, you must call `init()` explicit
118
118
  import { D1Store } from "@mastra/cloudflare-d1";
119
119
 
120
120
  const storage = new D1Store({
121
+ id: 'd1-storage',
121
122
  binding: D1Database,
122
123
  });
123
124
 
124
125
  // Required when using storage directly
125
126
  await storage.init();
126
127
 
127
- // Now you can use the storage
128
- await storage.getThread({ threadId: "..." });
128
+ // Access domain-specific stores via getStore()
129
+ const memoryStore = await storage.getStore('memory');
130
+ const thread = await memoryStore?.getThreadById({ threadId: "..." });
129
131
  ```
130
132
 
131
133
  :::warning
@@ -0,0 +1,223 @@
1
+ ---
2
+ title: "Reference: Storage Composition | Storage"
3
+ description: Documentation for combining multiple storage backends in Mastra.
4
+ ---
5
+
6
+ # Storage Composition
7
+
8
+ MastraStorage can compose storage domains from different adapters. Use it when you need different databases for different purposes. For example, use LibSQL for memory and PostgreSQL for workflows.
9
+
10
+ ## Installation
11
+
12
+ MastraStorage is included in `@mastra/core`:
13
+
14
+ ```bash
15
+ npm install @mastra/core@beta
16
+ ```
17
+
18
+ You'll also need to install the storage adapters you want to compose:
19
+
20
+ ```bash
21
+ npm install @mastra/pg@beta @mastra/libsql@beta
22
+ ```
23
+
24
+ ## Usage
25
+
26
+ ### Basic composition
27
+
28
+ Import domain classes directly from each store package and compose them:
29
+
30
+ ```typescript
31
+ import { MastraStorage } from "@mastra/core/storage";
32
+ import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
33
+ import { MemoryLibSQL } from "@mastra/libsql";
34
+ import { Mastra } from "@mastra/core";
35
+
36
+ const mastra = new Mastra({
37
+ storage: new MastraStorage({
38
+ id: "composite",
39
+ domains: {
40
+ memory: new MemoryLibSQL({ url: "file:./local.db" }),
41
+ workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
42
+ scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
43
+ },
44
+ }),
45
+ });
46
+ ```
47
+
48
+ ### With a default storage
49
+
50
+ Use `default` to specify a fallback storage, then override specific domains:
51
+
52
+ ```typescript
53
+ import { MastraStorage } from "@mastra/core/storage";
54
+ import { PostgresStore } from "@mastra/pg";
55
+ import { MemoryLibSQL } from "@mastra/libsql";
56
+ import { Mastra } from "@mastra/core";
57
+
58
+ const pgStore = new PostgresStore({
59
+ id: "pg",
60
+ connectionString: process.env.DATABASE_URL,
61
+ });
62
+
63
+ const mastra = new Mastra({
64
+ storage: new MastraStorage({
65
+ id: "composite",
66
+ default: pgStore,
67
+ domains: {
68
+ memory: new MemoryLibSQL({ url: "file:./local.db" }),
69
+ },
70
+ }),
71
+ });
72
+ ```
73
+
74
+ ## Options
75
+
76
+ <PropertiesTable
77
+ content={[
78
+ {
79
+ name: "id",
80
+ type: "string",
81
+ description: "Unique identifier for this storage instance.",
82
+ isOptional: false,
83
+ },
84
+ {
85
+ name: "default",
86
+ type: "MastraStorage",
87
+ description:
88
+ "Default storage adapter. Domains not explicitly specified in `domains` will use this storage's domains as fallbacks.",
89
+ isOptional: true,
90
+ },
91
+ {
92
+ name: "domains",
93
+ type: "object",
94
+ description:
95
+ "Individual domain overrides. Each domain can come from a different storage adapter. These take precedence over the default storage.",
96
+ isOptional: true,
97
+ },
98
+ {
99
+ name: "domains.memory",
100
+ type: "MemoryStorage",
101
+ description: "Storage for threads, messages, and resources.",
102
+ isOptional: true,
103
+ },
104
+ {
105
+ name: "domains.workflows",
106
+ type: "WorkflowsStorage",
107
+ description: "Storage for workflow snapshots.",
108
+ isOptional: true,
109
+ },
110
+ {
111
+ name: "domains.scores",
112
+ type: "ScoresStorage",
113
+ description: "Storage for evaluation scores.",
114
+ isOptional: true,
115
+ },
116
+ {
117
+ name: "domains.observability",
118
+ type: "ObservabilityStorage",
119
+ description: "Storage for traces and spans.",
120
+ isOptional: true,
121
+ },
122
+ {
123
+ name: "domains.agents",
124
+ type: "AgentsStorage",
125
+ description: "Storage for stored agent configurations.",
126
+ isOptional: true,
127
+ },
128
+ {
129
+ name: "disableInit",
130
+ type: "boolean",
131
+ description:
132
+ "When true, automatic initialization is disabled. You must call init() explicitly.",
133
+ isOptional: true,
134
+ },
135
+ ]}
136
+ />
137
+
138
+ ## Initialization
139
+
140
+ MastraStorage initializes each configured domain independently. When passed to the Mastra class, `init()` is called automatically:
141
+
142
+ ```typescript
143
+ import { MastraStorage } from "@mastra/core/storage";
144
+ import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
145
+ import { Mastra } from "@mastra/core";
146
+
147
+ const storage = new MastraStorage({
148
+ id: "composite",
149
+ domains: {
150
+ memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
151
+ workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
152
+ scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
153
+ },
154
+ });
155
+
156
+ const mastra = new Mastra({
157
+ storage, // init() called automatically
158
+ });
159
+ ```
160
+
161
+ If using storage directly, call `init()` explicitly:
162
+
163
+ ```typescript
164
+ const storage = new MastraStorage({
165
+ id: "composite",
166
+ domains: {
167
+ memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
168
+ },
169
+ });
170
+
171
+ await storage.init();
172
+
173
+ // Access domain-specific stores via getStore()
174
+ const memoryStore = await storage.getStore("memory");
175
+ const thread = await memoryStore?.getThreadById({ threadId: "..." });
176
+ ```
177
+
178
+ ## Use Cases
179
+
180
+ ### Separate databases for different workloads
181
+
182
+ Use a local database for development while keeping production data in a managed service:
183
+
184
+ ```typescript
185
+ import { MastraStorage } from "@mastra/core/storage";
186
+ import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
187
+ import { MemoryLibSQL } from "@mastra/libsql";
188
+
189
+ const storage = new MastraStorage({
190
+ id: "composite",
191
+ domains: {
192
+ // Use local SQLite for development, PostgreSQL for production
193
+ memory:
194
+ process.env.NODE_ENV === "development"
195
+ ? new MemoryLibSQL({ url: "file:./dev.db" })
196
+ : new MemoryPG({ connectionString: process.env.DATABASE_URL }),
197
+ workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
198
+ scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
199
+ },
200
+ });
201
+ ```
202
+
203
+ ### Specialized storage for observability
204
+
205
+ Use a time-series database for traces while keeping other data in PostgreSQL:
206
+
207
+ ```typescript
208
+ import { MastraStorage } from "@mastra/core/storage";
209
+ import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
210
+ import { ObservabilityStorageClickhouse } from "@mastra/clickhouse";
211
+
212
+ const storage = new MastraStorage({
213
+ id: "composite",
214
+ domains: {
215
+ memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
216
+ workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
217
+ scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
218
+ observability: new ObservabilityStorageClickhouse({
219
+ url: process.env.CLICKHOUSE_URL,
220
+ }),
221
+ },
222
+ });
223
+ ```
@@ -98,8 +98,9 @@ const storage = await LanceStorage.create("my-storage", "/path/to/db");
98
98
  // Required when using storage directly
99
99
  await storage.init();
100
100
 
101
- // Now you can use the storage
102
- await storage.getThread({ threadId: "..." });
101
+ // Access domain-specific stores via getStore()
102
+ const memoryStore = await storage.getStore('memory');
103
+ const thread = await memoryStore?.getThreadById({ threadId: "..." });
103
104
  ```
104
105
 
105
106
  :::warning
@@ -115,7 +115,7 @@ const mastra = new Mastra({
115
115
 
116
116
  If using storage directly without Mastra, call `init()` explicitly:
117
117
 
118
- ```typescript
118
+ ```typescript
119
119
  import { LibSQLStore } from "@mastra/libsql";
120
120
 
121
121
  const storage = new LibSQLStore({
@@ -124,5 +124,8 @@ const storage = new LibSQLStore({
124
124
  });
125
125
 
126
126
  await storage.init();
127
- await storage.getThread({ threadId: "..." });
127
+
128
+ // Access domain-specific stores via getStore()
129
+ const memoryStore = await storage.getStore('memory');
130
+ const thread = await memoryStore?.getThreadById({ threadId: "..." });
128
131
  ```
@@ -117,6 +117,7 @@ If you're using storage directly without Mastra, you must call `init()` explicit
117
117
  import { MongoDBStore } from "@mastra/mongodb";
118
118
 
119
119
  const storage = new MongoDBStore({
120
+ id: 'mongodb-storage',
120
121
  url: process.env.MONGODB_URL,
121
122
  dbName: process.env.MONGODB_DATABASE,
122
123
  });
@@ -124,8 +125,9 @@ const storage = new MongoDBStore({
124
125
  // Required when using storage directly
125
126
  await storage.init();
126
127
 
127
- // Now you can use the storage
128
- await storage.getThread({ threadId: "..." });
128
+ // Access domain-specific stores via getStore()
129
+ const memoryStore = await storage.getStore('memory');
130
+ const thread = await memoryStore?.getThreadById({ threadId: "..." });
129
131
  ```
130
132
 
131
133
  :::warning