@mastra/mcp-docs-server 1.0.0-beta.9 → 1.0.0

package/.docs/raw/reference/storage/composite.mdx

@@ -0,0 +1,245 @@
+---
+title: "Reference: Composite Storage | Storage"
+description: Documentation for combining multiple storage backends in Mastra.
+packages:
+  - "@mastra/clickhouse"
+  - "@mastra/core"
+  - "@mastra/libsql"
+  - "@mastra/pg"
+---
+
+# Composite Storage
+
+`MastraCompositeStore` can compose storage domains from different providers. Use it when you need different databases for different purposes. For example, use LibSQL for memory and PostgreSQL for workflows.
+
+## Installation
+
+`MastraCompositeStore` is included in `@mastra/core`:
+
+```bash
+npm install @mastra/core@beta
+```
+
+You'll also need to install the storage providers you want to compose:
+
+```bash
+npm install @mastra/pg@beta @mastra/libsql@beta
+```
+
+## Storage domains
+
+Mastra organizes storage into five specialized domains, each handling a specific type of data. Each domain can be backed by a different storage adapter, and domain classes are exported from each storage package.
+
+| Domain | Description |
+|--------|-------------|
+| `memory` | Conversation persistence for agents. Stores threads (conversation sessions), messages, resources (user identities), and working memory (persistent context across conversations). |
+| `workflows` | Workflow execution state. When workflows suspend for human input, external events, or scheduled resumption, their state is persisted here to enable resumption after server restarts. |
+| `scores` | Evaluation results from Mastra's evals system. Scores and metrics are persisted here for analysis and comparison over time. |
+| `observability` | Telemetry data including traces and spans. Agent interactions, tool calls, and LLM requests generate spans collected into traces for debugging and performance analysis. |
+| `agents` | Agent configurations for stored agents. Enables agents to be defined and updated at runtime without code deployments. |
+
+## Usage
+
+### Basic composition
+
+Import domain classes directly from each store package and compose them:
+
+```typescript title="src/mastra/index.ts"
+import { MastraCompositeStore } from "@mastra/core/storage";
+import { WorkflowsPG, ScoresPG } from "@mastra/pg";
+import { MemoryLibSQL } from "@mastra/libsql";
+import { Mastra } from "@mastra/core";
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: "composite",
+    domains: {
+      memory: new MemoryLibSQL({ url: "file:./local.db" }),
+      workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+      scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
+    },
+  }),
+});
+```
+
+### With a default storage
+
+Use `default` to specify a fallback storage, then override specific domains:
+
+```typescript title="src/mastra/index.ts"
+import { MastraCompositeStore } from "@mastra/core/storage";
+import { PostgresStore } from "@mastra/pg";
+import { MemoryLibSQL } from "@mastra/libsql";
+import { Mastra } from "@mastra/core";
+
+const pgStore = new PostgresStore({
+  id: "pg",
+  connectionString: process.env.DATABASE_URL,
+});
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: "composite",
+    default: pgStore,
+    domains: {
+      memory: new MemoryLibSQL({ url: "file:./local.db" }),
+    },
+  }),
+});
+```
+
+## Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Unique identifier for this storage instance.",
+      isOptional: false,
+    },
+    {
+      name: "default",
+      type: "MastraCompositeStore",
+      description:
+        "Default storage adapter. Domains not explicitly specified in `domains` will use this storage's domains as fallbacks.",
+      isOptional: true,
+    },
+    {
+      name: "domains",
+      type: "object",
+      description:
+        "Individual domain overrides. Each domain can come from a different storage adapter. These take precedence over the default storage.",
+      isOptional: true,
+    },
+    {
+      name: "domains.memory",
+      type: "MemoryStorage",
+      description: "Storage for threads, messages, and resources.",
+      isOptional: true,
+    },
+    {
+      name: "domains.workflows",
+      type: "WorkflowsStorage",
+      description: "Storage for workflow snapshots.",
+      isOptional: true,
+    },
+    {
+      name: "domains.scores",
+      type: "ScoresStorage",
+      description: "Storage for evaluation scores.",
+      isOptional: true,
+    },
+    {
+      name: "domains.observability",
+      type: "ObservabilityStorage",
+      description: "Storage for traces and spans.",
+      isOptional: true,
+    },
+    {
+      name: "domains.agents",
+      type: "AgentsStorage",
+      description: "Storage for stored agent configurations.",
+      isOptional: true,
+    },
+    {
+      name: "disableInit",
+      type: "boolean",
+      description:
+        "When true, automatic initialization is disabled. You must call init() explicitly.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Initialization
+
+`MastraCompositeStore` initializes each configured domain independently. When passed to the Mastra class, `init()` is called automatically:
+
+```typescript title="src/mastra/index.ts"
+import { MastraCompositeStore } from "@mastra/core/storage";
+import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
+import { Mastra } from "@mastra/core";
+
+const storage = new MastraCompositeStore({
+  id: "composite",
+  domains: {
+    memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
+    workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+    scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
+  },
+});
+
+export const mastra = new Mastra({
+  storage, // init() called automatically
+});
+```
+
+If using storage directly, call `init()` explicitly:
+
+```typescript
+import { MastraCompositeStore } from "@mastra/core/storage";
+import { MemoryPG } from "@mastra/pg";
+
+const storage = new MastraCompositeStore({
+  id: "composite",
+  domains: {
+    memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
+  },
+});
+
+await storage.init();
+
+// Access domain-specific stores via getStore()
+const memoryStore = await storage.getStore("memory");
+const thread = await memoryStore?.getThreadById({ threadId: "..." });
+```
+
+## Use cases
+
+### Separate databases for different workloads
+
+Use a local database for development while keeping production data in a managed service:
+
+```typescript
+import { MastraCompositeStore } from "@mastra/core/storage";
+import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
+import { MemoryLibSQL } from "@mastra/libsql";
+
+const storage = new MastraCompositeStore({
+  id: "composite",
+  domains: {
+    // Use local SQLite for development, PostgreSQL for production
+    memory:
+      process.env.NODE_ENV === "development"
+        ? new MemoryLibSQL({ url: "file:./dev.db" })
+        : new MemoryPG({ connectionString: process.env.DATABASE_URL }),
+    workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+    scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
+  },
+});
+```
+
+### Specialized storage for observability
+
+Use a time-series database for traces while keeping other data in PostgreSQL:
+
+```typescript
+import { MastraCompositeStore } from "@mastra/core/storage";
+import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
+import { ObservabilityStorageClickhouse } from "@mastra/clickhouse";
+
+const storage = new MastraCompositeStore({
+  id: "composite",
+  domains: {
+    memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
+    workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+    scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
+    observability: new ObservabilityStorageClickhouse({
+      url: process.env.CLICKHOUSE_URL,
+      username: process.env.CLICKHOUSE_USERNAME,
+      password: process.env.CLICKHOUSE_PASSWORD,
+    }),
+  },
+});
+```

package/.docs/raw/reference/storage/convex.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Convex Storage | Storage"
 description: Documentation for the Convex storage implementation in Mastra.
+packages:
+  - "@mastra/convex"
 ---
 
 # Convex Storage
@@ -9,7 +11,7 @@ The Convex storage implementation provides a serverless storage solution using [
 
 ## Installation
 
-```bash copy
+```bash
 npm install @mastra/convex@beta
 ```
 
@@ -21,7 +23,7 @@ Before using `ConvexStore`, you need to set up the Convex schema and storage han
 
 In `convex/schema.ts`:
 
-```typescript copy
+```typescript
 import { defineSchema } from 'convex/server';
 import {
   mastraThreadsTable,
@@ -32,7 +34,7 @@ import {
   mastraVectorIndexesTable,
   mastraVectorsTable,
   mastraDocumentsTable,
-} from '@mastra/convex/server';
+} from '@mastra/convex/schema';
 
 export default defineSchema({
   mastra_threads: mastraThreadsTable,
@@ -50,7 +52,7 @@ export default defineSchema({
 
 In `convex/mastra/storage.ts`:
 
-```typescript copy
+```typescript
 import { mastraStorage } from '@mastra/convex/server';
 
 export const handle = mastraStorage;
@@ -58,7 +60,7 @@ export const handle = mastraStorage;
 
 ### 3. Deploy to Convex
 
-```bash copy
+```bash
 npx convex dev
 # or for production
 npx convex deploy
@@ -66,7 +68,7 @@ npx convex deploy
 
 ## Usage
 
-```typescript copy showLineNumbers
+```typescript
 import { ConvexStore } from "@mastra/convex";
 
 const storage = new ConvexStore({

package/.docs/raw/reference/storage/dynamodb.mdx

@@ -1,6 +1,11 @@
 ---
 title: "Reference: DynamoDB Storage | Storage"
 description: "Documentation for the DynamoDB storage implementation in Mastra, using a single-table design with ElectroDB."
+packages:
+  - "@mastra/dynamodb"
+  - "@mastra/libsql"
+  - "@mastra/memory"
+  - "@mastra/pg"
 ---
 
 # DynamoDB Storage
@@ -15,10 +20,11 @@ The DynamoDB storage implementation provides a scalable and performant NoSQL dat
 - Compatible with AWS DynamoDB Local for development
 - Stores Thread, Message, Trace, Eval, and Workflow data
 - Optimized for serverless environments
+- Configurable TTL (Time To Live) for automatic data expiration per entity type
 
 ## Installation
 
-```bash copy
+```bash
 npm install @mastra/dynamodb@beta
 # or
 pnpm add @mastra/dynamodb@beta
@@ -36,13 +42,13 @@ Detailed instructions for setting up the table using AWS CloudFormation or AWS C
 
 ### Basic Usage
 
-```typescript copy showLineNumbers
+```typescript
 import { Memory } from "@mastra/memory";
 import { DynamoDBStore } from "@mastra/dynamodb";
 
 // Initialize the DynamoDB storage
 const storage = new DynamoDBStore({
-  name: "dynamodb", // A name for this storage instance
+  id: "dynamodb", // Unique identifier for this storage instance
   config: {
     tableName: "mastra-single-table", // Name of your DynamoDB table
     region: "us-east-1", // Optional: AWS region, defaults to 'us-east-1'
@@ -72,11 +78,11 @@ For local development, you can use [DynamoDB Local](https://docs.aws.amazon.com/
 
 2.  **Configure `DynamoDBStore` to use the local endpoint:**
 
-    ```typescript copy showLineNumbers
+    ```typescript copy
     import { DynamoDBStore } from "@mastra/dynamodb";
 
     const storage = new DynamoDBStore({
-      name: "dynamodb-local",
+      id: "dynamodb-local",
       config: {
         tableName: "mastra-single-table", // Ensure this table is created in your local DynamoDB
         region: "localhost", // Can be any string for local, 'localhost' is common
@@ -95,9 +101,9 @@ For local development, you can use [DynamoDB Local](https://docs.aws.amazon.com/
 <PropertiesTable
   content={[
     {
-      name: "name",
+      name: "id",
       type: "string",
-      description: "A name for the storage instance.",
+      description: "Unique identifier for this storage instance.",
       isOptional: false,
     },
     {
@@ -127,14 +133,134 @@ For local development, you can use [DynamoDB Local](https://docs.aws.amazon.com/
         "AWS credentials object with `accessKeyId` and `secretAccessKey`. If not provided, the AWS SDK will attempt to source credentials from environment variables, IAM roles (e.g., for EC2/Lambda), or the shared AWS credentials file.",
       isOptional: true,
     },
+    {
+      name: "config.ttl",
+      type: "object",
+      description:
+        "TTL (Time To Live) configuration for automatic data expiration. Configure per entity type: thread, message, trace, eval, workflow_snapshot, resource, score. Each entity config includes: enabled (boolean), attributeName (string, default: 'ttl'), defaultTtlSeconds (number).",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## TTL (Time To Live) Configuration
+
+DynamoDB TTL allows you to automatically delete items after a specified time period. This is useful for:
+
+- **Cost optimization**: Automatically remove old data to reduce storage costs
+- **Data lifecycle management**: Implement retention policies for compliance
+- **Performance**: Prevent tables from growing indefinitely
+- **Privacy compliance**: Automatically purge personal data after specified periods
+
+### Enabling TTL
+
+To use TTL, you must:
+
+1. **Configure TTL in DynamoDBStore** (shown below)
+2. **Enable TTL on your DynamoDB table** via AWS Console or CLI, specifying the attribute name (default: `ttl`)
+
+```typescript
+import { DynamoDBStore } from "@mastra/dynamodb";
+
+const storage = new DynamoDBStore({
+  name: "dynamodb",
+  config: {
+    tableName: "mastra-single-table",
+    region: "us-east-1",
+    ttl: {
+      // Messages expire after 30 days
+      message: {
+        enabled: true,
+        defaultTtlSeconds: 30 * 24 * 60 * 60, // 30 days
+      },
+      // Threads expire after 90 days
+      thread: {
+        enabled: true,
+        defaultTtlSeconds: 90 * 24 * 60 * 60, // 90 days
+      },
+      // Traces expire after 7 days with custom attribute name
+      trace: {
+        enabled: true,
+        attributeName: "expiresAt", // Custom TTL attribute
+        defaultTtlSeconds: 7 * 24 * 60 * 60, // 7 days
+      },
+      // Workflow snapshots don't expire
+      workflow_snapshot: {
+        enabled: false,
+      },
+    },
+  },
+});
+```
+
+### Supported Entity Types
+
+TTL can be configured for these entity types:
+
+| Entity | Description |
+|--------|-------------|
+| `thread` | Conversation threads |
+| `message` | Messages within threads |
+| `trace` | Observability traces |
+| `eval` | Evaluation results |
+| `workflow_snapshot` | Workflow state snapshots |
+| `resource` | User/resource data |
+| `score` | Scoring results |
+
+### TTL Entity Configuration
+
+Each entity type accepts the following configuration:
+
+<PropertiesTable
+  content={[
+    {
+      name: "enabled",
+      type: "boolean",
+      description: "Whether TTL is enabled for this entity type.",
+      isOptional: false,
+    },
+    {
+      name: "attributeName",
+      type: "string",
+      description: "The DynamoDB attribute name to use for TTL. Must match the TTL attribute configured on your DynamoDB table. Defaults to 'ttl'.",
+      isOptional: true,
+    },
+    {
+      name: "defaultTtlSeconds",
+      type: "number",
+      description: "Default TTL in seconds from item creation time. Items will be automatically deleted by DynamoDB after this duration.",
+      isOptional: true,
+    },
   ]}
 />
 
+### Enabling TTL on Your DynamoDB Table
+
+After configuring TTL in your code, you must enable TTL on the DynamoDB table itself:
+
+**Using AWS CLI:**
+
+```bash
+aws dynamodb update-time-to-live \
+  --table-name mastra-single-table \
+  --time-to-live-specification "Enabled=true, AttributeName=ttl"
+```
+
+**Using AWS Console:**
+
+1. Go to the DynamoDB console
+2. Select your table
+3. Go to "Additional settings" tab
+4. Under "Time to Live (TTL)", click "Manage TTL"
+5. Enable TTL and specify the attribute name (default: `ttl`)
+
+> **Note**: DynamoDB deletes expired items within 48 hours after expiration. Items remain queryable until actually deleted.
+
 ## AWS IAM Permissions
 
 The IAM role or user executing the code needs appropriate permissions to interact with the specified DynamoDB table and its indexes. Below is a sample policy. Replace `${YOUR_TABLE_NAME}` with your actual table name and `${YOUR_AWS_REGION}` and `${YOUR_AWS_ACCOUNT_ID}` with appropriate values.
 
-```json copy
+```json
 {
   "Version": "2012-10-17",
   "Statement": [

package/.docs/raw/reference/storage/lance.mdx

@@ -1,6 +1,9 @@
 ---
 title: "Reference: LanceDB Storage | Storage"
 description: Documentation for the LanceDB storage implementation in Mastra.
+packages:
+  - "@mastra/core"
+  - "@mastra/lance"
 ---
 
 # LanceDB Storage
@@ -17,7 +20,7 @@ npm install @mastra/lance@beta
 
 ### Basic Storage Usage
 
-```typescript copy showLineNumbers
+```typescript
 import { LanceStorage } from "@mastra/lance";
 
 // Connect to a local database
@@ -77,7 +80,7 @@ The LanceStorage implementation automatically handles schema creation and update
 
 When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
 
-```typescript copy
+```typescript
 import { Mastra } from "@mastra/core";
 import { LanceStorage } from "@mastra/lance";
 
@@ -90,7 +93,7 @@ const mastra = new Mastra({
 
 If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
 
-```typescript copy
+```typescript
 import { LanceStorage } from "@mastra/lance";
 
 const storage = await LanceStorage.create("my-storage", "/path/to/db");
@@ -98,8 +101,9 @@ const storage = await LanceStorage.create("my-storage", "/path/to/db");
 // Required when using storage directly
 await storage.init();
 
-// Now you can use the storage
-await storage.getThread({ threadId: "..." });
+// Access domain-specific stores via getStore()
+const memoryStore = await storage.getStore('memory');
+const thread = await memoryStore?.getThreadById({ threadId: "..." });
 ```
 
 :::warning