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

package/.docs/raw/reference/memory/listThreads.mdx

@@ -0,0 +1,187 @@
+---
+title: "Reference: Memory.listThreads() | Memory"
+description: "Documentation for the `Memory.listThreads()` method in Mastra, which retrieves threads with optional filtering by resourceId and/or metadata."
+packages:
+  - "@mastra/memory"
+---
+
+# Memory.listThreads()
+
+The `listThreads()` method retrieves threads with pagination support and optional filtering by `resourceId`, `metadata`, or both.
+
+## Usage Examples
+
+### List all threads with pagination
+
+```typescript
+const result = await memory.listThreads({
+  page: 0,
+  perPage: 10,
+});
+```
+
+### Fetch all threads without pagination
+
+Use `perPage: false` to retrieve all matching threads at once.
+
+:::warning
+
+Generally speaking it's recommended to use pagination, especially for large datasets. Use this option cautiously.
+
+:::
+
+```typescript
+const result = await memory.listThreads({
+  filter: { resourceId: "user-123" },
+  perPage: false,
+});
+```
+
+### Filter by resourceId
+
+```typescript
+const result = await memory.listThreads({
+  filter: { resourceId: "user-123" },
+  page: 0,
+  perPage: 10,
+});
+```
+
+### Filter by metadata
+
+```typescript
+const result = await memory.listThreads({
+  filter: { metadata: { category: "support", priority: "high" } },
+  page: 0,
+  perPage: 10,
+});
+```
+
+### Combined filter (resourceId & metadata)
+
+```typescript
+const result = await memory.listThreads({
+  filter: {
+    resourceId: "user-123",
+    metadata: { status: "active" },
+  },
+  page: 0,
+  perPage: 10,
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "filter",
+      type: "{ resourceId?: string; metadata?: Record<string, unknown> }",
+      description:
+        "Optional filter object. resourceId filters threads by resource ID. metadata filters threads by metadata key-value pairs (AND logic - all must match)",
+      isOptional: true,
+    },
+    {
+      name: "page",
+      type: "number",
+      description: "Page number (0-indexed) to retrieve",
+      isOptional: true,
+    },
+    {
+      name: "perPage",
+      type: "number | false",
+      description: "Maximum number of threads to return per page, or false to fetch all",
+      isOptional: true,
+    },
+    {
+      name: "orderBy",
+      type: "{ field: 'createdAt' | 'updatedAt', direction: 'ASC' | 'DESC' }",
+      description:
+        "Sort configuration with field and direction (defaults to { field: 'createdAt', direction: 'DESC' })",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "result",
+      type: "Promise<StorageListThreadsOutput>",
+      description: "A promise that resolves to paginated thread results with metadata",
+    },
+  ]}
+/>
+
+The return object contains:
+
+- `threads`: Array of thread objects
+- `total`: Total number of threads matching the filter
+- `page`: Current page number (same as the input `page` parameter)
+- `perPage`: Items per page (same as the input `perPage` parameter)
+- `hasMore`: Boolean indicating if more results are available
+
+## Extended usage example
+
+```typescript title="src/test-memory.ts"
+import { mastra } from "./mastra";
+
+const agent = mastra.getAgent("agent");
+const memory = await agent.getMemory();
+
+let currentPage = 0;
+const perPage = 25;
+let hasMorePages = true;
+
+// Fetch all active threads for a user, sorted by creation date
+while (hasMorePages) {
+  const result = await memory?.listThreads({
+    filter: {
+      resourceId: "user-123",
+      metadata: { status: "active" },
+    },
+    page: currentPage,
+    perPage: perPage,
+    orderBy: { field: "createdAt", direction: "ASC" },
+  });
+
+  if (!result) {
+    console.log("No threads");
+    break;
+  }
+
+  result.threads.forEach((thread) => {
+    console.log(`Thread: ${thread.id}, Created: ${thread.createdAt}`);
+  });
+
+  hasMorePages = result.hasMore;
+  currentPage++; // Move to next page
+}
+```
+
+## Metadata Filtering
+
+The metadata filter uses AND logic - all specified key-value pairs must match for a thread to be included in the results:
+
+```typescript
+// This will only return threads where BOTH conditions are true:
+// - category === 'support'
+// - priority === 'high'
+await memory.listThreads({
+  filter: {
+    metadata: {
+      category: "support",
+      priority: "high",
+    },
+  },
+});
+```
+
+## Related
+
+- [Memory Class Reference](/reference/v1/memory/memory-class)
+- [Getting Started with Memory](/docs/v1/memory/overview) (Covers threads/resources concept)
+- [createThread](/reference/v1/memory/createThread)
+- [getThreadById](/reference/v1/memory/getThreadById)

package/.docs/raw/reference/memory/memory-class.mdx

@@ -1,6 +1,11 @@
 ---
 title: "Reference: Memory Class | Memory"
 description: "Documentation for the `Memory` class in Mastra, which provides a robust system for managing conversation history and thread-based message storage."
+packages:
+  - "@mastra/core"
+  - "@mastra/libsql"
+  - "@mastra/memory"
+  - "@mastra/pg"
 ---
 
 # Memory Class
@@ -9,7 +14,7 @@ The `Memory` class provides a robust system for managing conversation history an
 
 ## Usage example
 
-```typescript title="src/mastra/agents/test-agent.ts" showLineNumbers copy
+```typescript title="src/mastra/agents/test-agent.ts"
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 
@@ -35,7 +40,7 @@ export const agent = new Agent({
   content={[
     {
       name: "storage",
-      type: "MastraStorage",
+      type: "MastraCompositeStore",
       description:
         'Storage implementation for persisting memory data. Defaults to `new DefaultStorage({ config: { url: "file:memory.db" } })` if not provided.',
       isOptional: true,
@@ -60,13 +65,7 @@ export const agent = new Agent({
       description: "Memory configuration options.",
       isOptional: true,
     },
-    {
-      name: "processors",
-      type: "MemoryProcessor[]",
-      description:
-        "Array of memory processors that can filter or transform messages before they're sent to the LLM.",
-      isOptional: true,
-    },
+    
   ]}
 />
 
@@ -82,6 +81,14 @@ export const agent = new Agent({
       isOptional: true,
       defaultValue: "10",
     },
+    {
+      name: "readOnly",
+      type: "boolean",
+      description:
+        "When true, prevents memory from saving new messages. Useful for read-only operations like previews or internal routing agents.",
+      isOptional: true,
+      defaultValue: "false",
+    },
     {
       name: "semanticRecall",
       type: "boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }",
@@ -100,12 +107,12 @@ export const agent = new Agent({
         "{ enabled: false, template: '# User Information\\n- **First Name**:\\n- **Last Name**:\\n...' }",
     },
     {
-      name: "threads",
-      type: "{ generateTitle?: boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> } }",
+      name: "generateTitle",
+      type: "boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> }",
       description:
-        "Settings related to memory thread creation. `generateTitle` controls automatic thread title generation from the user's first message. Can be a boolean or an object with custom model and instructions.",
+        "Controls automatic thread title generation from the user's first message. Can be a boolean or an object with custom model and instructions.",
       isOptional: true,
-      defaultValue: "{ generateTitle: false }",
+      defaultValue: "false",
     },
   ]}
 />
@@ -124,7 +131,7 @@ export const agent = new Agent({
 
 ## Extended usage example
 
-```typescript title="src/mastra/agents/test-agent.ts" showLineNumbers copy
+```typescript title="src/mastra/agents/test-agent.ts"
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
@@ -140,7 +147,7 @@ export const agent = new Agent({
     }),
     vector: new LibSQLVector({
       id: 'test-agent-vector',
-      connectionUrl: "file:./vector-memory.db",
+      url: "file:./vector-memory.db",
     }),
     options: {
       lastMessages: 10,
@@ -152,9 +159,7 @@ export const agent = new Agent({
       workingMemory: {
         enabled: true,
       },
-      threads: {
-        generateTitle: true,
-      },
+      generateTitle: true,
     },
   }),
 });
@@ -162,7 +167,7 @@ export const agent = new Agent({
 
 ## PostgreSQL with index configuration
 
-```typescript title="src/mastra/agents/pg-agent.ts" showLineNumbers copy
+```typescript title="src/mastra/agents/pg-agent.ts"
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
@@ -212,5 +217,7 @@ export const agent = new Agent({
 - [createThread](/reference/v1/memory/createThread)
 - [recall](/reference/v1/memory/recall)
 - [getThreadById](/reference/v1/memory/getThreadById)
-- [listThreadsByResourceId](/reference/v1/memory/listThreadsByResourceId)
+- [listThreads](/reference/v1/memory/listThreads)
 - [deleteMessages](/reference/v1/memory/deleteMessages)
+- [cloneThread](/reference/v1/memory/cloneThread)
+- [Clone Utility Methods](/reference/v1/memory/clone-utilities)

package/.docs/raw/reference/memory/recall.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Memory.recall() | Memory"
 description: "Documentation for the `Memory.recall()` method in Mastra, which retrieves messages from a specific thread with support for pagination, filtering options, and semantic search."
+packages:
+  - "@mastra/ai-sdk"
 ---
 
 # Memory.recall()
@@ -9,7 +11,7 @@ the `.recall()` method retrieves messages from a specific thread, with support f
 
 ## Usage Example
 
-```typescript copy
+```typescript
 await memory?.recall({ threadId: "user-123" });
 ```
 
@@ -61,9 +63,9 @@ await memory?.recall({ threadId: "user-123" });
     },
     {
       name: "filter",
-      type: "{ dateRange?: { start?: Date; end?: Date } }",
+      type: "{ dateRange?: { start?: Date; end?: Date; startExclusive?: boolean; endExclusive?: boolean } }",
       description:
-        "Filter options for message retrieval. Currently supports `dateRange` to filter messages by creation date.",
+        "Filter options for message retrieval. Currently supports `dateRange` to filter messages by creation date. Use `startExclusive` or `endExclusive` to exclude boundary dates (useful for cursor-based pagination).",
       isOptional: true,
     },
     {
@@ -138,7 +140,7 @@ await memory?.recall({ threadId: "user-123" });
 
 ## Extended usage example
 
-```typescript title="src/test-memory.ts" showLineNumbers copy
+```typescript title="src/test-memory.ts"
 import { mastra } from "./mastra";
 
 const agent = mastra.getAgent("agent");

package/.docs/raw/reference/observability/tracing/bridges/otel.mdx

@@ -1,6 +1,11 @@
 ---
 title: "Reference: OtelBridge | Observability"
 description: OpenTelemetry bridge for Tracing
+packages:
+  - "@mastra/core"
+  - "@mastra/langfuse"
+  - "@mastra/observability"
+  - "@mastra/otel-bridge"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";
@@ -150,8 +155,7 @@ The OtelBridge supports trace tagging for categorization and filtering. Tags are
 ### Usage
 
 ```typescript
-const result = await agent.generate({
-  messages: [{ role: "user", content: "Hello" }],
+const result = await agent.generate("Hello", {
   tracingOptions: {
     tags: ["production", "experiment-v2", "user-request"],
   },

package/.docs/raw/reference/observability/tracing/configuration.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Configuration | Observability"
 description: Tracing configuration types and registry functions
+packages:
+  - "@mastra/core"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";
@@ -51,6 +53,7 @@ interface ObservabilityInstanceConfig {
   spanOutputProcessors?: SpanOutputProcessor[];
   includeInternalSpans?: boolean;
   requestContextKeys?: string[];
+  serializationOptions?: SerializationOptions;
 }
 ```
 
@@ -98,6 +101,54 @@ interface ObservabilityInstanceConfig {
       description: "RequestContext keys to extract as metadata (supports dot notation)",
       required: false,
     },
+    {
+      name: "serializationOptions",
+      type: "SerializationOptions",
+      description: "Options for controlling serialization of span data (input/output/attributes)",
+      required: false,
+    },
+  ]}
+/>
+
+## SerializationOptions
+
+Options for controlling how span data is serialized before export. Use these to customize truncation limits for large payloads.
+
+```typescript
+interface SerializationOptions {
+  maxStringLength?: number;
+  maxDepth?: number;
+  maxArrayLength?: number;
+  maxObjectKeys?: number;
+}
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "maxStringLength",
+      type: "number",
+      description: "Maximum length for string values (default: 1024)",
+      required: false,
+    },
+    {
+      name: "maxDepth",
+      type: "number",
+      description: "Maximum depth for nested objects (default: 6)",
+      required: false,
+    },
+    {
+      name: "maxArrayLength",
+      type: "number",
+      description: "Maximum number of items in arrays (default: 50)",
+      required: false,
+    },
+    {
+      name: "maxObjectKeys",
+      type: "number",
+      description: "Maximum number of keys in objects (default: 50)",
+      required: false,
+    },
   ]}
 />
 

package/.docs/raw/reference/observability/tracing/exporters/arize.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: ArizeExporter | Observability"
 description: Arize exporter for Tracing using OpenInference
+packages:
+  - "@mastra/arize"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";
@@ -48,27 +50,27 @@ Non-reserved span attributes are serialized into the OpenInference `metadata` pa
       name: "endpoint",
       type: "string",
       description:
-        "Collector endpoint for trace exports (e.g., 'http://localhost:6006/v1/traces' for Phoenix). Required for Phoenix. Optional for Arize AX (defaults to https://otlp.arize.com/v1/traces).",
+        "Collector endpoint for trace exports. Falls back to PHOENIX_ENDPOINT env var. Required for Phoenix.",
       required: false,
     },
     {
       name: "apiKey",
       type: "string",
       description:
-        "API key for authentication. Required for Phoenix Cloud and Arize AX. Optional for self-hosted Phoenix.",
+        "API key for authentication. Falls back to ARIZE_API_KEY or PHOENIX_API_KEY env var.",
       required: false,
     },
     {
       name: "spaceId",
       type: "string",
       description:
-        "Arize AX space identifier. Required when sending traces to Arize AX.",
+        "Arize AX space identifier. Falls back to ARIZE_SPACE_ID env var. Required for Arize AX.",
       required: false,
     },
     {
       name: "projectName",
       type: "string",
-      description: "Project name added as OpenInference resource attribute",
+      description: "Project name. Falls back to ARIZE_PROJECT_NAME or PHOENIX_PROJECT_NAME env var.",
       required: false,
     },
     {
@@ -123,6 +125,14 @@ async export(spans: ReadOnlySpan[]): Promise<void>
 
 Batch exports spans using OpenTelemetry with OpenInference semantic conventions.
 
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered spans to the configured endpoint without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
+
 ### shutdown
 
 ```typescript
@@ -133,6 +143,16 @@ Flushes pending data and shuts down the client.
 
 ## Usage
 
+### Zero-Config (using environment variables)
+
+```typescript
+import { ArizeExporter } from "@mastra/arize";
+
+// For Phoenix: Set PHOENIX_ENDPOINT, PHOENIX_API_KEY, PHOENIX_PROJECT_NAME
+// For Arize AX: Set ARIZE_SPACE_ID, ARIZE_API_KEY, ARIZE_PROJECT_NAME
+const exporter = new ArizeExporter();
+```
+
 ### Phoenix Configuration
 
 ```typescript
@@ -168,8 +188,7 @@ The ArizeExporter supports trace tagging for categorization and filtering. Tags
 ### Usage
 
 ```typescript
-const result = await agent.generate({
-  messages: [{ role: "user", content: "Hello" }],
+const result = await agent.generate("Hello", {
   tracingOptions: {
     tags: ["production", "experiment-v2", "user-request"],
   },

package/.docs/raw/reference/observability/tracing/exporters/braintrust.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: BraintrustExporter | Observability"
 description: Braintrust exporter for Tracing
+packages:
+  - "@mastra/braintrust"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";
@@ -35,13 +37,13 @@ Extends `BaseExporterConfig`, which includes:
     {
       name: "apiKey",
       type: "string",
-      description: "Braintrust API key",
+      description: "Braintrust API key. Falls back to BRAINTRUST_API_KEY env var.",
       required: false,
     },
     {
       name: "endpoint",
       type: "string",
-      description: "Custom Braintrust endpoint",
+      description: "Custom Braintrust endpoint. Falls back to BRAINTRUST_ENDPOINT env var.",
       required: false,
     },
     {
@@ -83,6 +85,14 @@ async export(spans: ReadOnlySpan[]): Promise<void>
 
 Batch exports spans to Braintrust.
 
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered spans to Braintrust without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
+
 ### shutdown
 
 ```typescript
@@ -93,6 +103,17 @@ Flushes pending data and shuts down the client.
 
 ## Usage
 
+### Zero-Config (using environment variables)
+
+```typescript
+import { BraintrustExporter } from "@mastra/braintrust";
+
+// Reads from BRAINTRUST_API_KEY, BRAINTRUST_ENDPOINT
+const exporter = new BraintrustExporter();
+```
+
+### Explicit Configuration
+
 ```typescript
 import { BraintrustExporter } from "@mastra/braintrust";
 

package/.docs/raw/reference/observability/tracing/exporters/cloud-exporter.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: CloudExporter | Observability"
 description: API reference for the CloudExporter
+packages:
+  - "@mastra/observability"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";
@@ -85,6 +87,14 @@ Processes tracing events. Only exports SPAN_ENDED events to Cloud.
   ]}
 />
 
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered events to Mastra Cloud without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
+
 ### shutdown
 
 ```typescript

package/.docs/raw/reference/observability/tracing/exporters/console-exporter.mdx

@@ -1,6 +1,9 @@
 ---
 title: "Reference: ConsoleExporter | Observability"
 description: API reference for the ConsoleExporter
+packages:
+  - "@mastra/core"
+  - "@mastra/observability"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";