@mastra/mcp-docs-server 1.0.0-beta.10 → 1.0.0-beta.13

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

@@ -5,6 +5,12 @@ description: "Overview of breaking changes when upgrading to Mastra v1."
 
 # Upgrade to Mastra v1
 
+:::info[First update to latest 0.x version]
+Before upgrading to v1, make sure you've updated to the latest 0.x version of Mastra. Follow the [upgrade to latest 0.x guide](https://mastra.ai/guides/migrations/upgrade-to-latest-0x) first, then return here to complete the v1 migration.
+:::
+
+Mastra v1 is coming in January 2026. We recommend starting any new projects with the beta, or upgrading your existing project today to get ahead.
+
 This guide provides a comprehensive overview of breaking changes when upgrading from Mastra 0.x to v1.0. The migration is organized by package and feature area to help you systematically update your codebase.
 
 :::tip[Need help?]

package/.docs/raw/index.mdx

@@ -27,7 +27,7 @@ Some highlights include:
 
 - [**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/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.
+- [**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/memory/storage/overview) 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/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.
 

package/.docs/raw/{deployment/mastra-cloud → mastra-cloud}/dashboard.mdx

@@ -3,13 +3,9 @@ title: "Navigating the Dashboard | Mastra Cloud"
 description: Details of each feature available in Mastra Cloud
 ---
 
-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/v1/deployment/mastra-cloud/dashboard#studio).
-
-<MastraCloudCallout />
+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).
 
 ## Overview
 
@@ -97,4 +93,4 @@ Each MCP Server includes API endpoints for HTTP and SSE, along with IDE configur
 
 ## Next steps
 
-- [Understanding Tracing and Logs](/docs/v1/deployment/mastra-cloud/observability)
+- [Understanding Tracing and Logs](/docs/v1/mastra-cloud/observability)

package/.docs/raw/{deployment/mastra-cloud → mastra-cloud}/observability.mdx

@@ -3,16 +3,12 @@ title: "Understanding Tracing and Logs | Mastra Cloud"
 description: Monitoring and debugging tools for Mastra Cloud deployments
 ---
 
-import { MastraCloudCallout } from "@site/src/components/MastraCloudCallout";
-
 # Understanding Tracing and Logs
 
 Mastra Cloud provides full observability for production applications, giving you insight into how your agents and workflows behave. Observability can be enabled whether your application is deployed to Mastra Cloud, running locally, or hosted on your own infrastructure. Any Mastra project can send traces and logs to the platform regardless of where it's running.
 
 For details on configuring observability, see the [Cloud Exporter](/docs/v1/observability/tracing/exporters/cloud) docs.
 
-<MastraCloudCallout />
-
 ## Traces
 
 More detailed traces are available for both agents and workflows by enabling [observability](/docs/v1/observability/tracing/overview) using one of our [supported providers](/docs/v1/observability/tracing/overview#exporters).
@@ -39,7 +35,7 @@ Workflow traces capture each step in the run, including transitions, branching,
 
 ## Logs
 
-You can view detailed logs for debugging and monitoring your application's behavior on the [Logs](/docs/v1/deployment/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)
 

package/.docs/raw/{deployment/mastra-cloud → mastra-cloud}/overview.mdx

@@ -3,13 +3,9 @@ title: "Mastra Cloud | Mastra Cloud"
 description: Deployment and monitoring service for Mastra applications
 ---
 
-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/v1/deployment/mastra-cloud/setting-up) your application, Mastra Cloud exposes your agents, tools, and workflows as REST API endpoints.
-
-<MastraCloudCallout />
+[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.
 
 ## Platform features
 
@@ -62,4 +58,4 @@ Mastra Cloud is purpose-built for Mastra agents, tools, and workflows. It handle
 
 ## Next steps
 
-- [Setting Up and Deploying](/docs/v1/deployment/mastra-cloud/setting-up)
+- [Setting Up and Deploying](/docs/v1/mastra-cloud/setting-up)

package/.docs/raw/{deployment/mastra-cloud → mastra-cloud}/setting-up.mdx

@@ -3,7 +3,6 @@ title: "Setting Up and Deploying | Mastra Cloud"
 description: Configuration steps for Mastra Cloud projects
 ---
 
-import { MastraCloudCallout } from "@site/src/components/MastraCloudCallout";
 import Steps from "@site/src/components/Steps";
 import StepItem from "@site/src/components/StepItem";
 
@@ -11,8 +10,6 @@ import StepItem from "@site/src/components/StepItem";
 
 This page explains how to set up a project on [Mastra Cloud](https://mastra.ai/cloud) with automatic deployments using our GitHub integration.
 
-<MastraCloudCallout />
-
 ## Prerequisites
 
 - A [Mastra Cloud](https://mastra.ai/cloud) account
@@ -73,7 +70,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/v1/server-db/storage) storage
+  - **Store settings**: Use Mastra Cloud's built-in [LibSQLStore](/docs/v1/memory/storage/overview) storage
 - **Deploy Project**: Starts the deployment process
 
 </StepItem>
@@ -98,8 +95,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/v1/deployment/mastra-cloud/dashboard#studio) in Mastra Cloud, or interact with them using our [Client SDK](/docs/v1/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/mastra-client).
 
 ## Next steps
 
-- [Navigating the Dashboard](/docs/v1/deployment/mastra-cloud/dashboard)
+- [Navigating the Dashboard](/docs/v1/mastra-cloud/dashboard)

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

@@ -3,7 +3,7 @@ title: "Memory overview | Memory"
 description: "Learn how Mastra's memory system works with working memory, conversation history, and semantic recall."
 ---
 
-# Memory overview
+# Memory Overview
 
 Memory in Mastra helps agents manage context across conversations by condensing relevant information into the language model's context window.
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Memory with LibSQL | Memory"
+title: "Memory with LibSQL | Storage"
 description: Example for how to use Mastra's memory system with LibSQL storage and vector database backend.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Example: Memory with MongoDB | Memory"
+title: "Example: Memory with MongoDB | Storage"
 description: Example for how to use Mastra's memory system with MongoDB storage and vector capabilities.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Memory with Postgres | Memory"
+title: "Memory with Postgres | Storage"
 description: Example for how to use Mastra's memory system with PostgreSQL storage and vector capabilities.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Memory with Upstash | Memory"
+title: "Memory with Upstash | Storage"
 description: Example for how to use Mastra's memory system with Upstash Redis storage and vector capabilities.
 ---
 

package/.docs/raw/{server-db/storage.mdx → memory/storage/overview.mdx}

@@ -1,5 +1,5 @@
 ---
-title: "MastraStorage | Server & DB"
+title: "MastraStorage | Storage"
 description: Overview of Mastra's storage system and data persistence capabilities.
 ---
 
@@ -9,7 +9,7 @@ import { StorageOverviewImage } from "@site/src/components/StorageOverviewImage"
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-# MastraStorage
+# Storage Overview
 
 `MastraStorage` provides a unified interface for managing:
 

package/.docs/raw/observability/logging.mdx

@@ -7,7 +7,7 @@ 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](/docs/v1/deployment/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.
 
 ## Configuring logs with PinoLogger
 

package/.docs/raw/observability/tracing/exporters/cloud.mdx

@@ -112,4 +112,4 @@ CloudExporter uses intelligent batching to optimize network usage. Traces are bu
 
 - [Tracing Overview](/docs/v1/observability/tracing/overview)
 - [DefaultExporter](/docs/v1/observability/tracing/exporters/default)
-- [Mastra Cloud Documentation](/docs/v1/deployment/mastra-cloud/overview)
+- [Mastra Cloud Documentation](/docs/v1/mastra-cloud/overview)

package/.docs/raw/observability/tracing/exporters/default.mdx

@@ -160,4 +160,4 @@ new DefaultExporter({
 
 - [Tracing Overview](/docs/v1/observability/tracing/overview)
 - [CloudExporter](/docs/v1/observability/tracing/exporters/cloud)
-- [Storage Configuration](/docs/v1/server-db/storage)
+- [Storage Configuration](/docs/v1/memory/storage/overview)

package/.docs/raw/rag/chunking-and-embedding.mdx

@@ -28,7 +28,9 @@ Use `chunk` to split documents into manageable pieces. Mastra supports multiple
 - `latex`: LaTeX structure-aware splitting
 - `sentence`: Sentence-aware splitting
 
-**Note:** Each strategy accepts different parameters optimized for its chunking approach.
+:::note
+Each strategy accepts different parameters optimized for its chunking approach.
+:::
 
 Here's an example of how to use the `recursive` strategy:
 
@@ -67,15 +69,17 @@ const chunks = await doc.chunk({
 });
 ```
 
-**Note:** Metadata extraction may use LLM calls, so ensure your API key is set.
+:::note
+Metadata extraction may use LLM calls, so ensure your API key is set.
+:::
 
-We go deeper into chunking strategies in our [chunk documentation](/reference/v1/rag/chunk).
+We go deeper into chunking strategies in our [`chunk()` reference documentation](/reference/v1/rag/chunk).
 
 ## Step 2: Embedding Generation
 
-Transform chunks into embeddings using your preferred provider. Mastra supports embedding models through the model router or AI SDK packages.
+Transform chunks into embeddings using your preferred provider. Mastra supports embedding models through the model router.
 
-### Using the Model Router (Recommended)
+### Using the Model Router
 
 The simplest way is to use Mastra's model router with `provider/model` strings:
 
@@ -89,27 +93,10 @@ const { embeddings } = await embedMany({
 });
 ```
 
-Supported embedding models:
-
-- **OpenAI**: `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`
-- **Google**: `gemini-embedding-001`, `text-embedding-004`
+Mastra supports OpenAI and Google embedding models. For a complete list of supported embedding models, see the [embeddings reference](/reference/v1/rag/embeddings).
 
 The model router automatically handles API key detection from environment variables.
 
-### Using AI SDK Packages
-
-You can also use AI SDK embedding models directly:
-
-```ts showLineNumbers copy
-import { embedMany } from "ai";
-import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
-
-const { embeddings } = await embedMany({
-  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
-  values: chunks.map((chunk) => chunk.text),
-});
-```
-
 The embedding functions return vectors, arrays of numbers representing the semantic meaning of your text, ready for similarity searches in your vector database.
 
 ### Configuring Embedding Dimensions
@@ -147,9 +134,9 @@ const { embeddings } = await embedMany({
 });
 ```
 
-### Vector Database Compatibility
-
+:::important[Vector Database Compatibility]
 When storing embeddings, the vector database index must be configured to match the output size of your embedding model. If the dimensions do not match, you may get errors or data corruption.
+:::
 
 ## Example: Complete Pipeline
 

package/.docs/raw/rag/graph-rag.mdx

@@ -0,0 +1,220 @@
+---
+title: "GraphRAG | RAG"
+description: Guide on graph-based retrieval in Mastra's RAG systems for documents with complex relationships.
+---
+
+# GraphRAG
+
+Graph-based retrieval enhances traditional vector search by following relationships between chunks of information. This approach is useful when information is spread across multiple documents or when documents reference each other.
+
+## When to use GraphRAG
+
+GraphRAG is particularly effective when:
+
+- Information is spread across multiple documents
+- Documents reference each other
+- You need to traverse relationships to find complete answers
+- Understanding connections between concepts is important
+- Simple vector similarity misses important contextual relationships
+
+For straightforward semantic search without relationship traversal, use [standard retrieval methods](/docs/v1/rag/retrieval).
+
+## How GraphRAG works
+
+GraphRAG combines vector similarity with knowledge graph traversal:
+
+1. Initial vector search retrieves relevant chunks based on semantic similarity
+2. A knowledge graph is constructed from the retrieved chunks
+3. The graph is traversed to find connected information
+4. Results include both directly relevant chunks and related content
+
+This process helps surface information that might not be semantically similar to the query but is contextually relevant through connections.
+
+## Creating a graph query tool
+
+The Graph Query Tool provides agents with the ability to perform graph-based retrieval:
+
+```ts showLineNumbers copy
+import { createGraphRAGTool } from "@mastra/rag";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+
+const graphQueryTool = createGraphRAGTool({
+  vectorStoreName: "pgVector",
+  indexName: "embeddings",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  graphOptions: {
+    threshold: 0.7,
+  },
+});
+```
+
+### Configuration options
+
+The `graphOptions` parameter controls how the knowledge graph is built and traversed:
+
+- `threshold`: Similarity threshold (0-1) for determining which chunks are related. Higher values create sparser graphs with stronger connections; lower values create denser graphs with more potential relationships.
+- `dimension`: Vector embedding dimension. Must match the embedding model's output dimension (e.g., 1536 for OpenAI's text-embedding-3-small).
+
+```ts showLineNumbers copy
+const graphQueryTool = createGraphRAGTool({
+  vectorStoreName: "pgVector",
+  indexName: "embeddings",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  graphOptions: {
+    dimension: 1536,
+    threshold: 0.7,
+  },
+});
+```
+
+## Using GraphRAG with agents
+
+Integrate the graph query tool with an agent to enable graph-based retrieval:
+
+```ts showLineNumbers copy
+import { Agent } from "@mastra/core/agent";
+
+const ragAgent = new Agent({
+  id: "rag-agent",
+  name: "GraphRAG Agent",
+  instructions: `You are a helpful assistant that answers questions based on the provided context.
+When answering questions, use the graph query tool to find relevant information and relationships.
+Base your answers on the context provided by the tool, and clearly state if the context doesn't contain enough information.`,
+  model: "openai/gpt-5.1",
+  tools: {
+    graphQueryTool,
+  },
+});
+```
+
+## Document processing and storage
+
+Before using graph-based retrieval, process documents into chunks and store their embeddings:
+
+```ts showLineNumbers copy
+import { MDocument } from "@mastra/rag";
+import { embedMany } from "ai";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+
+// Create and chunk document
+const doc = MDocument.fromText("Your document content here...");
+
+const chunks = await doc.chunk({
+  strategy: "recursive",
+  size: 512,
+  overlap: 50,
+  separator: "\n",
+});
+
+// Generate embeddings
+const { embeddings } = await embedMany({
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  values: chunks.map((chunk) => chunk.text),
+});
+
+// Store in vector database
+const vectorStore = mastra.getVector("pgVector");
+await vectorStore.createIndex({
+  indexName: "embeddings",
+  dimension: 1536,
+});
+await vectorStore.upsert({
+  indexName: "embeddings",
+  vectors: embeddings,
+  metadata: chunks?.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+## Querying with GraphRAG
+
+Once configured, the agent can perform graph-based queries:
+
+```ts showLineNumbers copy
+const query = "What are the effects of infrastructure changes on local businesses?";
+const response = await ragAgent.generate(query);
+console.log(response.text);
+```
+
+The agent uses the graph query tool to:
+
+1. Convert the query to an embedding
+2. Find semantically similar chunks in the vector store
+3. Build a knowledge graph from related chunks
+4. Traverse the graph to find connected information
+5. Return comprehensive context for generating the response
+
+## Choosing the right threshold
+
+The threshold parameter significantly impacts retrieval quality:
+
+- **High threshold (0.8-0.9)**: Strict connections, fewer relationships, more precise but potentially incomplete results
+- **Medium threshold (0.6-0.8)**: Balanced approach, good for most use cases
+- **Low threshold (0.4-0.6)**: More connections, broader context, risk of including less relevant information
+
+Start with 0.7 and adjust based on your specific use case:
+
+```ts showLineNumbers copy
+// Strict connections for precise answers
+const strictGraphTool = createGraphRAGTool({
+  vectorStoreName: "pgVector",
+  indexName: "embeddings",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  graphOptions: {
+    threshold: 0.85,
+  },
+});
+
+// Broader connections for exploratory queries
+const broadGraphTool = createGraphRAGTool({
+  vectorStoreName: "pgVector",
+  indexName: "embeddings",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  graphOptions: {
+    threshold: 0.5,
+  },
+});
+```
+
+## Combining with other retrieval methods
+
+GraphRAG can be used alongside other retrieval approaches:
+
+```ts showLineNumbers copy
+import { createVectorQueryTool } from "@mastra/rag";
+
+const vectorQueryTool = createVectorQueryTool({
+  vectorStoreName: "pgVector",
+  indexName: "embeddings",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+});
+
+const graphQueryTool = createGraphRAGTool({
+  vectorStoreName: "pgVector",
+  indexName: "embeddings",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  graphOptions: {
+    threshold: 0.7,
+  },
+});
+
+const agent = new Agent({
+  id: "rag-agent",
+  name: "RAG Agent",
+  instructions: `Use vector search for simple fact-finding queries.
+Use graph search when you need to understand relationships or find connected information.`,
+  model: "openai/gpt-5.1",
+  tools: {
+    vectorQueryTool,
+    graphQueryTool,
+  },
+});
+```
+
+This gives the agent flexibility to choose the appropriate retrieval method based on the query.
+
+## Reference
+
+For detailed API documentation, see:
+
+- [GraphRAG Class](/reference/v1/rag/graph-rag)
+- [createGraphRAGTool()](/reference/v1/tools/graph-rag-tool)

package/.docs/raw/rag/overview.mdx

@@ -74,5 +74,4 @@ Mastra supports multiple vector stores for embedding persistence and similarity
 
 ## More resources
 
-- [Chain of Thought RAG Example](/examples/v1/rag/usage/cot-rag)
-- [All RAG Examples](/examples/v1/) (including different chunking strategies, embedding models, and vector stores)
+- [Chain of Thought RAG Example](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/cot-rag)

package/.docs/raw/rag/retrieval.mdx

@@ -76,7 +76,9 @@ Results include both the text content and a similarity score:
 
 ### Metadata Filtering
 
-Filter results based on metadata fields to narrow down the search space. This is useful when you have documents from different sources, time periods, or with specific attributes. Mastra provides a unified MongoDB-style query syntax that works across all supported vector stores.
+Filter results based on metadata fields to narrow down the search space. This approach - combining vector similarity search with metadata filters - is sometimes called hybrid vector search, as it merges semantic search with structured filtering criteria.
+
+This is useful when you have documents from different sources, time periods, or with specific attributes. Mastra provides a unified MongoDB-style query syntax that works across all supported vector stores.
 
 For detailed information about available operators and syntax, see the [Metadata Filters Reference](/reference/v1/rag/metadata-filters).
 
@@ -146,13 +148,14 @@ Common use cases for metadata filtering:
 - Combine multiple conditions for precise querying
 - Filter by document attributes (e.g., language, author)
 
-For an example of how to use metadata filtering, see the [Hybrid Vector Search](/examples/v1/rag/query/hybrid-vector-search) example.
-
 ### Vector Query Tool
 
 Sometimes you want to give your agent the ability to query a vector database directly. The Vector Query Tool allows your agent to be in charge of retrieval decisions, combining semantic search with optional filtering and reranking based on the agent's understanding of the user's needs.
 
 ```ts showLineNumbers copy
+import { createVectorQueryTool } from "@mastra/rag";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+
 const vectorQueryTool = createVectorQueryTool({
   vectorStoreName: "pgVector",
   indexName: "embeddings",
@@ -180,6 +183,9 @@ Connection credentials (URLs, auth tokens) are configured when you instantiate t
 :::
 
 ```ts showLineNumbers copy
+import { createVectorQueryTool } from "@mastra/rag";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
+
 // Pinecone with namespace
 const pineconeQueryTool = createVectorQueryTool({
   vectorStoreName: "pinecone",
@@ -535,8 +541,9 @@ The weights control how different factors influence the final ranking:
 - `vector`: Higher values favor the original vector similarity scores
 - `position`: Higher values help maintain the original ordering of results
 
-
-> **Note:** For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
+:::note
+For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
+:::
 
 You can also use other relevance score providers like Cohere or ZeroEntropy:
 
@@ -552,27 +559,4 @@ The re-ranked results combine vector similarity with semantic understanding to i
 
 For more details about re-ranking, see the [rerank()](/reference/v1/rag/rerankWithScorer) method.
 
-### Graph-based Retrieval
-
-For documents with complex relationships, graph-based retrieval can follow connections between chunks. This helps when:
-
-- Information is spread across multiple documents
-- Documents reference each other
-- You need to traverse relationships to find complete answers
-
-Example setup:
-
-```ts showLineNumbers copy
-const graphQueryTool = createGraphQueryTool({
-  vectorStoreName: "pgVector",
-  indexName: "embeddings",
-  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
-  graphOptions: {
-    threshold: 0.7,
-  },
-});
-```
-
-For more details about graph-based retrieval, see the [GraphRAG](/reference/v1/rag/graph-rag) class and the [createGraphQueryTool()](/reference/v1/tools/graph-rag-tool) function.
-
-For an example of how to use the graph-based retrieval method, see the [Graph-based Retrieval](/examples/v1/rag/usage/graph-rag) example.
+For graph-based retrieval that follows connections between chunks, see the [GraphRAG](/docs/v1/rag/graph-rag) documentation.

package/.docs/raw/rag/vector-databases.mdx

@@ -380,9 +380,11 @@ The dimension size must match the output dimension of your chosen embedding mode
 
 - OpenAI text-embedding-3-small: 1536 dimensions (or custom, e.g., 256)
 - Cohere embed-multilingual-v3: 1024 dimensions
-- Google `text-embedding-004`: 768 dimensions (or custom)
+- Google text-embedding-004: 768 dimensions (or custom)
 
-> **Important**: Index dimensions cannot be changed after creation. To use a different model, delete and recreate the index with the new dimension size.
+:::important
+Index dimensions cannot be changed after creation. To use a different model, delete and recreate the index with the new dimension size.
+:::
 
 ### Naming Rules for Databases
 
@@ -535,7 +537,9 @@ The upsert operation:
 
 Vector stores support rich metadata (any JSON-serializable fields) for filtering and organization. Since metadata is stored with no fixed schema, use consistent field naming to avoid unexpected query results.
 
-**Important**: Metadata is crucial for vector storage - without it, you'd only have numerical embeddings with no way to return the original text or filter results. Always store at least the source text as metadata.
+:::important
+Metadata is crucial for vector storage - without it, you'd only have numerical embeddings with no way to return the original text or filter results. Always store at least the source text as metadata.
+:::
 
 ```ts showLineNumbers copy
 // Store embeddings with rich metadata for better organization and filtering

package/.docs/raw/reference/agents/agent.mdx

@@ -212,17 +212,24 @@ export const agent = new Agent({
     },
     {
       name: "inputProcessors",
-      type: "Processor[] | ({ requestContext: RequestContext }) => Processor[] | Promise<Processor[]>",
+      type: "(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>",
       isOptional: true,
       description:
-        "Input processors that can modify or validate messages before they are processed by the agent. Must implement the `processInput` function.",
+        "Input processors that can modify or validate messages before they are processed by the agent. Can be individual Processor objects or workflows created with `createWorkflow()` using ProcessorStepSchema.",
     },
     {
       name: "outputProcessors",
-      type: "Processor[] | ({ requestContext: RequestContext }) => Processor[] | Promise<Processor[]>",
+      type: "(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>",
       isOptional: true,
       description:
-        "Output processors that can modify or validate messages from the agent, before it is sent to the client. Must implement either (or both) of the `processOutputResult` and `processOutputStream` functions.",
+        "Output processors that can modify or validate messages from the agent before they are sent to the client. Can be individual Processor objects or workflows.",
+    },
+    {
+      name: "maxProcessorRetries",
+      type: "number",
+      isOptional: true,
+      description:
+        "Maximum number of times a processor can request retrying the LLM step.",
     },
   ]}
 />