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

package/.docs/raw/guides/migrations/upgrade-to-v1/storage.mdx

@@ -7,8 +7,160 @@ description: "Learn how to migrate storage-related changes when upgrading to v1.
 
 Storage APIs have been standardized with consistent pagination and naming patterns across all methods.
 
+## Database Migration
+
+Run these SQL migrations through your normal migration process (e.g., Prisma Migrate, Drizzle Kit, or your DBA review process).
+
+### Scorers table column rename
+
+The `runtimeContext` column in `mastra_scorers` was renamed to `requestContext`.
+
+:::note[Who needs this migration]
+Only if you use `@mastra/pg` or `@mastra/libsql` with evals/scoring and have existing data in the `runtimeContext` column.
+:::
+
+:::important[What breaks without it]
+Existing score records won't have their request context data accessible.
+:::
+
+After deploying v1 (which adds the new `requestContext` column on init), copy the data and drop the old column:
+
+```sql
+UPDATE mastra_scorers SET "requestContext" = "runtimeContext" WHERE "runtimeContext" IS NOT NULL;
+ALTER TABLE mastra_scorers DROP COLUMN "runtimeContext";
+```
+
+### Duplicate spans migration
+
+If you're upgrading from an older version of Mastra, you may have duplicate `(traceId, spanId)` entries in your `mastra_spans` table. V1 adds a unique constraint on these columns to ensure data integrity, but this constraint cannot be added if duplicates exist.
+
+:::note[Who needs this migration]
+Only if you have existing spans data from Mastra versions prior to v1 and encounter errors about duplicate key violations or constraint creation failures.
+:::
+
+:::important[What breaks without it]
+The storage initialization may fail when trying to add the unique constraint, or you may see errors like "duplicate key value violates unique constraint".
+:::
+
+**Option 1: Use the CLI (Recommended)**
+
+Run the migration command which automatically deduplicates spans and adds the constraint:
+
+```bash
+npx mastra migrate
+```
+
+The CLI bundles your project, connects to your configured storage, and runs the migration. It keeps the most complete record (based on `endTime` and attributes) when removing duplicates.
+
+**Option 2: Manual SQL (PostgreSQL)**
+
+If you prefer to run the migration manually:
+
+```sql
+-- Remove duplicates, keeping the most complete record
+DELETE FROM mastra_spans a USING mastra_spans b
+WHERE a.ctid < b.ctid
+  AND a."traceId" = b."traceId"
+  AND a."spanId" = b."spanId";
+
+-- Add the unique constraint
+ALTER TABLE mastra_spans ADD CONSTRAINT mastra_spans_trace_span_unique UNIQUE ("traceId", "spanId");
+```
+
+**Option 3: Manual migration (Other databases)**
+
+For ClickHouse, LibSQL, MongoDB, or MSSQL, use the programmatic API:
+
+```typescript
+const storage = mastra.getStorage();
+const observabilityStore = await storage.getStore('observability');
+
+// Check if migration is needed
+const status = await observabilityStore?.checkSpansMigrationStatus();
+console.log(status);
+
+// Run the migration
+const result = await observabilityStore?.migrateSpans();
+console.log(result);
+```
+
+### JSON columns (TEXT → JSONB)
+
+**PostgreSQL only.** The `metadata` column in `mastra_threads` and `snapshot` column in `mastra_workflow_snapshot` changed from TEXT to JSONB.
+
+:::note[Recommended]
+Migrating to JSONB enables native PostgreSQL JSON operators and GIN indexing for better query performance on JSON fields.
+:::
+
+```sql
+ALTER TABLE mastra_threads
+ALTER COLUMN metadata TYPE jsonb
+USING metadata::jsonb;
+
+ALTER TABLE mastra_workflow_snapshot
+ALTER COLUMN snapshot TYPE jsonb
+USING snapshot::jsonb;
+```
+
+## Added
+
+### Storage composition in MastraCompositeStore
+
+`MastraCompositeStore` can now compose storage domains from different adapters. Use it when you need different databases for different purposes - for example, PostgreSQL for memory and workflows, but a specialized database for observability.
+
+```typescript
+import { MastraCompositeStore } from "@mastra/core/storage";
+import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
+import { MemoryLibSQL } from "@mastra/libsql";
+import { Mastra } from "@mastra/core";
+
+// Compose domains from different stores
+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 }),
+    },
+  }),
+});
+```
+
+See the [Storage Composition reference](/reference/v1/storage/composite) for more details.
+
 ## Changed
 
+### `MastraStorage` renamed to `MastraCompositeStore`
+
+The `MastraStorage` class has been renamed to `MastraCompositeStore` to better reflect its role as a composite storage implementation that routes different domains to different underlying stores. This avoids confusion with the general "Mastra Storage" concept (the `storage` property on the Mastra instance).
+
+The old `MastraStorage` name remains available as a deprecated alias for backward compatibility, but will be removed in a future version.
+
+To migrate, update your imports and instantiation:
+
+```diff
+- import { MastraStorage } from "@mastra/core/storage";
++ import { MastraCompositeStore } from "@mastra/core/storage";
+  import { MemoryLibSQL } from "@mastra/libsql";
+  import { WorkflowsPG } from "@mastra/pg";
+
+  export const mastra = new Mastra({
+-   storage: new MastraStorage({
++   storage: new MastraCompositeStore({
+      id: "composite",
+      domains: {
+        memory: new MemoryLibSQL({ url: "file:./memory.db" }),
+        workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
+      },
+    }),
+  });
+```
+
+:::note
+If you're using a single store implementation (like `PostgresStore` or `LibSQLStore`) directly, no changes are needed. This only affects code that explicitly uses `MastraStorage` for composite storage.
+:::
+
 ### Required `id` property for storage instances
 
 Storage instances now require an `id` property. This unique identifier is used for tracking and managing storage instances within Mastra. The `id` should be a descriptive, unique string for each storage instance in your application.
@@ -36,7 +188,7 @@ All pagination APIs now use `page` and `perPage` instead of `offset` and `limit`
 To migrate, update all pagination parameters from `offset/limit` to `page/perPage`. Note that `page` is 0-indexed.
 
 ```diff
-  storage.listMessages({
+  memoryStore.listMessages({
     threadId: 'thread-123',
 -   offset: 0,
 -   limit: 20,
@@ -52,18 +204,20 @@ The `getMessagesPaginated()` method has been replaced with `listMessages()`. The
 To migrate, rename the method and update pagination parameters. You can now use `perPage: false` to fetch all records.
 
 ```diff
++ const memoryStore = await storage.getStore('memory');
++
   // Paginated
 - const result = await storage.getMessagesPaginated({
-+ const result = await storage.listMessages({
++ const result = await memoryStore?.listMessages({
     threadId: 'thread-123',
 -   offset: 0,
 -   limit: 20,
 +   page: 0,
 +   perPage: 20,
   });
-  
+
   // Fetch all records (no pagination limit)
-+ const allMessages = await storage.listMessages({
++ const allMessages = await memoryStore?.listMessages({
 +   threadId: 'thread-123',
 +   page: 0,
 +   perPage: false,
@@ -80,19 +234,106 @@ npx @mastra/codemod@beta v1/storage-get-messages-paginated .
 
 :::
 
-### `getThreadsByResourceId` to `listThreadsByResourceId`
+### Domain-specific storage access via `getStore()`
 
-The `getThreadsByResourceId()` method has been renamed to `listThreadsByResourceId()`. This change aligns with the convention that `list*` methods return collections.
+Storage operations are now accessed through domain-specific stores instead of directly on the storage instance. 
 
-To migrate, rename the method call and update pagination parameters.
+Domains include:
+- **`memory`** - Threads, messages, and resources
+- **`workflows`** - Workflow snapshots
+- **`scores`** - Evaluation scores
+- **`observability`** - Traces and spans
+- **`agents`** - Stored agent data
+
+To migrate, call `getStore()` with the domain name, then call methods on the returned store.
+
+```diff
+  const storage = mastra.getStorage();
+
+  // Memory operations (threads, messages, resources)
+- const thread = await storage.getThread({ threadId: '123' });
+- await storage.saveThread({ thread });
++ const memoryStore = await storage.getStore('memory');
++ const thread = await memoryStore?.getThreadById({ threadId: '123' });
++ await memoryStore?.saveThread({ thread });
+
+  // Workflow operations (snapshots)
+- const snapshot = await storage.loadWorkflowSnapshot({ runId, workflowName });
+- await storage.persistWorkflowSnapshot({ runId, workflowName, snapshot });
++ const workflowStore = await storage.getStore('workflows');
++ const snapshot = await workflowStore?.loadWorkflowSnapshot({ runId, workflowName });
++ await workflowStore?.persistWorkflowSnapshot({ runId, workflowName, snapshot });
+
+  // Observability operations (traces, spans)
+- const traces = await storage.listTraces({ page: 0, perPage: 20 });
++ const observabilityStore = await storage.getStore('observability');
++ const traces = await observabilityStore?.listTraces({ page: 0, perPage: 20 });
+
+  // Score operations (evaluations)
+- const scores = await storage.listScoresByScorerId({ scorerId: 'helpfulness' });
++ const scoresStore = await storage.getStore('scores');
++ const scores = await scoresStore?.listScoresByScorerId({ scorerId: 'helpfulness' });
+```
+
+### `getThreadsByResourceId` to `listThreads`
+
+The `getThreadsByResourceId()` method has been replaced with `listThreads()`. The new method adds pagination support and filtering by `resourceId`, `metadata`, or both.
+
+:::important
+
+The old `getThreadsByResourceId()` returned all matching threads without pagination. The new `listThreads()` requires pagination parameters. To preserve the old behavior of fetching all threads, use `perPage: false`.
+
+:::
+
+To migrate, use the memory store and the new `listThreads()` method with pagination and an optional filter object.
 
 ```diff
 - const threads = await storage.getThreadsByResourceId({
-+ const threads = await storage.listThreadsByResourceId({
-    resourceId: 'res-123',
+-   resourceId: 'res-123',
+- });
++ const memoryStore = await storage.getStore('memory');
++
++ // Paginated (recommended for large datasets)
++ const result = await memoryStore?.listThreads({
++   filter: { resourceId: 'res-123' },
 +   page: 0,
 +   perPage: 20,
-  });
++ });
++ const threads = result?.threads;
++
++ // Or fetch all threads like before (use perPage: false)
++ const allResult = await memoryStore?.listThreads({
++   filter: { resourceId: 'res-123' },
++   perPage: false,
++ });
++ const allThreads = allResult?.threads;
+```
+
+The new method also supports:
+- Listing all threads (omit filter)
+- Filtering by metadata only
+- Combined resourceId + metadata filters
+
+```typescript
+// List all threads
+await memoryStore?.listThreads({ page: 0, perPage: 20 });
+
+// Filter by metadata only
+await memoryStore?.listThreads({
+  filter: { metadata: { status: 'active' } },
+  page: 0,
+  perPage: 20,
+});
+
+// Combined filter
+await memoryStore?.listThreads({
+  filter: {
+    resourceId: 'user-123',
+    metadata: { category: 'support' },
+  },
+  page: 0,
+  perPage: 20,
+});
 ```
 
 :::tip[Codemod]
@@ -100,7 +341,7 @@ To migrate, rename the method call and update pagination parameters.
 You can use Mastra's codemod CLI to update your code automatically:
 
 ```shell
-npx @mastra/codemod@beta v1/storage-get-threads-by-resource .
+npx @mastra/codemod@beta v1/storage-list-threads-by-resource-to-list-threads .
 ```
 
 :::
@@ -109,11 +350,12 @@ npx @mastra/codemod@beta v1/storage-get-threads-by-resource .
 
 The `getWorkflowRuns()` method has been renamed to `listWorkflowRuns()`. This change aligns with the convention that `list*` methods return collections.
 
-To migrate, rename the method call and update pagination parameters.
+To migrate, use the workflows stores, rename the method call and update pagination parameters.
 
 ```diff
 - const runs = await storage.getWorkflowRuns({
-+ const runs = await storage.listWorkflowRuns({
++ const workflowStore = await storage.getStore('workflows');
++ const runs = await workflowStore?.listWorkflowRuns({
     fromDate,
     toDate,
 +   page: 0,
@@ -135,11 +377,12 @@ npx @mastra/codemod@beta v1/storage-list-workflow-runs .
 
 The `getMessagesById()` method has been renamed to `listMessagesById()`. This change aligns with the convention that `list*` methods return collections.
 
-To migrate, rename the method call.
+To migrate, use the memory store and rename the method call.
 
 ```diff
++ const memoryStore = await storage.getStore('memory');
 - const result = await storage.getMessagesById({
-+ const result = await storage.listMessagesById({
++ const result = await memoryStore?.listMessagesById({
     messageIds: ['msg-1', 'msg-2'],
   });
 ```
@@ -158,20 +401,22 @@ npx @mastra/codemod@beta v1/storage-list-messages-by-id .
 
 The `getMessages()` and `saveMessages()` methods have changed signatures and return types. Format overloads have been removed, and the methods now always work with `MastraDBMessage`. This change simplifies the API by removing format variations.
 
-To migrate, remove format parameters and update code to work with the consistent return type.
+To migrate, use the memory store, remove format parameters, and update code to work with the consistent return type.
 
 ```diff
++ const memoryStore = await storage.getStore('memory');
++
   // Always returns { messages: MastraDBMessage[] }
 - const v1Messages = await storage.getMessages({ threadId, format: 'v1' });
 - const v2Messages = await storage.getMessages({ threadId, format: 'v2' });
-+ const result = await storage.getMessages({ threadId });
-+ const messages = result.messages; // MastraDBMessage[]
-  
++ const result = await memoryStore?.getMessages({ threadId });
++ const messages = result?.messages; // MastraDBMessage[]
+
   // SaveMessages always uses MastraDBMessage
 - await storage.saveMessages({ messages: v1Messages, format: 'v1' });
 - await storage.saveMessages({ messages: v2Messages, format: 'v2' });
-+ const result = await storage.saveMessages({ messages: mastraDBMessages });
-+ const saved = result.messages; // MastraDBMessage[]
++ const saveResult = await memoryStore?.saveMessages({ messages: mastraDBMessages });
++ const saved = saveResult?.messages; // MastraDBMessage[]
 ```
 
 ### Vector store API from positional to named arguments
@@ -298,16 +543,17 @@ To migrate, update method names from `getScores` to `listScoresByScorerId` and r
 
 Non-paginated storage functions have been removed in favor of paginated versions. All list operations now use pagination, though you can fetch all records with `perPage: false`. This change provides consistency across the API and prevents accidental loading of large datasets.
 
-To migrate, use paginated methods. For fetching all records, use `perPage: false`.
+To migrate, use paginated methods via domain stores. For fetching all records, use `perPage: false`.
 
 ```diff
 - // Non-paginated direct access
 - const messages = await storage.getMessages({ threadId });
 
-+ // Use paginated methods
-+ const result = await storage.listMessages({ threadId, page: 0, perPage: 20 });
++ // Use paginated methods via domain stores
++ const memoryStore = await storage.getStore('memory');
++ const result = await memoryStore?.listMessages({ threadId, page: 0, perPage: 20 });
 + // Or fetch all
-+ const allMessages = await storage.listMessages({
++ const allMessages = await memoryStore?.listMessages({
 +   threadId,
 +   page: 0,
 +   perPage: false,

package/.docs/raw/guides/migrations/upgrade-to-v1/tracing.mdx

@@ -33,20 +33,36 @@ export const mastra = new Mastra({
 });
 ```
 
-**After (v1 with observability - quick start):**
+**After (v1 with observability):**
 
 ```typescript
 import { Mastra } from '@mastra/core';
-import { Observability } from '@mastra/observability';
+import {
+  Observability,
+  DefaultExporter,
+  CloudExporter,
+  SensitiveDataFilter,
+} from '@mastra/observability';
 
 export const mastra = new Mastra({
   observability: new Observability({
-    default: { enabled: true },
+    configs: {
+      default: {
+        serviceName: 'mastra',
+        exporters: [
+          new DefaultExporter(), // Persists traces to storage for Mastra Studio
+          new CloudExporter(), // Sends traces to Mastra Cloud (if MASTRA_CLOUD_ACCESS_TOKEN is set)
+        ],
+        spanOutputProcessors: [
+          new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
+        ],
+      },
+    },
   }),
 });
 ```
 
-This minimal configuration automatically includes the `DefaultExporter`, `CloudExporter`, and `SensitiveDataFilter` processor. See the [observability tracing documentation](/docs/v1/observability/tracing/overview) for full configuration options.
+This configuration includes `DefaultExporter`, `CloudExporter`, and `SensitiveDataFilter` processor. See the [observability tracing documentation](/docs/v1/observability/tracing/overview) for full configuration options.
 
 **After (v1 with custom configuration):**
 
@@ -86,14 +102,14 @@ export const mastra = new Mastra({
 Key changes:
 1. Install `@mastra/observability` package
 2. Replace `telemetry:` with `observability: new Observability()`
-3. Use `default: { enabled: true }` for quick setup, or `configs:` for custom configuration
+3. Use explicit `configs:` with `DefaultExporter`, `CloudExporter`, and `SensitiveDataFilter`
 4. Export types change from string literals (`'otlp'`) to exporter class instances (`new OtelExporter()`)
 
 See the [exporters documentation](/docs/v1/observability/tracing/overview#exporters) for all available exporters.
 
 ### From AI Tracing
 
-If you already upgraded to AI tracing (the intermediate system), you only need to wrap your configuration and install the new package.
+If you already upgraded to AI tracing (the intermediate system), you need to install the new package and use the explicit configuration.
 
 **Before (AI tracing):**
 
@@ -111,19 +127,35 @@ export const mastra = new Mastra({
 
 ```typescript
 import { Mastra } from '@mastra/core';
-import { Observability } from '@mastra/observability';
+import {
+  Observability,
+  DefaultExporter,
+  CloudExporter,
+  SensitiveDataFilter,
+} from '@mastra/observability';
 
 export const mastra = new Mastra({
   observability: new Observability({
-    default: { enabled: true },
+    configs: {
+      default: {
+        serviceName: 'mastra',
+        exporters: [
+          new DefaultExporter(),
+          new CloudExporter(),
+        ],
+        spanOutputProcessors: [
+          new SensitiveDataFilter(),
+        ],
+      },
+    },
   }),
 });
 ```
 
 Key changes:
 1. Install `@mastra/observability` package
-2. Import `Observability` from `@mastra/observability`
-3. Wrap configuration with `new Observability()`
+2. Import `Observability`, exporters, and processors from `@mastra/observability`
+3. Use explicit `configs` with `DefaultExporter`, `CloudExporter`, and `SensitiveDataFilter`
 
 ## Changed
 
@@ -144,18 +176,30 @@ npm install @mastra/observability@beta
 
 ### Registry configuration
 
-The observability registry is now configured using an `Observability` class instance instead of a plain object.
+The observability registry is now configured using an `Observability` class instance with explicit configs instead of a plain object.
 
-To migrate, wrap your configuration object with `new Observability()`.
+To migrate, use `new Observability()` with explicit exporters and processors.
 
 ```diff
-+ import { Observability } from '@mastra/observability';
++ import {
++   Observability,
++   DefaultExporter,
++   CloudExporter,
++   SensitiveDataFilter,
++ } from '@mastra/observability';
 
   export const mastra = new Mastra({
 -   observability: {
-+   observability: new Observability({
-      default: { enabled: true },
+-     default: { enabled: true },
 -   },
++   observability: new Observability({
++     configs: {
++       default: {
++         serviceName: 'mastra',
++         exporters: [new DefaultExporter(), new CloudExporter()],
++         spanOutputProcessors: [new SensitiveDataFilter()],
++       },
++     },
 +   }),
   });
 ```
@@ -236,11 +280,22 @@ Simply remove the `instrumentation.mjs` file and configure observability in your
 
 ```typescript
 // src/mastra/index.ts
-import { Observability } from '@mastra/observability';
+import {
+  Observability,
+  DefaultExporter,
+  CloudExporter,
+  SensitiveDataFilter,
+} from '@mastra/observability';
 
 export const mastra = new Mastra({
   observability: new Observability({
-    default: { enabled: true },
+    configs: {
+      default: {
+        serviceName: 'mastra',
+        exporters: [new DefaultExporter(), new CloudExporter()],
+        spanOutputProcessors: [new SensitiveDataFilter()],
+      },
+    },
   }),
 });
 ```

package/.docs/raw/guides/migrations/upgrade-to-v1/vectors.mdx

@@ -29,7 +29,6 @@ To migrate, add an `id` field to your vector store constructor.
   const pineconeStore = new PineconeVector({
 +   id: 'pinecone-production',
     apiKey: process.env.PINECONE_API_KEY,
-    environment: process.env.PINECONE_ENVIRONMENT,
   });
 ```
 
@@ -45,3 +44,49 @@ To migrate, replace all calls to `getVectors()` with `listVectors()`.
 - const vectors = await vectorStore.getVectors({ ... });
 + const vectors = await vectorStore.listVectors({ ... });
 ```
+
+### LibSQLVector: `connectionUrl` to `url`
+
+The `connectionUrl` parameter has been renamed to `url` to align with the `@libsql/client` API and match LibSQLStorage.
+
+```diff
+  const vectorStore = new LibSQLVector({
+    id: 'my-vector',
+-   connectionUrl: 'file:./db.sqlite',
++   url: 'file:./db.sqlite',
+  });
+```
+
+### OpenSearchVector: `url` to `node`
+
+The `url` parameter has been renamed to `node` to match the OpenSearch `ClientOptions` API. The constructor now accepts all OpenSearch client options including authentication, SSL, and compression.
+
+```diff
+  const vectorStore = new OpenSearchVector({
+    id: 'my-vector',
+-   url: 'http://localhost:9200',
++   node: 'http://localhost:9200',
+  });
+```
+
+### PineconeVector: `environment` removed
+
+The `environment` parameter has been removed. Use `controllerHostUrl` instead if you need to specify a custom controller host. The constructor now accepts all Pinecone configuration options.
+
+```diff
+  const vectorStore = new PineconeVector({
+    id: 'my-vector',
+    apiKey: process.env.PINECONE_API_KEY,
+-   environment: process.env.PINECONE_ENVIRONMENT,
+  });
+```
+
+If you need a custom controller host:
+
+```ts
+const vectorStore = new PineconeVector({
+  id: 'my-vector',
+  apiKey: process.env.PINECONE_API_KEY,
+  controllerHostUrl: 'https://api.pinecone.io',
+});
+```