@mastra/mcp-docs-server 1.0.0-beta.4 → 1.0.0-beta.6

package/.docs/raw/reference/processors/semantic-recall-processor.mdx

@@ -0,0 +1,197 @@
+---
+title: "Reference: Semantic Recall Processor | Processors"
+description: "Documentation for the SemanticRecall processor in Mastra, which enables semantic search over conversation history using vector embeddings."
+---
+
+# SemanticRecall
+
+The `SemanticRecall` is a **hybrid processor** that enables semantic search over conversation history using vector embeddings. On input, it performs semantic search to find relevant historical messages. On output, it creates embeddings for new messages to enable future semantic retrieval.
+
+## Usage example
+
+```typescript copy
+import { SemanticRecall } from "@mastra/core/processors";
+import { openai } from "@ai-sdk/openai";
+
+const processor = new SemanticRecall({
+  storage: memoryStorage,
+  vector: vectorStore,
+  embedder: openai.embedding("text-embedding-3-small"),
+  topK: 5,
+  messageRange: 2,
+  scope: "resource",
+});
+```
+
+## Constructor parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "options",
+      type: "SemanticRecallOptions",
+      description: "Configuration options for the semantic recall processor",
+      isOptional: false,
+    },
+  ]}
+/>
+
+### Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "storage",
+      type: "MemoryStorage",
+      description: "Storage instance for retrieving messages",
+      isOptional: false,
+    },
+    {
+      name: "vector",
+      type: "MastraVector",
+      description: "Vector store for semantic search",
+      isOptional: false,
+    },
+    {
+      name: "embedder",
+      type: "MastraEmbeddingModel<string>",
+      description: "Embedder for generating query embeddings",
+      isOptional: false,
+    },
+    {
+      name: "topK",
+      type: "number",
+      description: "Number of most similar messages to retrieve",
+      isOptional: true,
+      default: "4",
+    },
+    {
+      name: "messageRange",
+      type: "number | { before: number; after: number }",
+      description: "Number of context messages to include before/after each match. Can be a single number (same for both) or an object with separate values",
+      isOptional: true,
+      default: "1",
+    },
+    {
+      name: "scope",
+      type: "'thread' | 'resource'",
+      description: "Scope of semantic search. 'thread' searches within the current thread only. 'resource' searches across all threads for the resource",
+      isOptional: true,
+      default: "'resource'",
+    },
+    {
+      name: "threshold",
+      type: "number",
+      description: "Minimum similarity score threshold (0-1). Messages below this threshold are filtered out",
+      isOptional: true,
+    },
+    {
+      name: "indexName",
+      type: "string",
+      description: "Index name for the vector store. If not provided, auto-generated based on embedder model",
+      isOptional: true,
+    },
+    {
+      name: "logger",
+      type: "IMastraLogger",
+      description: "Optional logger instance for structured logging",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Processor identifier set to 'semantic-recall'",
+      isOptional: false,
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Processor display name set to 'SemanticRecall'",
+      isOptional: false,
+    },
+    {
+      name: "processInput",
+      type: "(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>",
+      description: "Performs semantic search on historical messages and adds relevant context to the message list",
+      isOptional: false,
+    },
+    {
+      name: "processOutputResult",
+      type: "(args: { messages: MastraDBMessage[]; messageList?: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>",
+      description: "Creates embeddings for new messages to enable future semantic search",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Extended usage example
+
+```typescript title="src/mastra/agents/semantic-memory-agent.ts" showLineNumbers copy
+import { Agent } from "@mastra/core/agent";
+import { SemanticRecall, MessageHistory } from "@mastra/core/processors";
+import { PostgresStorage } from "@mastra/pg";
+import { PgVector } from "@mastra/pg";
+import { openai } from "@ai-sdk/openai";
+
+const storage = new PostgresStorage({
+  connectionString: process.env.DATABASE_URL,
+});
+
+const vector = new PgVector({
+  connectionString: process.env.DATABASE_URL,
+});
+
+const semanticRecall = new SemanticRecall({
+  storage,
+  vector,
+  embedder: openai.embedding("text-embedding-3-small"),
+  topK: 5,
+  messageRange: { before: 2, after: 1 },
+  scope: "resource",
+  threshold: 0.7,
+});
+
+export const agent = new Agent({
+  name: "semantic-memory-agent",
+  instructions: "You are a helpful assistant with semantic memory recall",
+  model: "openai:gpt-4o",
+  inputProcessors: [
+    semanticRecall,
+    new MessageHistory({ storage, lastMessages: 50 }),
+  ],
+  outputProcessors: [
+    semanticRecall,
+    new MessageHistory({ storage }),
+  ],
+});
+```
+
+## Behavior
+
+### Input processing
+1. Extracts the user query from the last user message
+2. Generates embeddings for the query
+3. Performs vector search to find semantically similar messages
+4. Retrieves matched messages along with surrounding context (based on `messageRange`)
+5. For `scope: 'resource'`, formats cross-thread messages as a system message with timestamps
+6. Adds recalled messages with `source: 'memory'` tag
+
+### Output processing
+1. Extracts text content from new user and assistant messages
+2. Generates embeddings for each message
+3. Stores embeddings in the vector store with metadata (message ID, thread ID, resource ID, role, content, timestamp)
+4. Uses LRU caching for embeddings to avoid redundant API calls
+
+### Cross-thread recall
+When `scope` is set to `'resource'`, the processor can recall messages from other threads. These cross-thread messages are formatted as a system message with timestamps and conversation labels to provide context about when and where the conversation occurred.
+
+## Related
+
+- [Guardrails](/docs/v1/agents/guardrails)

package/.docs/raw/reference/processors/system-prompt-scrubber.mdx

@@ -10,11 +10,10 @@ The `SystemPromptScrubber` is an **output processor** that detects and handles s
 ## Usage example
 
 ```typescript copy
-import { openai } from "@ai-sdk/openai";
 import { SystemPromptScrubber } from "@mastra/core/processors";
 
 const processor = new SystemPromptScrubber({
-  model: openai("gpt-4.1-nano"),
+  model: "openrouter/openai/gpt-oss-safeguard-20b",
   strategy: "redact",
   redactionMethod: "mask",
   includeDetections: true
@@ -131,7 +130,7 @@ import { BatchPartsProcessor, SystemPromptScrubber } from "@mastra/core/processo
 export const agent = new Agent({
   name: "scrubbed-agent",
   instructions: "You are a helpful assistant",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   outputProcessors: [
     // Batch stream parts first to reduce LLM calls
     new BatchPartsProcessor({
@@ -139,7 +138,7 @@ export const agent = new Agent({
     }),
     // Then apply system prompt detection on batched content
     new SystemPromptScrubber({
-      model: "openai/gpt-4.1-nano",
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       strategy: "redact",
       customPatterns: ["system prompt", "internal instructions"],
       includeDetections: true,

package/.docs/raw/reference/processors/token-limiter-processor.mdx

@@ -45,7 +45,7 @@ const processor = new TokenLimiterProcessor({
     {
       name: "encoding",
       type: "TiktokenBPE",
-      description: "Optional encoding to use. Defaults to o200k_base which is used by gpt-4o",
+      description: "Optional encoding to use. Defaults to o200k_base which is used by gpt-5.1",
       isOptional: true,
       default: "o200k_base",
     },
@@ -124,7 +124,7 @@ import { TokenLimiterProcessor } from "@mastra/core/processors";
 export const agent = new Agent({
   name: "limited-agent",
   instructions: "You are a helpful assistant",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   outputProcessors: [
     new TokenLimiterProcessor({
       limit: 1000,

package/.docs/raw/reference/processors/tool-call-filter.mdx

@@ -0,0 +1,125 @@
+---
+title: "Reference: Tool Call Filter | Processors"
+description: "Documentation for the ToolCallFilter processor in Mastra, which filters out tool calls and results from messages."
+---
+
+# ToolCallFilter
+
+The `ToolCallFilter` is an **input processor** that filters out tool calls and their results from the message history before sending to the model. This is useful when you want to exclude specific tool interactions from context or remove all tool calls entirely.
+
+## Usage example
+
+```typescript copy
+import { ToolCallFilter } from "@mastra/core/processors";
+
+// Exclude all tool calls
+const filterAll = new ToolCallFilter();
+
+// Exclude specific tools by name
+const filterSpecific = new ToolCallFilter({
+  exclude: ["searchDatabase", "sendEmail"],
+});
+```
+
+## Constructor parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "options",
+      type: "Options",
+      description: "Configuration options for the tool call filter",
+      isOptional: true,
+    },
+  ]}
+/>
+
+### Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "exclude",
+      type: "string[]",
+      description: "List of specific tool names to exclude. If not provided or undefined, all tool calls are excluded",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Processor identifier set to 'tool-call-filter'",
+      isOptional: false,
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Processor display name set to 'ToolCallFilter'",
+      isOptional: false,
+    },
+    {
+      name: "processInput",
+      type: "(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>",
+      description: "Processes input messages to filter out tool calls and their results based on configuration",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Extended usage example
+
+```typescript title="src/mastra/agents/filtered-agent.ts" showLineNumbers copy
+import { Agent } from "@mastra/core/agent";
+import { ToolCallFilter } from "@mastra/core/processors";
+
+export const agent = new Agent({
+  name: "filtered-agent",
+  instructions: "You are a helpful assistant",
+  model: "openai:gpt-4o",
+  tools: {
+    searchDatabase,
+    sendEmail,
+    getWeather,
+  },
+  inputProcessors: [
+    // Filter out database search tool calls from context
+    // to reduce token usage while keeping other tool interactions
+    new ToolCallFilter({
+      exclude: ["searchDatabase"],
+    }),
+  ],
+});
+```
+
+## Filtering all tool calls
+
+```typescript copy
+import { Agent } from "@mastra/core/agent";
+import { ToolCallFilter } from "@mastra/core/processors";
+
+export const agent = new Agent({
+  name: "no-tools-context-agent",
+  instructions: "You are a helpful assistant",
+  model: "openai:gpt-4o",
+  tools: {
+    searchDatabase,
+    sendEmail,
+  },
+  inputProcessors: [
+    // Remove all tool calls from the message history
+    // The agent can still use tools, but previous tool interactions
+    // won't be included in the context
+    new ToolCallFilter(),
+  ],
+});
+```
+
+## Related
+
+- [Guardrails](/docs/v1/agents/guardrails)

package/.docs/raw/reference/processors/unicode-normalizer.mdx

@@ -101,7 +101,7 @@ import { UnicodeNormalizer } from "@mastra/core/processors";
 export const agent = new Agent({
   name: "normalized-agent",
   instructions: "You are a helpful assistant",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
   inputProcessors: [
     new UnicodeNormalizer({
       stripControlChars: true,

package/.docs/raw/reference/processors/working-memory-processor.mdx

@@ -0,0 +1,221 @@
+---
+title: "Reference: Working Memory Processor | Processors"
+description: "Documentation for the WorkingMemory processor in Mastra, which injects persistent user/context data as system instructions."
+---
+
+# WorkingMemory
+
+The `WorkingMemory` is an **input processor** that injects working memory data as a system message. It retrieves persistent information from storage and formats it as instructions for the LLM, enabling the agent to maintain context about users across conversations.
+
+## Usage example
+
+```typescript copy
+import { WorkingMemory } from "@mastra/core/processors";
+
+const processor = new WorkingMemory({
+  storage: memoryStorage,
+  scope: "resource",
+  template: {
+    format: "markdown",
+    content: `# User Profile
+- **Name**:
+- **Preferences**:
+- **Goals**:
+`,
+  },
+});
+```
+
+## Constructor parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "options",
+      type: "Options",
+      description: "Configuration options for the working memory processor",
+      isOptional: false,
+    },
+  ]}
+/>
+
+### Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "storage",
+      type: "MemoryStorage",
+      description: "Storage instance for retrieving working memory data",
+      isOptional: false,
+    },
+    {
+      name: "template",
+      type: "WorkingMemoryTemplate",
+      description: "Template defining the format and structure of working memory",
+      isOptional: true,
+    },
+    {
+      name: "scope",
+      type: "'thread' | 'resource'",
+      description: "Scope of working memory. 'thread' scopes to current thread, 'resource' shares across all threads for the resource",
+      isOptional: true,
+      default: "'resource'",
+    },
+    {
+      name: "useVNext",
+      type: "boolean",
+      description: "Use the next-generation instruction format with improved guidelines",
+      isOptional: true,
+    },
+    {
+      name: "templateProvider",
+      type: "{ getWorkingMemoryTemplate(args: { memoryConfig?: MemoryConfig }): Promise<WorkingMemoryTemplate | null> }",
+      description: "Dynamic template provider for runtime template resolution",
+      isOptional: true,
+    },
+    {
+      name: "logger",
+      type: "IMastraLogger",
+      description: "Optional logger instance for structured logging",
+      isOptional: true,
+    },
+  ]}
+/>
+
+### WorkingMemoryTemplate
+
+<PropertiesTable
+  content={[
+    {
+      name: "format",
+      type: "'markdown' | 'json'",
+      description: "Format of the working memory content",
+      isOptional: false,
+    },
+    {
+      name: "content",
+      type: "string",
+      description: "Template content defining the structure of working memory data",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Processor identifier set to 'working-memory'",
+      isOptional: false,
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Processor display name set to 'WorkingMemory'",
+      isOptional: false,
+    },
+    {
+      name: "defaultWorkingMemoryTemplate",
+      type: "string",
+      description: "The default markdown template used when no custom template is provided",
+      isOptional: false,
+    },
+    {
+      name: "processInput",
+      type: "(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>",
+      description: "Retrieves working memory and adds it as a system message to the message list",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Extended usage example
+
+```typescript title="src/mastra/agents/personalized-agent.ts" showLineNumbers copy
+import { Agent } from "@mastra/core/agent";
+import { WorkingMemory, MessageHistory } from "@mastra/core/processors";
+import { PostgresStorage } from "@mastra/pg";
+
+const storage = new PostgresStorage({
+  connectionString: process.env.DATABASE_URL,
+});
+
+export const agent = new Agent({
+  name: "personalized-agent",
+  instructions: "You are a helpful assistant that remembers user preferences",
+  model: "openai:gpt-4o",
+  inputProcessors: [
+    new WorkingMemory({
+      storage,
+      scope: "resource",
+      template: {
+        format: "markdown",
+        content: `# User Information
+- **Name**:
+- **Location**:
+- **Preferences**:
+- **Communication Style**:
+- **Current Projects**:
+`,
+      },
+    }),
+    new MessageHistory({ storage, lastMessages: 50 }),
+  ],
+  outputProcessors: [
+    new MessageHistory({ storage }),
+  ],
+});
+```
+
+## JSON format example
+
+```typescript copy
+import { WorkingMemory } from "@mastra/core/processors";
+
+const processor = new WorkingMemory({
+  storage: memoryStorage,
+  scope: "resource",
+  template: {
+    format: "json",
+    content: JSON.stringify({
+      user: {
+        name: { type: "string" },
+        preferences: { type: "object" },
+        goals: { type: "array" },
+      },
+    }),
+  },
+});
+```
+
+## Behavior
+
+### Input processing
+1. Retrieves `threadId` and `resourceId` from the request context
+2. Based on scope, fetches working memory from either:
+   - Thread metadata (`scope: 'thread'`)
+   - Resource record (`scope: 'resource'`)
+3. Resolves the template (from provider, options, or default)
+4. Generates system instructions that include:
+   - Guidelines for the LLM on storing and updating information
+   - The template structure
+   - Current working memory data
+5. Adds the instruction as a system message with `source: 'memory'` tag
+
+### Working memory updates
+Working memory updates happen through the `updateWorkingMemory` tool provided by the Memory class, not through this processor. The processor only handles injecting the current working memory state into conversations.
+
+### Default template
+If no template is provided, the processor uses a default markdown template with fields for:
+- First Name, Last Name
+- Location, Occupation
+- Interests, Goals
+- Events, Facts, Projects
+
+## Related
+
+- [Guardrails](/docs/v1/agents/guardrails)

package/.docs/raw/reference/rag/embeddings.mdx

@@ -13,9 +13,10 @@ The `embed` function generates a vector embedding for a single text input:
 
 ```typescript
 import { embed } from "ai";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 
 const result = await embed({
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   value: "Your text to embed",
   maxRetries: 2, // optional, defaults to 2
 });
@@ -80,7 +81,7 @@ For embedding multiple texts at once, use the `embedMany` function:
 import { embedMany } from "ai";
 
 const result = await embedMany({
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   values: ["First text", "Second text", "Third text"],
   maxRetries: 2, // optional, defaults to 2
 });
@@ -142,17 +143,16 @@ const result = await embedMany({
 
 ```typescript
 import { embed, embedMany } from "ai";
-import { openai } from "@ai-sdk/openai";
 
 // Single embedding
 const singleResult = await embed({
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   value: "What is the meaning of life?",
 });
 
 // Multiple embeddings
 const multipleResult = await embedMany({
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   values: [
     "First question about life",
     "Second question about universe",

package/.docs/raw/reference/rag/rerank.mdx

@@ -19,10 +19,9 @@ function rerank(
 ## Usage Example
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
 import { rerank } from "@mastra/rag";
 
-const model = openai("gpt-4o-mini");
+const model = "openai/gpt-5.1";
 
 const rerankedResults = await rerank(
   vectorSearchResults,

package/.docs/raw/reference/rag/rerankWithScorer.mdx

@@ -19,7 +19,6 @@ function rerankWithScorer({
 ## Usage Example
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
 import { rerankWithScorer as rerank, CohereRelevanceScorer } from "@mastra/rag";
 
 const scorer = new CohereRelevanceScorer("rerank-v3.5");