@mastra/mcp-docs-server 0.13.39 → 1.0.0-beta.1

package/.docs/raw/memory/storage/memory-with-libsql.mdx

@@ -18,7 +18,7 @@ OPENAI_API_KEY=<your-api-key>
 And install the following package:
 
 ```bash copy
-npm install @mastra/libsql
+npm install @mastra/libsql@beta
 ```
 
 ## Adding memory to an agent
@@ -32,16 +32,18 @@ import { openai } from "@ai-sdk/openai";
 import { LibSQLStore } from "@mastra/libsql";
 
 export const libsqlAgent = new Agent({
-  name: "libsql-agent",
+  id: "libsql-agent",
+  name: "LibSQL Agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
   model: openai("gpt-4o"),
   memory: new Memory({
     storage: new LibSQLStore({
+      id: 'libsql-agent-storage',
       url: "file:libsql-agent.db",
     }),
     options: {
-      generateTitle: true,
+      generateTitle: true, // Explicitly enable automatic title generation
     },
   }),
 });
@@ -54,7 +56,7 @@ Embeddings are numeric vectors used by memory’s `semanticRecall` to retrieve r
 Install `fastembed` to get started:
 
 ```bash copy
-npm install @mastra/fastembed
+npm install @mastra/fastembed@beta
 ```
 
 Add the following to your agent:
@@ -67,15 +69,18 @@ import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
 import { fastembed } from "@mastra/fastembed";
 
 export const libsqlAgent = new Agent({
-  name: "libsql-agent",
+  id: "libsql-agent",
+  name: "LibSQL Agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
   model: openai("gpt-4o"),
   memory: new Memory({
     storage: new LibSQLStore({
+      id: 'libsql-agent-storage',
       url: "file:libsql-agent.db",
     }),
     vector: new LibSQLVector({
+      id: 'libsql-agent-vector',
       connectionUrl: "file:libsql-agent.db",
     }),
     embedder: fastembed,
@@ -86,7 +91,7 @@ export const libsqlAgent = new Agent({
         messageRange: 2,
       },
       threads: {
-        generateTitle: true,
+        generateTitle: true, // Explicitly enable automatic title generation
       },
     },
   }),
@@ -137,4 +142,4 @@ for await (const chunk of stream.textStream) {
 
 ## Related
 
-- [Calling Agents](/examples/agents/calling-agents)
+- [Calling Agents](/examples/v1/agents/calling-agents)

package/.docs/raw/memory/storage/memory-with-pg.mdx

@@ -19,7 +19,7 @@ DATABASE_URL=<your-connection-string>
 And install the following package:
 
 ```bash copy
-npm install @mastra/pg
+npm install @mastra/pg@beta
 ```
 
 ## Adding memory to an agent
@@ -33,16 +33,18 @@ import { openai } from "@ai-sdk/openai";
 import { PostgresStore } from "@mastra/pg";
 
 export const pgAgent = new Agent({
-  name: "pg-agent",
+  id: "pg-agent",
+  name: "PG Agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
   model: openai("gpt-4o"),
   memory: new Memory({
     storage: new PostgresStore({
+      id: 'pg-agent-storage',
       connectionString: process.env.DATABASE_URL!,
     }),
     options: {
-      generateTitle: true,
+      generateTitle: true, // Explicitly enable automatic title generation
     },
   }),
 });
@@ -55,7 +57,7 @@ Embeddings are numeric vectors used by memory’s `semanticRecall` to retrieve r
 Install `fastembed` to get started:
 
 ```bash copy
-npm install @mastra/fastembed
+npm install @mastra/fastembed@beta
 ```
 
 Add the following to your agent:
@@ -68,15 +70,18 @@ import { PostgresStore, PgVector } from "@mastra/pg";
 import { fastembed } from "@mastra/fastembed";
 
 export const pgAgent = new Agent({
-  name: "pg-agent",
+  id: "pg-agent",
+  name: "PG Agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
   model: openai("gpt-4o"),
   memory: new Memory({
     storage: new PostgresStore({
+      id: 'pg-agent-storage',
       connectionString: process.env.DATABASE_URL!,
     }),
     vector: new PgVector({
+      id: 'pg-agent-vector',
       connectionString: process.env.DATABASE_URL!,
     }),
     embedder: fastembed,
@@ -135,4 +140,4 @@ for await (const chunk of stream.textStream) {
 
 ## Related
 
-- [Calling Agents](/examples/agents/calling-agents)
+- [Calling Agents](/examples/v1/agents/calling-agents)

package/.docs/raw/memory/storage/memory-with-upstash.mdx

@@ -24,7 +24,7 @@ You can get your Upstash credentials by signing up at [upstash.com](https://upst
 And install the following package:
 
 ```bash copy
-npm install @mastra/upstash
+npm install @mastra/upstash@beta
 ```
 
 ## Adding memory to an agent
@@ -38,17 +38,19 @@ import { openai } from "@ai-sdk/openai";
 import { UpstashStore } from "@mastra/upstash";
 
 export const upstashAgent = new Agent({
-  name: "upstash-agent",
+  id: "upstash-agent",
+  name: "Upstash Agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
   model: openai("gpt-4o"),
   memory: new Memory({
     storage: new UpstashStore({
+      id: 'upstash-agent-storage',
       url: process.env.UPSTASH_REDIS_REST_URL!,
       token: process.env.UPSTASH_REDIS_REST_TOKEN!,
     }),
     options: {
-      generateTitle: true,
+      generateTitle: true, // Explicitly enable automatic title generation
     },
   }),
 });
@@ -61,7 +63,7 @@ Embeddings are numeric vectors used by memory’s `semanticRecall` to retrieve r
 Install `fastembed` to get started:
 
 ```bash copy
-npm install @mastra/fastembed
+npm install @mastra/fastembed@beta
 ```
 
 Add the following to your agent:
@@ -74,16 +76,19 @@ import { UpstashStore, UpstashVector } from "@mastra/upstash";
 import { fastembed } from "@mastra/fastembed";
 
 export const upstashAgent = new Agent({
-  name: "upstash-agent",
+  id: "upstash-agent",
+  name: "Upstash Agent",
   instructions:
     "You are an AI agent with the ability to automatically recall memories from previous interactions.",
   model: openai("gpt-4o"),
   memory: new Memory({
     storage: new UpstashStore({
+      id: 'upstash-agent-storage',
       url: process.env.UPSTASH_REDIS_REST_URL!,
       token: process.env.UPSTASH_REDIS_REST_TOKEN!,
     }),
     vector: new UpstashVector({
+      id: 'upstash-agent-vector',
       url: process.env.UPSTASH_VECTOR_REST_URL!,
       token: process.env.UPSTASH_VECTOR_REST_TOKEN!,
     }),
@@ -143,4 +148,4 @@ for await (const chunk of stream.textStream) {
 
 ## Related
 
-- [Calling Agents](/examples/agents/calling-agents)
+- [Calling Agents](/examples/v1/agents/calling-agents)

package/.docs/raw/memory/threads-and-resources.mdx

@@ -10,13 +10,13 @@ Mastra organizes memory into threads, which are records that group related inter
 1. **`thread`**: A globally unique ID representing the conversation (e.g., `support_123`). Must be unique across all resources.
 2. **`resource`**: The user or entity that owns the thread (e.g., `user_123`, `org_456`).
 
-The `resource` is especially important for [resource-scoped memory](./working-memory#resource-scoped-memory), which allows memory to persist across all threads associated with the same user or entity.
+The `resource` is especially important for [resource-scoped memory](./working-memory#resource-scoped-memory-default), which allows memory to persist across all threads associated with the same user or entity.
 
 ```typescript {4} showLineNumbers
 const stream = await agent.stream("message for agent", {
   memory: {
-    thread: "user-123",
-    resource: "test-123",
+    thread: "conversation-123",
+    resource: "user-123",
   },
 });
 ```
@@ -31,21 +31,19 @@ Even with memory configured, agents won’t store or recall information unless b
 
 ### Thread title generation
 
-Mastra can automatically generate descriptive thread titles based on the user's first message. Enable it by setting `generateTitle` to `true`. This improves organization and makes it easier to display conversations in your UI.
+Mastra can automatically generate descriptive thread titles based on the user's first message. This feature is disabled by default. Enable it by setting `generateTitle` to `true`. This improves organization and makes it easier to display conversations in your UI.
 
 ```typescript {3-7} showLineNumbers
 export const testAgent = new Agent({
   memory: new Memory({
     options: {
-      threads: {
-        generateTitle: true,
-      }
+      generateTitle: true, // Explicitly enable automatic title generation
     },
   }),
 });
 ```
 
-> Title generation runs asynchronously after the agent responds and does not affect response time. See the [full configuration reference](/reference/memory/memory-class) for details and examples.
+> Title generation runs asynchronously after the agent responds and does not affect response time. See the [full configuration reference](/reference/v1/memory/memory-class) for details and examples.
 
 #### Optimizing title generation
 
@@ -70,7 +68,7 @@ export const testAgent = new Agent({
 
 #### Dynamic model selection and instructions
 
-You can configure thread title generation dynamically by passing functions to `model` and `instructions`. These functions receive the `runtimeContext` object, allowing you to adapt title generation based on user-specific values.
+You can configure thread title generation dynamically by passing functions to `model` and `instructions`. These functions receive the `requestContext` object, allowing you to adapt title generation based on user-specific values.
 
 ```typescript {7-16} showLineNumbers
 export const testAgent = new Agent({
@@ -79,14 +77,14 @@ export const testAgent = new Agent({
     options: {
       threads: {
         generateTitle: {
-          model: ({ runtimeContext }) => {
-            const userTier = runtimeContext.get("userTier");
+          model: ({ requestContext }) => {
+            const userTier = requestContext.get("userTier");
             return userTier === "premium"
               ? openai("gpt-4.1")
               : openai("gpt-4.1-nano");
           },
-          instructions: ({ runtimeContext }) => {
-            const language = runtimeContext.get("userLanguage") || "English";
+          instructions: ({ requestContext }) => {
+            const language = requestContext.get("userLanguage") || "English";
             return `Generate a concise, engaging title in ${language} based on the user's first message.`;
           },
         },

package/.docs/raw/memory/working-memory.mdx

@@ -7,7 +7,7 @@ import YouTube from "@site/src/components/YouTube-player";
 
 # Working Memory
 
-While [conversation history](/docs/memory/conversation-history) and [semantic recall](./semantic-recall) help agents remember conversations, working memory allows them to maintain persistent information about users across interactions.
+While [conversation history](/docs/v1/memory/conversation-history) and [semantic recall](./semantic-recall) help agents remember conversations, working memory allows them to maintain persistent information about users across interactions.
 
 Think of it as the agent's active thoughts or scratchpad – the key information they keep available about the user or task. It's similar to how a person would naturally remember someone's name, preferences, or important details during a conversation.
 
@@ -15,8 +15,8 @@ This is useful for maintaining ongoing state that's always relevant and should a
 
 Working memory can persist at two different scopes:
 
-- **Thread-scoped** (default): Memory is isolated per conversation thread
-- **Resource-scoped**: Memory persists across all conversation threads for the same user
+- **Resource-scoped** (default): Memory persists across all conversation threads for the same user
+- **Thread-scoped**: Memory is isolated per conversation thread
 
 **Important:** Switching between scopes means the agent won't see memory from the other scope - thread-scoped memory is completely separate from resource-scoped memory.
 
@@ -31,6 +31,7 @@ import { openai } from "@ai-sdk/openai";
 
 // Create agent with working memory enabled
 const agent = new Agent({
+  id: "personal-assistant",
   name: "PersonalAssistant",
   instructions: "You are a helpful personal assistant.",
   model: openai("gpt-4o"),
@@ -54,9 +55,9 @@ Working memory is a block of Markdown text that the agent is able to update over
 
 Working memory can operate in two different scopes, allowing you to choose how memory persists across conversations:
 
-### Thread-Scoped Memory (Default)
+### Resource-Scoped Memory (Default)
 
-By default, working memory is scoped to individual conversation threads. Each thread maintains its own isolated memory:
+By default, working memory persists across all conversation threads for the same user (resourceId), enabling persistent user memory:
 
 ```typescript
 const memory = new Memory({
@@ -64,11 +65,13 @@ const memory = new Memory({
   options: {
     workingMemory: {
       enabled: true,
-      scope: 'thread', // Default - memory is isolated per thread
+      scope: "resource", // Memory persists across all user threads
       template: `# User Profile
 - **Name**:
+- **Location**:
 - **Interests**:
-- **Current Goal**:
+- **Preferences**:
+- **Long-term Goals**:
 `,
     },
   },
@@ -76,13 +79,26 @@ const memory = new Memory({
 ```
 
 **Use cases:**
-- Different conversations about separate topics
-- Temporary or session-specific information
-- Workflows where each thread needs working memory but threads are ephemeral and not related to each other
 
-### Resource-Scoped Memory
+- Personal assistants that remember user preferences
+- Customer service bots that maintain customer context
+- Educational applications that track student progress
+
+### Usage with Agents
+
+When using resource-scoped memory, make sure to pass the `resourceId` parameter:
+
+```typescript
+// Resource-scoped memory requires resourceId
+const response = await agent.generate("Hello!", {
+  threadId: "conversation-123",
+  resourceId: "user-alice-456", // Same user across different threads
+});
+```
+
+### Thread-Scoped Memory
 
-Resource-scoped memory persists across all conversation threads for the same user (resourceId), enabling persistent user memory:
+Thread-scoped memory isolates working memory to individual conversation threads. Each thread maintains its own isolated memory:
 
 ```typescript
 const memory = new Memory({
@@ -362,6 +378,6 @@ await memory.updateWorkingMemory({
 
 ## Examples
 
-- [Working memory with template](/examples/memory/working-memory-template)
-- [Working memory with schema](/examples/memory/working-memory-schema)
+- [Working memory with template](/examples/v1/memory/working-memory-template)
+- [Working memory with schema](/examples/v1/memory/working-memory-schema)
 - [Per-resource working memory](https://github.com/mastra-ai/mastra/tree/main/examples/memory-per-resource-example) - Complete example showing resource-scoped memory persistence

package/.docs/raw/observability/overview.mdx

@@ -9,62 +9,45 @@ Mastra provides comprehensive observability features designed specifically for A
 
 ## Key Features
 
-### Structured Logging
-
-Debug applications with contextual logging:
-
-- **Context propagation**: Automatic correlation with traces
-- **Configurable levels**: Filter by severity in development and production
-
-### AI Tracing
+### Tracing
 
 Specialized tracing for AI operations that captures:
 
-- **LLM interactions**: Token usage, latency, prompts, and completions
+- **Model interactions**: Token usage, latency, prompts, and completions
 - **Agent execution**: Decision paths, tool calls, and memory operations
 - **Workflow steps**: Branching logic, parallel execution, and step outputs
 - **Automatic instrumentation**: Zero-configuration tracing with decorators
 
-### OTEL Tracing
-
-Traditional distributed tracing with OpenTelemetry:
-
-- **Standard OTLP protocol**: Compatible with existing observability infrastructure
-- **HTTP and database instrumentation**: Automatic spans for common operations
-- **Provider integrations**: Datadog, New Relic, Jaeger, and other OTLP collectors
-- **Distributed context**: W3C Trace Context propagation
-
 ## Quick Start
 
 Configure Observability in your Mastra instance:
 
 ```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
-import { PinoLogger } from "@mastra/core";
+import { PinoLogger } from "@mastra/loggers";
 import { LibSqlStorage } from "@mastra/libsql";
+import { Observability } from "@mastra/observability";
 
 export const mastra = new Mastra({
   // ... other config
   logger: new PinoLogger(),
-  observability: {
-    default: { enabled: true }, // Enables AI Tracing
-  },
   storage: new LibSQLStore({
+    id: 'mastra-storage',
     url: "file:./mastra.db", // Storage is required for tracing
   }),
-  telemetry: {
-    enabled: true, // Enables OTEL Tracing
-  },
+  observability: new Observability({ // Enables Tracing
+    default: { enabled: true },
+  }),
 });
 ```
 
 With this basic setup, you will see Traces and Logs in both Studio and in Mastra Cloud.
 
-We also support various external tracing providers like Langfuse, Braintrust, and any OpenTelemetry-compatible platform (Datadog, New Relic, SigNoz, etc.). See more about this in the [AI Tracing](/docs/observability/ai-tracing/overview) documentation.
+We also support various external tracing providers like Langfuse, Braintrust, and any OpenTelemetry-compatible platform (Datadog, New Relic, SigNoz, etc.). See more about this in the [Tracing](/docs/v1/observability/tracing/overview) documentation.
 
 ## What's Next?
 
-- **[Set up AI Tracing](/docs/observability/ai-tracing/overview)**: Configure tracing for your application
-- **[Configure Logging](/docs/observability/logging)**: Add structured logging
-- **[View Examples](/examples/observability/basic-ai-tracing)**: See observability in action
-- **[API Reference](/reference/observability/ai-tracing/)**: Detailed configuration options
+- **[Set up Tracing](/docs/v1/observability/tracing/overview)**: Configure tracing for your application
+- **[Configure Logging](/docs/v1/logging)**: Add structured logging
+- **[View Examples](/examples/v1/observability/basic-tracing)**: See observability in action
+- **[API Reference](/reference/v1/observability/tracing/instances)**: Detailed configuration options

package/.docs/raw/observability/{ai-tracing → tracing}/exporters/arize.mdx

@@ -1,26 +1,16 @@
 ---
-title: "Arize Exporter | AI Tracing | Observability | Mastra Docs"
-description: "Send AI traces to Arize Phoenix or Arize AX using OpenTelemetry and OpenInference"
+title: "Arize Exporter | Tracing | Observability | Mastra Docs"
+description: "Send traces to Arize Phoenix or Arize AX using OpenTelemetry and OpenInference"
 ---
 
 # Arize Exporter
 
-[Arize](https://arize.com/) provides observability platforms for AI applications through [Phoenix](https://phoenix.arize.com/) (open-source) and [Arize AX](https://arize.com/generative-ai/) (enterprise). The Arize exporter sends AI traces using OpenTelemetry and [OpenInference](https://github.com/Arize-ai/openinference/tree/main/spec) semantic conventions, compatible with any OpenTelemetry platform that supports OpenInference.
-
-## When to Use Arize
-
-Arize is ideal when you need:
-
-- **OpenInference standards** - Industry-standard semantic conventions for AI traces
-- **Flexible deployment** - Self-hosted Phoenix or managed Arize AX
-- **OpenTelemetry compatibility** - Works with any OTLP-compatible platform
-- **Comprehensive AI observability** - LLM traces, embeddings, and retrieval analytics
-- **Open-source option** - Full-featured local deployment with Phoenix
+[Arize](https://arize.com/) provides observability platforms for AI applications through [Phoenix](https://phoenix.arize.com/) (open-source) and [Arize AX](https://arize.com/generative-ai/) (enterprise). The Arize exporter sends traces using OpenTelemetry and [OpenInference](https://github.com/Arize-ai/openinference/tree/main/spec) semantic conventions, compatible with any OpenTelemetry platform that supports OpenInference.
 
 ## Installation
 
 ```bash npm2yarn
-npm install @mastra/arize
+npm install @mastra/arize@beta
 ```
 
 ## Configuration
@@ -46,10 +36,11 @@ PHOENIX_PROJECT_NAME=mastra-service  # Optional, defaults to 'mastra-service'
 
 ```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
 import { ArizeExporter } from "@mastra/arize";
 
 export const mastra = new Mastra({
-  observability: {
+  observability: new Observability({
     configs: {
       arize: {
         serviceName: process.env.PHOENIX_PROJECT_NAME || "mastra-service",
@@ -62,7 +53,7 @@ export const mastra = new Mastra({
         ],
       },
     },
-  },
+  }),
 });
 ```
 
@@ -103,10 +94,11 @@ ARIZE_PROJECT_NAME=mastra-service  # Optional
 
 ```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
 import { ArizeExporter } from "@mastra/arize";
 
 export const mastra = new Mastra({
-  observability: {
+  observability: new Observability({
     configs: {
       arize: {
         serviceName: process.env.ARIZE_PROJECT_NAME || "mastra-service",
@@ -119,7 +111,7 @@ export const mastra = new Mastra({
         ],
       },
     },
-  },
+  }),
 });
 ```
 
@@ -196,7 +188,7 @@ This exporter implements the [OpenInference Semantic Conventions](https://github
 
 ## Related
 
-- [AI Tracing Overview](/docs/observability/ai-tracing/overview)
+- [Tracing Overview](/docs/v1/observability/tracing/overview)
 - [Phoenix Documentation](https://docs.arize.com/phoenix)
 - [Arize AX Documentation](https://docs.arize.com/)
 - [OpenInference Specification](https://github.com/Arize-ai/openinference/tree/main/spec)

package/.docs/raw/observability/{ai-tracing → tracing}/exporters/braintrust.mdx

@@ -1,26 +1,16 @@
 ---
-title: "Braintrust Exporter | AI Tracing | Observability | Mastra Docs"
-description: "Send AI traces to Braintrust for evaluation and monitoring"
+title: "Braintrust Exporter | Tracing | Observability | Mastra Docs"
+description: "Send traces to Braintrust for evaluation and monitoring"
 ---
 
 # Braintrust Exporter
 
-[Braintrust](https://www.braintrust.dev/) is an evaluation and monitoring platform that helps you measure and improve LLM application quality. The Braintrust exporter sends your AI traces to Braintrust, enabling systematic evaluation, scoring, and experimentation.
-
-## When to Use Braintrust
-
-Braintrust excels at:
-
-- **Evaluation workflows** - Systematic quality measurement
-- **Experiment tracking** - Compare model versions and prompts
-- **Dataset management** - Curate test cases and golden datasets
-- **Regression testing** - Ensure improvements don't break existing functionality
-- **Team collaboration** - Share experiments and insights
+[Braintrust](https://www.braintrust.dev/) is an evaluation and monitoring platform that helps you measure and improve LLM application quality. The Braintrust exporter sends your traces to Braintrust, enabling systematic evaluation, scoring, and experimentation.
 
 ## Installation
 
 ```bash npm2yarn
-npm install @mastra/braintrust
+npm install @mastra/braintrust@beta
 ```
 
 ## Configuration
@@ -41,10 +31,11 @@ BRAINTRUST_PROJECT_NAME=my-project  # Optional, defaults to 'mastra-tracing'
 
 ```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
 import { BraintrustExporter } from "@mastra/braintrust";
 
 export const mastra = new Mastra({
-  observability: {
+  observability: new Observability({
     configs: {
       braintrust: {
         serviceName: "my-service",
@@ -56,7 +47,7 @@ export const mastra = new Mastra({
         ],
       },
     },
-  },
+  }),
 });
 ```
 
@@ -76,5 +67,5 @@ new BraintrustExporter({
 
 ## Related
 
-- [AI Tracing Overview](/docs/observability/ai-tracing/overview)
+- [Tracing Overview](/docs/v1/observability/tracing/overview)
 - [Braintrust Documentation](https://www.braintrust.dev/docs)

package/.docs/raw/observability/{ai-tracing → tracing}/exporters/cloud.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Cloud Exporter | AI Tracing | Observability | Mastra Docs"
+title: "Cloud Exporter | Tracing | Observability | Mastra Docs"
 description: "Send traces to Mastra Cloud for production monitoring"
 ---
 
@@ -7,15 +7,6 @@ description: "Send traces to Mastra Cloud for production monitoring"
 
 The `CloudExporter` sends traces to Mastra Cloud for centralized monitoring and team collaboration. It's automatically enabled when using the default observability configuration with a valid access token.
 
-## When to Use CloudExporter
-
-CloudExporter is ideal for:
-
-- **Production monitoring** - Centralized trace visualization
-- **Team collaboration** - Share traces across your organization
-- **Advanced analytics** - Insights and performance metrics
-- **Zero maintenance** - No infrastructure to manage
-
 ## Configuration
 
 ### Prerequisites
@@ -32,10 +23,10 @@ MASTRA_CLOUD_ACCESS_TOKEN=mst_xxxxxxxxxxxxxxxx
 
 ```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
-import { CloudExporter } from "@mastra/core/ai-tracing";
+import { Observability, CloudExporter } from "@mastra/observability";
 
 export const mastra = new Mastra({
-  observability: {
+  observability: new Observability({
     configs: {
       production: {
         serviceName: "my-service",
@@ -44,7 +35,7 @@ export const mastra = new Mastra({
         ],
       },
     },
-  },
+  }),
 });
 ```
 
@@ -53,10 +44,13 @@ export const mastra = new Mastra({
 When using the default observability configuration, CloudExporter is automatically included if the access token is set:
 
 ```typescript
+import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
+
 export const mastra = new Mastra({
-  observability: {
+  observability: new Observability({
     default: { enabled: true }, // Automatically includes CloudExporter if token exists
-  },
+  }),
 });
 ```
 
@@ -116,6 +110,6 @@ CloudExporter uses intelligent batching to optimize network usage. Traces are bu
 
 ## Related
 
-- [AI Tracing Overview](/docs/observability/ai-tracing/overview)
-- [DefaultExporter](/docs/observability/ai-tracing/exporters/default)
+- [Tracing Overview](/docs/v1/observability/tracing/overview)
+- [DefaultExporter](/docs/v1/observability/tracing/exporters/default)
 - [Mastra Cloud Documentation](https://cloud.mastra.ai/docs)