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

package/.docs/raw/guides/quickstarts/nextjs.mdx

@@ -0,0 +1,275 @@
+---
+title: "Next.js Quickstart"
+description: "Get started with Mastra, Next.js, and AS SDK UI. Quickly."
+---
+
+# Next.js Quickstart
+
+In this quickstart, you'll build an AI agent with tool-calling capabilities using [Mastra](/docs/v1), then connect it to Next.js by importing and calling the agent directly within your routes. 
+
+You'll use [AI SDK UI](https://ai-sdk.dev/docs/ai-sdk-ui/overview) and [AI Elements](https://ai-sdk.dev/elements) to create a beautiful, interactive chat experience. 
+
+In ~5 minutes, you'll have a functional AI-powered app ready to extend with your own tools and logic.
+
+<figure>
+![Screenshot of a chat-style web app displaying a completed "weatherTool" tool call, answering "What is the weather in London?" with a JSON result. A message suggests offering activity ideas, and a text input field is at the bottom.](/img/nextjs-quickstart.png)
+<figcaption class="text-sm text-center">What you'll build: an agent that can call a weather tool, display the JSON result, stream a weather summary in the chat UI, and persist conversation history across reloads.</figcaption>
+</figure>
+
+## Before you begin
+
+* You'll need an API key from a supported [model provider](/models/v1). If you don't have a preference, use [OpenAI](https://platform.openai.com/api-keys).
+
+## Create a new Next.js app
+
+Run the following command to [create a new Next.js app](https://nextjs.org/docs/app/getting-started/installation):
+
+```bash
+npx create-next-app \
+    my-nextjs-agent \
+    --yes \
+    --ts \
+    --eslint \
+    --tailwind \
+    --src-dir \
+    --app \
+    --turbopack \
+    --no-react-compiler \
+    --no-import-alias
+```
+
+This creates a project called `my-nextjs-agent`, but you can replace it with any name you want.
+
+## Initialize Mastra
+`cd` and run [`mastra init`](/reference/v1/cli/create-mastra). 
+
+When prompted, choose a provider (e.g. OpenAI) and enter your key:
+
+```bash
+cd my-nextjs-agent
+npx --force mastra@beta init
+```
+This creates a `src/mastra` folder with an example weather agent and the following files:
+
+-	`index.ts` - Mastra config, including memory
+- `tools/weather-tool.ts` - a tool to fetch weather for a given location
+-	`agents/weather-agent.ts`- a weather agent with a prompt that uses the tool
+
+You'll call `weather-agent.ts` from your Next.js routes in the next steps.
+
+
+## Install AI SDK UI and AI Elements
+
+Install AI SDK UI along with the Mastra adapter:
+
+```bash
+npm install \
+    @mastra/ai-sdk \
+    @ai-sdk/react 
+```
+
+Next, initialize AI Elements. When prompted, choose the default options:
+
+```bash
+npx ai-elements@latest
+```
+
+This downloads the entire AI Elements UI component library into a `@/components/ai-elements` folder.
+
+
+## Create a chat route
+
+Create `src/app/api/chat/route.ts`:
+
+```ts title="src/app/api/chat/route.ts"
+import { mastra } from "@/mastra";
+import { NextResponse } from "next/server";
+import { toAISdkFormat } from "@mastra/ai-sdk";
+import { convertMessages } from "@mastra/core/agent";
+import { createUIMessageStreamResponse } from "ai";
+
+const weatherAgent = mastra.getAgent("weatherAgent");
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const stream = await weatherAgent.stream(messages, {
+    memory: {
+      thread: "example-user-id",
+      resource: "weather-chat",
+    },
+  });
+
+  return createUIMessageStreamResponse({
+    stream: toAISdkFormat(stream, { from: "agent" }),
+  })
+}
+
+export async function GET() {
+  const memory = await weatherAgent.getMemory();
+  const response = await memory?.query({
+    threadId: "example-user-id",
+    resourceId: "weather-chat",
+  });
+
+  const uiMessages = 
+    convertMessages(response?.uiMessages ?? []).to("AIV5.UI");
+  return NextResponse.json(uiMessages);
+}
+```
+
+The POST route accepts a prompt and streams the agent's response back in AI SDK format, while the GET route fetches message history from memory so the UI can be hydrated when the client reloads.
+
+## Create a chat page
+
+Create `src/app/chat/page.tsx`:
+
+```tsx title="src/app/chat/page.tsx"
+'use client';
+
+import '@/app/globals.css';
+import { useEffect, useState } from 'react';
+import { DefaultChatTransport } from 'ai';
+import { useChat } from '@ai-sdk/react';
+
+import {
+  PromptInput,
+  PromptInputBody,
+  PromptInputTextarea,
+} from '@/components/ai-elements/prompt-input';
+
+import {
+  Conversation,
+  ConversationContent,
+  ConversationScrollButton,
+} from '@/components/ai-elements/conversation';
+
+import { Message, MessageContent, MessageResponse } from '@/components/ai-elements/message';
+
+import {
+  Tool,
+  ToolHeader,
+  ToolContent,
+  ToolInput,
+  ToolOutput,
+} from '@/components/ai-elements/tool';
+
+
+function Chat() {
+  const [input, setInput] = useState<string>('');
+
+  const { messages, setMessages, sendMessage, status } = useChat({
+    transport: new DefaultChatTransport({
+      api: '/api/chat',
+    }),
+  });
+
+  useEffect(() => {
+    const fetchMessages = async () => {
+      const res = await fetch('/api/chat');
+      const data = await res.json();
+      setMessages([...data]);
+    };
+    fetchMessages();
+  }, [setMessages]);
+
+  const handleSubmit = async () => {
+    if (!input.trim()) return;
+
+    sendMessage({ text: input });
+    setInput('');
+  };
+
+  return (
+    <div className="w-full p-6 relative size-full h-screen">
+      <div className="flex flex-col h-full">
+        <Conversation className="h-full">
+          <ConversationContent>
+            {messages.map((message: any) => (
+              <div key={message.id}>
+                {message.parts?.map((part: any, i: number) => {
+                  if (part.type === 'text') {
+                    return (
+                      <Message 
+                        key={`${message.id}-${i}`} 
+                        from={message.role}>
+                          <MessageContent>
+                            <MessageResponse>{part.text}</MessageResponse>
+                          </MessageContent>
+                      </Message>
+                    );
+                  }
+
+                  if (part.type?.startsWith('tool-')) {
+                    return (
+                      <Tool key={`${message.id}-${i}`}>
+                        <ToolHeader
+                          type={part.type}
+                          state={part.state || 'output-available'}
+                          className="cursor-pointer"
+                        />
+                        <ToolContent>
+                          <ToolInput input={part.input || part.args || {}} />
+                          <ToolOutput
+                            output={part.output || part.result}
+                            errorText={part.errorText || part.error}
+                          />
+                        </ToolContent>
+                      </Tool>
+                    );
+                  }
+
+                  return null;
+                })}
+              </div>
+            ))}
+            <ConversationScrollButton />
+          </ConversationContent>
+        </Conversation>
+
+        <PromptInput onSubmit={handleSubmit} className="mt-20">
+          <PromptInputBody>
+            <PromptInputTextarea
+              onChange={(e: any) => setInput(e.target.value)}
+              className="md:leading-10"
+              value={input}
+              placeholder="Type your message..."
+              disabled={status !== 'ready'}
+            />
+          </PromptInputBody>
+        </PromptInput>
+      </div>
+    </div>
+  );
+}
+
+export default Chat;
+```
+
+This component connects [`useChat()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) to the `api/chat` endpoint, sending prompts there and streaming the response back in chunks.
+
+It renders the response text using the [`<MessageResponse>`](https://ai-sdk.dev/elements/components/message#messageresponse-) component, and shows any tool invocations with the [`<Tool>`](https://ai-sdk.dev/elements/components/tool) component.
+
+
+## Test your agent 
+1. Run your Next.js app with `npm run dev`
+
+2. Open the chat at http://localhost:3000/chat
+
+3. Try asking about the weather. If your API key is set up correctly, you'll get a response.
+
+## Next steps
+
+Congratulations on building your Mastra agent with Next.js! 🎉 
+
+From here, you can extend the project with your own tools and logic:
+
+- Learn more about [agents](/docs/v1/agents/overview)
+- Give your agent its own [tools](/docs/v1/agents/using-tools)
+- Add human-like [memory](/docs/v1/agents/agent-memory) to your agent
+
+When you're ready, read more about how Mastra integrates with AI SDK and Next.js, and how to deploy to Vercel:
+
+- Integrate Mastra with [AI SDK](/docs/v1/frameworks/agentic-uis/ai-sdk)
+- Use Mastra in your [Next.js app](/docs/v1/frameworks/web-frameworks/next-js)
+- Deploy your agent to [Vercel](/docs/v1/deployment/serverless-platforms/vercel-deployer)

package/.docs/raw/index.mdx

@@ -9,7 +9,7 @@ import YouTube from "@site/src/components/YouTube-player";
 
 # About Mastra
 
-From the team behind Gatsby, Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.
+Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.
 
 It includes everything you need to go from early prototypes to production-ready applications. Mastra integrates with frontend and backend frameworks like React, Next.js, and Node, or you can deploy it anywhere as a standalone server. It's the easiest way to build, tune, and scale reliable AI products.
 
@@ -21,19 +21,19 @@ Purpose-built for TypeScript and designed around established AI patterns, Mastra
 
 Some highlights include:
 
-- [**Model routing**](/models) - Connect to 40+ providers through one standard interface. Use models from OpenAI, Anthropic, Gemini, and more.
+- [**Model routing**](/models/v1) - Connect to 40+ providers through one standard interface. Use models from OpenAI, Anthropic, Gemini, and more.
 
-- [**Agents**](/docs/agents/overview) - Build autonomous agents that use LLMs and tools to solve open-ended tasks. Agents reason about goals, decide which tools to use, and iterate internally until the model emits a final answer or an optional stopping condition is met.
+- [**Agents**](/docs/v1/agents/overview) - Build autonomous agents that use LLMs and tools to solve open-ended tasks. Agents reason about goals, decide which tools to use, and iterate internally until the model emits a final answer or an optional stopping condition is met.
 
-- [**Workflows**](/docs/workflows/overview) - When you need explicit control over execution, use Mastra's graph-based workflow engine to orchestrate complex multi-step processes. Mastra workflows use an intuitive syntax for control flow (`.then()`, `.branch()`, `.parallel()`).
+- [**Workflows**](/docs/v1/workflows/overview) - When you need explicit control over execution, use Mastra's graph-based workflow engine to orchestrate complex multi-step processes. Mastra workflows use an intuitive syntax for control flow (`.then()`, `.branch()`, `.parallel()`).
 
-- [**Human-in-the-loop**](/docs/workflows/suspend-and-resume) - Suspend an agent or workflow and await user input or approval before resuming. Mastra uses [storage](/docs/server-db/storage) to remember execution state, so you can pause indefinitely and resume where you left off.
+- [**Human-in-the-loop**](/docs/v1/workflows/suspend-and-resume) - Suspend an agent or workflow and await user input or approval before resuming. Mastra uses [storage](/docs/v1/server-db/storage) to remember execution state, so you can pause indefinitely and resume where you left off.
 
-- **Context management** - Give your agents the right context at the right time. Provide [conversation history](/docs/memory/conversation-history), [retrieve](/docs/rag/overview) data from your sources (APIs, databases, files), and add human-like [working](/docs/memory/working-memory) and [semantic](/docs/memory/semantic-recall) memory so your agents behave coherently.
+- **Context management** - Give your agents the right context at the right time. Provide [conversation history](/docs/v1/memory/conversation-history), [retrieve](/docs/v1/rag/overview) data from your sources (APIs, databases, files), and add human-like [working](/docs/v1/memory/working-memory) and [semantic](/docs/v1/memory/semantic-recall) memory so your agents behave coherently.
 
 - **Integrations** - Bundle agents and workflows into existing React, Next.js, or Node.js apps, or ship them as standalone endpoints. When building UIs, integrate with agentic libraries like Vercel's AI SDK UI and CopilotKit to bring your AI assistant to life on the web.
 
-- **Production essentials** - Shipping reliable agents takes ongoing insight, evaluation, and iteration. With built-in [scorers](/docs/scorers/overview) and [observability](/docs/observability/overview), Mastra gives you the tools to observe, measure, and refine continuously.
+- **Production essentials** - Shipping reliable agents takes ongoing insight, evaluation, and iteration. With built-in [scorers](/docs/v1/evals/overview) and [observability](/docs/v1/observability/overview), Mastra gives you the tools to observe, measure, and refine continuously.
 
 ## What can you build?
 
@@ -51,8 +51,8 @@ Explore real-world examples in our [community showcase](/showcase).
 
 ## Get started
 
-Follow the [Installation guide](/docs/getting-started/installation) for step-by-step setup with the CLI or a manual install.
+Follow the [Installation guide](/docs/v1/getting-started/installation) for step-by-step setup with the CLI or a manual install.
 
-If you're new to AI agents, check out our [templates](/docs/getting-started/templates), [course](https://mastra.ai/book), and [YouTube videos](https://youtube.com/@mastra-ai) to start building with Mastra today.
+If you're new to AI agents, check out our [templates](/docs/v1/getting-started/templates), [course](https://mastra.ai/book), and [YouTube videos](https://youtube.com/@mastra-ai) to start building with Mastra today.
 
 We can't wait to see what you build ✌️

package/.docs/raw/{observability/logging.mdx → logging.mdx}

@@ -7,14 +7,14 @@ description: Learn how to use logging in Mastra to monitor execution, capture ap
 
 Mastra's logging system captures function execution, input data, and output responses in a structured format.
 
-When deploying to Mastra Cloud, logs are shown on the [Logs](../mastra-cloud/observability) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
+When deploying to Mastra Cloud, logs are shown on the [Logs](/docs/v1/mastra-cloud/observability) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
 
 ## PinoLogger
 
-When [initializing a new Mastra project](../getting-started/installation) using the CLI, `PinoLogger` is included by default.
+When [initializing a new Mastra project](/docs/v1/getting-started/installation) using the CLI, `PinoLogger` is included by default.
 
 ```typescript title="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 import { PinoLogger } from "@mastra/loggers";
 
 export const mastra = new Mastra({
@@ -26,7 +26,7 @@ export const mastra = new Mastra({
 });
 ```
 
-> See the [PinoLogger](/reference/observability/logging/pino-logger) API reference for all available configuration options.
+> See the [PinoLogger](/reference/v1/logging/pino-logger) API reference for all available configuration options.
 
 ## Logging from workflows and tools
 

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

@@ -7,7 +7,7 @@ import { MastraCloudCallout } from "@site/src/components/MastraCloudCallout";
 
 # Navigating the Dashboard
 
-This page explains how to navigate the Mastra Cloud dashboard, where you can configure your project, view deployment details, and interact with agents and workflows using the built-in [Studio](/docs/mastra-cloud/dashboard#studio).
+This page explains how to navigate the Mastra Cloud dashboard, where you can configure your project, view deployment details, and interact with agents and workflows using the built-in [Studio](/docs/v1/mastra-cloud/dashboard#studio).
 
 <MastraCloudCallout />
 
@@ -97,4 +97,4 @@ Each MCP Server includes API endpoints for HTTP and SSE, along with IDE configur
 
 ## Next steps
 
-- [Understanding Tracing and Logs](/docs/mastra-cloud/observability)
+- [Understanding Tracing and Logs](/docs/v1/mastra-cloud/observability)

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

@@ -16,18 +16,19 @@ Mastra's memory system uses [storage providers](#memory-storage-adapters) to per
 First install the required dependencies:
 
 ```bash copy
-npm install @mastra/core @mastra/memory @mastra/libsql
+npm install @mastra/core@beta @mastra/memory@beta @mastra/libsql@beta
 ```
 
 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)
 
@@ -144,7 +147,7 @@ const agent = new Agent({
 To use FastEmbed (a local embedding model), install `@mastra/fastembed`:
 
 ```bash npm2yarn copy
-npm install @mastra/fastembed
+npm install @mastra/fastembed@beta
 ```
 
 Then configure it in your memory:
@@ -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