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

package/.docs/raw/mastra-cloud/observability.mdx

@@ -13,7 +13,7 @@ Mastra Cloud captures execution data to help you monitor your application's beha
 
 ## Logs
 
-You can view detailed logs for debugging and monitoring your application's behavior on the [Logs](/docs/mastra-cloud/dashboard#logs) page of the Dashboard.
+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.
 
 ![Dashboard logs](/img/mastra-cloud/mastra-cloud-dashboard-logs.jpg)
 
@@ -23,11 +23,11 @@ Each log entry includes its severity level and a detailed message showing agent,
 
 ## Traces
 
-More detailed traces are available for both agents and workflows by using a [logger](/docs/observability/logging) or enabling [telemetry](/docs/observability/ai-tracing/overview) using one of our [supported providers](/reference/observability/otel-tracing/providers/).
+More detailed traces are available for both agents and workflows by using a [logger]/docs/v1/logging) or enabling [observability]/docs/v1/observability/tracing/overview) using one of our [supported providers]/docs/v1/observability/tracing/overview#exporters).
 
 ### Agents
 
-With a [logger](/docs/observability/logging) enabled, you can view detailed outputs from your agents in the **Traces** section in Studio.
+With a [logger]/docs/v1/logging) enabled, you can view detailed outputs from your agents in the **Traces** section in Studio.
 
 ![observability agents](/img/mastra-cloud/mastra-cloud-observability-agents.jpg)
 
@@ -37,7 +37,7 @@ Tools passed to the agent during generation are standardized using `convertTools
 
 ### Workflows
 
-With a [logger](/docs/observability/logging) enabled, you can view detailed outputs from your workflows in the **Traces** section in Studio.
+With a [logger]/docs/v1/logging) enabled, you can view detailed outputs from your workflows in the **Traces** section in Studio.
 
 ![observability workflows](/img/mastra-cloud/mastra-cloud-observability-workflows.jpg)
 
@@ -47,5 +47,5 @@ Workflows are created using `createWorkflow`, which sets up steps, metadata, and
 
 ## Next steps
 
-- [Logging](/docs/observability/logging)
-- [Tracing](/docs/observability/ai-tracing/overview)
+- [Logging]/docs/v1/logging)
+- [Tracing]/docs/v1/observability/tracing/overview)

package/.docs/raw/mastra-cloud/overview.mdx

@@ -7,7 +7,7 @@ import { MastraCloudCallout } from "@site/src/components/MastraCloudCallout";
 
 # Mastra Cloud
 
-[Mastra Cloud](https://mastra.ai/cloud) is a platform for deploying, managing, monitoring, and debugging Mastra applications. When you [deploy](/docs/mastra-cloud/setting-up) your application, Mastra Cloud exposes your agents, tools, and workflows as REST API endpoints.
+[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.
 
 <MastraCloudCallout />
 
@@ -62,4 +62,4 @@ Mastra Cloud is purpose-built for Mastra agents, tools, and workflows. It handle
 
 ## Next steps
 
-- [Setting Up and Deploying](/docs/mastra-cloud/setting-up)
+- [Setting Up and Deploying](/docs/v1/mastra-cloud/setting-up)

package/.docs/raw/mastra-cloud/setting-up.mdx

@@ -18,7 +18,7 @@ This page explains how to set up a project on [Mastra Cloud](https://mastra.ai/c
 - A [Mastra Cloud](https://mastra.ai/cloud) account
 - A GitHub account / repository containing a Mastra application
 
-> See our [Getting started](/docs/getting-started/installation) guide to scaffold out a new Mastra project with sensible defaults.
+> See our [Getting started](/docs/v1/getting-started/installation) guide to scaffold out a new Mastra project with sensible defaults.
 
 ## Setup and Deploy process
 
@@ -73,7 +73,7 @@ Mastra Cloud automatically detects the right build settings, but you can customi
   - **Install command**: Runs pre-build to install project dependencies
   - **Project setup command**: Runs pre-build to prepare any external dependencies
   - **Port**: The network port the server will use
-  - **Store settings**: Use Mastra Cloud's built-in [LibSQLStore](/docs/server-db/storage) storage
+  - **Store settings**: Use Mastra Cloud's built-in [LibSQLStore](/docs/v1/server-db/storage) storage
 - **Deploy Project**: Starts the deployment process
 
 </StepItem>
@@ -98,8 +98,8 @@ Your project is now configured with automatic deployments which occur whenever y
 
 ## Testing your application
 
-After a successful deployment you can test your agents and workflows [Studio](/docs/mastra-cloud/dashboard#studio) in Mastra Cloud, or interact with them using our [Client SDK](/docs/server-db/mastra-client).
+After a successful deployment you can test your agents and workflows [Studio](/docs/v1/mastra-cloud/dashboard#studio) in Mastra Cloud, or interact with them using our [Client SDK](/docs/v1/server-db/mastra-client).
 
 ## Next steps
 
-- [Navigating the Dashboard](/docs/mastra-cloud/dashboard)
+- [Navigating the Dashboard](/docs/v1/mastra-cloud/dashboard)

package/.docs/raw/memory/conversation-history.mdx

@@ -13,6 +13,7 @@ You can increase this limit by passing the `lastMessages` parameter to the `Memo
 
 ```typescript {3-7} showLineNumbers
 export const testAgent = new Agent({
+  id: "test-agent",
   // ...
   memory: new Memory({
     options: {

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

@@ -24,6 +24,8 @@ import { Agent } from "@mastra/core/agent";
 import { openai } from "@ai-sdk/openai";
 
 const agent = new Agent({
+  id: "test-agent",
+  name: "Test Agent",
   model: openai("gpt-4o"),
   memory: new Memory({
     processors: [
@@ -103,9 +105,8 @@ const memoryWithMultipleProcessors = new Memory({
 You can create custom logic by extending the base `MemoryProcessor` class.
 
 ```typescript copy showLineNumbers {5-20,24-27}
-import { Memory } from "@mastra/memory";
-import { CoreMessage, MemoryProcessorOpts } from "@mastra/core";
-import { MemoryProcessor } from "@mastra/core/memory";
+import { Memory, MemoryProcessorOpts, MemoryProcessor } from "@mastra/memory";
+import { CoreMessage } from "@mastra/core/llm";
 
 class ConversationOnlyFilter extends MemoryProcessor {
   constructor() {

package/.docs/raw/memory/overview.mdx

@@ -22,12 +22,13 @@ npm install @mastra/core @mastra/memory @mastra/libsql
 Then add a storage adapter to the main Mastra instance. Any agent with memory enabled will use this shared storage to store and recall interactions.
 
 ```typescript {6-8} title="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 import { LibSQLStore } from "@mastra/libsql";
 
 export const mastra = new Mastra({
   // ...
   storage: new LibSQLStore({
+    id: 'mastra-storage',
     url: ":memory:",
   }),
 });
@@ -40,6 +41,7 @@ import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
 
 export const testAgent = new Agent({
+  id: "test-agent",
   // ...
   memory: new Memory(),
 });
@@ -61,13 +63,13 @@ Mastra combines all memory types into a single context window. If the total exce
 
 ## Scoping memory with threads and resources
 
-All memory types are [Thread-scoped](./working-memory#thread-scoped-memory-default) by default, meaning they apply only to a single conversation. [resource-scoped](./working-memory#resource-scoped-memory) configuration allows working memory and semantic recall to persist across all threads that use the same user or entity.
+All memory types are [resource-scoped](./working-memory#resource-scoped-memory-default) by default, meaning they persist across all conversations for the same user or entity. [Thread-scoped](./working-memory#thread-scoped-memory) configuration isolates memory to a single conversation thread.
 
 ## Memory Storage Adapters
 
 To persist and recall information between conversations, memory requires a storage adapter.
 
-Supported options include [LibSQL](/docs/memory/storage/memory-with-libsql), [MongoDB](/examples/memory/memory-with-mongodb), [Postgres](/docs/memory/storage/memory-with-pg), and [Upstash](/docs/memory/storage/memory-with-upstash)
+Supported options include [LibSQL](/docs/v1/memory/storage/memory-with-libsql), [MongoDB](/examples/v1/memory/memory-with-mongodb), [Postgres](/docs/v1/memory/storage/memory-with-pg), and [Upstash](/docs/v1/memory/storage/memory-with-upstash)
 
 We use LibSQL out of the box because it is file-based or in-memory, so it is easy to install and works well with Studio.
 
@@ -85,10 +87,12 @@ import { Agent } from "@mastra/core/agent";
 import { LibSQLStore } from "@mastra/libsql";
 
 export const testAgent = new Agent({
+  id: "test-agent",
   // ...
   memory: new Memory({
     // ...
     storage: new LibSQLStore({
+      id: 'test-agent-storage',
       url: "file:agent-memory.db",
     }),
     // ...
@@ -102,7 +106,7 @@ If tracing is enabled in your Mastra deployment and memory is configured either
 
 This is helpful for debugging, understanding agent decisions, and verifying that the agent is retrieving the right information for each request.
 
-For more details on enabling and configuring tracing, see [AI Tracing](../observability/ai-tracing/overview).
+For more details on enabling and configuring tracing, see [Tracing](../observability/tracing/overview).
 
 ## Local development with LibSQL
 
@@ -114,4 +118,4 @@ For local development with `LibSQLStore`, you can inspect stored memory using th
 
 Now that you understand the core concepts, continue to [semantic recall](./semantic-recall) to learn how to add RAG memory to your Mastra agents.
 
-Alternatively you can visit the [configuration reference](/reference/memory/memory-class) for available options.
+Alternatively you can visit the [configuration reference](/reference/v1/memory/memory-class) for available options.

package/.docs/raw/memory/semantic-recall.mdx

@@ -36,6 +36,7 @@ import { Memory } from "@mastra/memory";
 import { openai } from "@ai-sdk/openai";
 
 const agent = new Agent({
+  id: "support-agent",
   name: "SupportAgent",
   instructions: "You are a helpful support agent.",
   model: openai("gpt-4o"),
@@ -67,7 +68,7 @@ const agent = new Agent({
 
 ### Storage configuration
 
-Semantic recall relies on a [storage and vector db](/reference/memory/memory-class) to store messages and their embeddings.
+Semantic recall relies on a [storage and vector db](/reference/v1/memory/memory-class) to store messages and their embeddings.
 
 ```ts {8-17}
 import { Memory } from "@mastra/memory";
@@ -78,10 +79,12 @@ const agent = new Agent({
   memory: new Memory({
     // this is the default storage db if omitted
     storage: new LibSQLStore({
+      id: 'agent-storage',
       url: "file:./local.db",
     }),
     // this is the default vector db if omitted
     vector: new LibSQLVector({
+      id: 'agent-vector',
       connectionUrl: "file:./local.db",
     }),
   }),
@@ -90,14 +93,14 @@ const agent = new Agent({
 
 **Storage/vector code Examples**:
 
-- [LibSQL](/docs/memory/storage/memory-with-libsql)
-- [MongoDB](/examples/memory/memory-with-mongodb)
-- [Postgres](/docs/memory/storage/memory-with-pg)
-- [Upstash](/docs/memory/storage/memory-with-upstash)
+- [LibSQL](/docs/v1/memory/storage/memory-with-libsql)
+- [MongoDB](/examples/v1/memory/memory-with-mongodb)
+- [Postgres](/docs/v1/memory/storage/memory-with-pg)
+- [Upstash](/docs/v1/memory/storage/memory-with-upstash)
 
 ### Embedder configuration
 
-Semantic recall relies on an [embedding model](/reference/memory/memory-class) to convert messages into embeddings. Mastra supports embedding models through the model router using `provider/model` strings, or you can use any [embedding model](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings) compatible with the AI SDK.
+Semantic recall relies on an [embedding model](/reference/v1/memory/memory-class) to convert messages into embeddings. Mastra supports embedding models through the model router using `provider/model` strings, or you can use any [embedding model](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings) compatible with the AI SDK.
 
 #### Using the Model Router (Recommended)
 
@@ -175,9 +178,11 @@ import { PgStore, PgVector } from "@mastra/pg";
 const agent = new Agent({
   memory: new Memory({
     storage: new PgStore({
+      id: 'agent-storage',
       connectionString: process.env.DATABASE_URL,
     }),
     vector: new PgVector({
+      id: 'agent-vector',
       connectionString: process.env.DATABASE_URL,
     }),
     options: {
@@ -196,7 +201,7 @@ const agent = new Agent({
 });
 ```
 
-For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](/reference/vectors/pg#index-configuration-guide).
+For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](/reference/v1/vectors/pg#index-configuration-guide).
 
 ### Disabling
 

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

@@ -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
     },
   }),
 });
@@ -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

@@ -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
     },
   }),
 });
@@ -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

@@ -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
     },
   }),
 });
@@ -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