@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

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

@@ -0,0 +1,131 @@
+# Memory Processors
+
+Memory Processors allow you to modify the list of messages retrieved from memory _before_ they are added to the agent's context window and sent to the LLM. This is useful for managing context size, filtering content, and optimizing performance.
+
+Processors operate on the messages retrieved based on your memory configuration (e.g., `lastMessages`, `semanticRecall`). They do **not** affect the new incoming user message.
+
+## Built-in Processors
+
+Mastra provides built-in processors:
+
+### `TokenLimiter`
+
+This processor is used to prevent errors caused by exceeding the LLM's context window limit. It counts the tokens in the retrieved memory messages and removes the oldest messages until the total count is below the specified `limit`.
+
+```typescript copy showLineNumbers {9-12}
+import { Memory } from "@mastra/memory";
+import { TokenLimiter } from "@mastra/memory/processors";
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+
+const agent = new Agent({
+  model: openai("gpt-4o"),
+  memory: new Memory({
+    processors: [
+      // Ensure the total tokens from memory don't exceed ~127k
+      new TokenLimiter(127000),
+    ],
+  }),
+});
+```
+
+The `TokenLimiter` uses the `o200k_base` encoding by default (suitable for GPT-4o). You can specify other encodings if needed for different models:
+
+```typescript copy showLineNumbers {6-9}
+// Import the encoding you need (e.g., for older OpenAI models)
+import cl100k_base from "js-tiktoken/ranks/cl100k_base";
+
+const memoryForOlderModel = new Memory({
+  processors: [
+    new TokenLimiter({
+      limit: 16000, // Example limit for a 16k context model
+      encoding: cl100k_base,
+    }),
+  ],
+});
+```
+
+See the [OpenAI cookbook](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken#encodings) or [`js-tiktoken` repo](https://github.com/dqbd/tiktoken) for more on encodings.
+
+### `ToolCallFilter`
+
+This processor removes tool calls from the memory messages sent to the LLM. It saves tokens by excluding potentially verbose tool interactions from the context, which is useful if the details aren't needed for future interactions. It's also useful if you always want your agent to call a specific tool again and not rely on previous tool results in memory.
+
+```typescript copy showLineNumbers {5-14}
+import { Memory } from "@mastra/memory";
+import { ToolCallFilter, TokenLimiter } from "@mastra/memory/processors";
+
+const memoryFilteringTools = new Memory({
+  processors: [
+    // Example 1: Remove all tool calls/results
+    new ToolCallFilter(),
+
+    // Example 2: Remove only noisy image generation tool calls/results
+    new ToolCallFilter({ exclude: ["generateImageTool"] }),
+
+    // Always place TokenLimiter last
+    new TokenLimiter(127000),
+  ],
+});
+```
+
+## Applying Multiple Processors
+
+You can chain multiple processors. They execute in the order they appear in the `processors` array. The output of one processor becomes the input for the next.
+
+**Order matters!** It's generally best practice to place `TokenLimiter` **last** in the chain. This ensures it operates on the final set of messages after other filtering has occurred, providing the most accurate token limit enforcement.
+
+```typescript copy showLineNumbers {7-14}
+import { Memory } from "@mastra/memory";
+import { ToolCallFilter, TokenLimiter } from "@mastra/memory/processors";
+// Assume a hypothetical 'PIIFilter' custom processor exists
+// import { PIIFilter } from './custom-processors';
+
+const memoryWithMultipleProcessors = new Memory({
+  processors: [
+    // 1. Filter specific tool calls first
+    new ToolCallFilter({ exclude: ["verboseDebugTool"] }),
+    // 2. Apply custom filtering (e.g., remove hypothetical PII - use with caution)
+    // new PIIFilter(),
+    // 3. Apply token limiting as the final step
+    new TokenLimiter(127000),
+  ],
+});
+```
+
+## Creating Custom Processors
+
+You can create custom logic by extending the base `MemoryProcessor` class.
+
+```typescript copy showLineNumbers {4-19,23-26}
+import { Memory, CoreMessage } from "@mastra/memory";
+import { MemoryProcessor, MemoryProcessorOpts } from "@mastra/core/memory";
+
+class ConversationOnlyFilter extends MemoryProcessor {
+  constructor() {
+    // Provide a name for easier debugging if needed
+    super({ name: "ConversationOnlyFilter" });
+  }
+
+  process(
+    messages: CoreMessage[],
+    _opts: MemoryProcessorOpts = {}, // Options passed during memory retrieval, rarely needed here
+  ): CoreMessage[] {
+    // Filter messages based on role
+    return messages.filter(
+      (msg) => msg.role === "user" || msg.role === "assistant",
+    );
+  }
+}
+
+// Use the custom processor
+const memoryWithCustomFilter = new Memory({
+  processors: [
+    new ConversationOnlyFilter(),
+    new TokenLimiter(127000), // Still apply token limiting
+  ],
+});
+```
+
+When creating custom processors avoid mutating the input `messages` array or its objects directly.
+

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

@@ -0,0 +1,119 @@
+## Overview
+
+Memory is how agents manage the context that's available to them, it's a condensation of all chat messages into their context window.
+
+## The Context Window
+
+The context window is the total information visible to the language model at any given time.
+
+In Mastra, context is broken up into three parts: system instructions and information about the user ([working memory](./working-memory.mdx)), recent messages ([message history](#conversation-history)), and older messages that are relevant to the user’s query ([semantic recall](./semantic-recall.mdx)).
+
+In addition, we provide [memory processors](./memory-processors.mdx) to trim context or remove information if the context is too long.
+
+## Quick Start
+
+The fastest way to see memory in action is using the built-in development playground.
+
+If you haven't already, create a new Mastra project following the main [Getting Started guide](/docs/getting-started/installation).
+
+**1. Install the memory package:**
+
+```bash npm2yarn copy
+npm install @mastra/memory
+```
+
+**2. Create an agent and attach a `Memory` instance:**
+
+```typescript filename="src/mastra/agents/index.ts" {10}
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+import { openai } from "@ai-sdk/openai";
+
+export const myMemoryAgent = new Agent({
+  name: "MemoryAgent",
+  instructions: "...",
+  model: openai("gpt-4o"),
+
+  memory: new Memory(),
+});
+```
+
+**3. Start the Development Server:**
+
+```bash npm2yarn copy
+npm run dev
+```
+
+**4. Open the playground (http://localhost:4111) and select your `MemoryAgent`:**
+
+Send a few messages and notice that it remembers information across turns:
+
+```
+➡️ You: My favorite color is blue.
+⬅️ Agent: Got it! I'll remember that your favorite color is blue.
+➡️ You: What is my favorite color?
+⬅️ Agent: Your favorite color is blue.
+```
+
+## Memory Threads
+
+Mastra organizes memory into threads, which are records that identify specific conversation histories, using two identifiers:
+
+1.  **`threadId`**: A specific conversation id (e.g., `support_123`).
+2.  **`resourceId`**: The user or entity id that owns each thread (e.g., `user_123`, `org_456`).
+
+```typescript {2,3}
+const response = await myMemoryAgent.stream("Hello, my name is Alice.", {
+  resourceId: "user_alice",
+  threadId: "conversation_123",
+});
+```
+
+**Important:** without these ID's your agent will not use memory, even if memory is properly configured. The playground handles this for you, but you need to add ID's yourself when using memory in your application.
+
+## Conversation History
+
+By default, the `Memory` instance includes the [last 40 messages](../../reference/memory/Memory.mdx) from the current Memory thread in each new request. This provides the agent with immediate conversational context.
+
+```ts {3}
+const memory = new Memory({
+  options: {
+    lastMessages: 10,
+  },
+});
+```
+
+**Important:** Only send the newest user message in each agent call. Mastra handles retrieving and injecting the necessary history. Sending the full history yourself will cause duplication. See the [AI SDK Memory Example](../../examples/memory/use-chat.mdx) for how to handle this with when using the `useChat` frontend hooks.
+
+### Storage Configuration
+
+Conversation history relies on a [storage adapter](/reference/memory/Memory#parameters) to store messages.
+
+```ts {7-12}
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { LibSQLStore } from "@mastra/core/storage/libsql";
+
+const agent = new Agent({
+  memory: new Memory({
+    // this is the default storage db if omitted
+    storage: new LibSQLStore({
+      config: {
+        url: "file:local.db",
+      },
+    }),
+  }),
+});
+```
+
+**Storage code Examples**:
+
+- [LibSQL](/examples/memory/memory-with-libsql)
+- [Postgres](/examples/memory/memory-with-pg)
+- [Upstash](/examples/memory/memory-with-upstash)
+
+## Next Steps
+
+Now that you understand the core concepts, continue to [semantic recall](./semantic-recall.mdx) to learn how to add RAG memory to your Mastra agents.
+
+Alternatively you can visit the [configuration reference](../../reference/memory/Memory.mdx) for available options, or browse [usage examples](../../examples/memory/use-chat.mdx).

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

@@ -0,0 +1,122 @@
+# Recalling Relevant History
+
+If you ask your friend what they did last weekend, they will search in their memory for events associated with "last weekend" and then tell you what they did. That's sort of like how semantic recall works in Mastra.
+
+## How Semantic Recall Works
+
+Semantic recall is RAG-based search that helps agents maintain context across longer interactions when messages are no longer within [recent conversation history](./overview.mdx#conversation-history).
+
+It uses vector embeddings of messages for similarity search, integrates with various vector stores, and has configurable context windows around retrieved messages.
+
+<br />
+<img
+  src="/docs/semantic-recall.png"
+  alt="Diagram showing Mastra Memory semantic recall"
+  width={800}
+/>
+
+## Quick Start
+
+Semantic recall is enabled by default, so if you give your agent memory it will be included:
+
+```typescript {9}
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+import { openai } from "@ai-sdk/openai";
+
+const agent = new Agent({
+  name: "SupportAgent",
+  instructions: "You are a helpful support agent.",
+  model: openai("gpt-4o"),
+  memory: new Memory(),
+});
+```
+
+## Recall configuration
+
+The two main parameters that control semantic recall behavior are:
+
+1. **topK**: How many semantically similar messages to retrieve
+2. **messageRange**: How much surrounding context to include with each match
+
+```typescript {5-6}
+const agent = new Agent({
+  memory: new Memory({
+    options: {
+      semanticRecall: {
+        topK: 3, // Retrieve 3 most similar messages
+        messageRange: 2, // Include 2 messages before and after each match
+      },
+    },
+  }),
+});
+```
+
+### Storage configuration
+
+Semantic recall relies on a [storage and vector db](/reference/memory/Memory#parameters) to store messages and their embeddings.
+
+```ts {8-17}
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { LibSQLStore } from "@mastra/core/storage/libsql";
+import { LibSQLVector } from "@mastra/core/vector/libsql";
+
+const agent = new Agent({
+  memory: new Memory({
+    // this is the default storage db if omitted
+    storage: new LibSQLStore({
+      config: {
+        url: "file:local.db",
+      },
+    }),
+    // this is the default vector db if omitted
+    vector: new LibSQLVector({
+      connectionUrl: "file:local.db",
+    }),
+  }),
+});
+```
+
+**Storage/vector code Examples**:
+
+- [LibSQL](/examples/memory/memory-with-libsql)
+- [Postgres](/examples/memory/memory-with-pg)
+- [Upstash](/examples/memory/memory-with-upstash)
+
+### Embedder configuration
+
+Semantic recall relies an [embedding model](/reference/memory/Memory#embedder) to convert messages into embeddings. By default Mastra uses FastEmbed but you can specify another [embedding model](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings).
+
+```ts {7}
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+
+const agent = new Agent({
+  memory: new Memory({
+    embedder: openai.embedding("text-embedding-3-small"),
+  }),
+});
+```
+
+### Disabling
+
+There is a performance impact to using semantic recall. New messages are converted into embeddings and used to query a vector database before new messages are sent to the LLM.
+
+Semantic recall is enabled by default but can be disabled when not needed:
+
+```typescript {4}
+const agent = new Agent({
+  memory: new Memory({
+    options: {
+      semanticRecall: false,
+    },
+  }),
+});
+```
+
+You might want to disable semantic recall in scenarios like:
+
+- When [conversation history](./getting-started.mdx#conversation-history-last-messages) provide sufficient context for the current conversation.
+- In performance-sensitive applications, like realtime two-way audio, where the added latency of creating embeddings and running vector queries is noticeable.

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

@@ -0,0 +1,87 @@
+import YouTube from "../../../components/youtube";
+
+# Continuously Relevant Information
+
+While [conversation history](/docs/memory/overview#conversation-history) and [semantic recall](./semantic-recall.mdx) help agents remember conversations, working memory allows them to maintain persistent information about users across interactions within a thread.
+
+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.
+
+This is useful for maintaining ongoing state that's always relevant and should always be available to the agent.
+
+## Quick Start
+
+Here's a minimal example of setting up an agent with working memory:
+
+```typescript {12-15}
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+import { openai } from "@ai-sdk/openai";
+
+// Create agent with working memory enabled
+const agent = new Agent({
+  name: "PersonalAssistant",
+  instructions: "You are a helpful personal assistant.",
+  model: openai("gpt-4o"),
+  memory: new Memory({
+    options: {
+      workingMemory: {
+        enabled: true,
+        use: "tool-call", // Recommended setting
+      },
+    },
+  }),
+});
+```
+
+## How it Works
+
+Working memory is a block of Markdown text that the agent is able to update over time to store continuously relevant information:
+
+<YouTube id="ik-ld_XA96s" />
+
+## Custom Templates
+
+Templates guide the agent on what information to track and update in working memory. While a default template is used if none is provided, you'll typically want to define a custom template tailored to your agent's specific use case to ensure it remembers the most relevant information.
+
+Here's an example of a custom template. In this example the agent will store the users name, location, timezone, etc as soon as the user sends a message containing any of the info:
+
+```typescript {5-28}
+const memory = new Memory({
+  options: {
+    workingMemory: {
+      enabled: true,
+      template: `
+# User Profile
+ 
+## Personal Info
+ 
+- Name:
+- Location:
+- Timezone:
+ 
+## Preferences
+ 
+- Communication Style: [e.g., Formal, Casual]
+- Project Goal:
+- Key Deadlines:
+  - [Deadline 1]: [Date]
+  - [Deadline 2]: [Date]
+ 
+## Session State
+ 
+- Last Task Discussed:
+- Open Questions:
+  - [Question 1]
+  - [Question 2]
+`,
+    },
+  },
+});
+```
+
+If your agent is not properly updating working memory when you expect it to, you can add system instructions on _how_ and _when_ to use this template in your agents `instruction` setting.
+
+## Examples
+
+- [Streaming working memory](/examples/memory/streaming-working-memory)
+- [Using a working memory template](/examples/memory/streaming-working-memory-advanced)

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

@@ -0,0 +1,38 @@
+---
+title: "Logging | Mastra Observability Documentation"
+description: Documentation on effective logging in Mastra, crucial for understanding application behavior and improving AI accuracy.
+---
+
+import Image from "next/image";
+
+# Logging
+
+In Mastra, logs can detail when certain functions run, what input data they receive, and how they respond.
+
+## Basic Setup
+
+Here's a minimal example that sets up a **console logger** at the `INFO` level. This will print out informational messages and above (i.e., `DEBUG`, `INFO`, `WARN`, `ERROR`) to the console.
+
+```typescript filename="mastra.config.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core";
+import { createLogger } from "@mastra/core/logger";
+
+export const mastra = new Mastra({
+  // Other Mastra configuration...
+  logger: createLogger({
+    name: "Mastra",
+    level: "info",
+  }),
+});
+```
+
+In this configuration:
+
+- `name: "Mastra"` specifies the name to group logs under.
+- `level: "info"` sets the minimum severity of logs to record.
+
+## Configuration
+
+- For more details on the options you can pass to `createLogger()`, see the [createLogger reference documentation](/reference/observability/create-logger.mdx).
+- Once you have a `Logger` instance, you can call its methods (e.g., `.info()`, `.warn()`, `.error()`) in the [Logger instance reference documentation](/reference/observability/logger.mdx).
+- If you want to send your logs to an external service for centralized collection, analysis, or storage, you can configure other logger types such as Upstash Redis. Consult the [createLogger reference documentation](/reference/observability/create-logger.mdx) for details on parameters like `url`, `token`, and `key` when using the `UPSTASH` logger type.

package/.docs/raw/observability/nextjs-tracing.mdx

@@ -0,0 +1,108 @@
+---
+title: "Next.js Tracing | Mastra Observability Documentation"
+description: "Set up OpenTelemetry tracing for Next.js applications"
+---
+
+# Next.js Tracing
+
+Next.js requires additional configuration to enable OpenTelemetry tracing. 
+
+### Step 1: Next.js Configuration
+
+Start by enabling the instrumentation hook in your Next.js config:
+
+```ts filename="next.config.ts" showLineNumbers copy
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  experimental: {
+    instrumentationHook: true // Not required in Next.js 15+
+  }
+};
+
+export default nextConfig;
+```
+
+### Step 2: Mastra Configuration
+
+Configure your Mastra instance:
+
+```typescript filename="mastra.config.ts" copy
+import { Mastra } from "@mastra/core";
+
+export const mastra = new Mastra({
+  // ... other config
+  telemetry: {
+    serviceName: "your-project-name",
+    enabled: true
+  }
+});
+```
+
+### Step 3: Configure your providers
+
+If you're using Next.js, you have two options for setting up OpenTelemetry instrumentation:
+
+#### Option 1: Using a Custom Exporter
+
+The default that will work across providers is to configure a custom exporter:
+
+1. Install the required dependencies (example using Langfuse):
+
+```bash copy
+npm install @opentelemetry/api langfuse-vercel
+```
+
+2. Create an instrumentation file:
+
+```ts filename="instrumentation.ts" copy
+import {
+  NodeSDK,
+  ATTR_SERVICE_NAME,
+  Resource,
+} from '@mastra/core/telemetry/otel-vendor';
+import { LangfuseExporter } from 'langfuse-vercel';
+
+export function register() {
+  const exporter = new LangfuseExporter({
+    // ... Langfuse config
+  })
+
+  const sdk = new NodeSDK({
+    resource: new Resource({
+      [ATTR_SERVICE_NAME]: 'ai',
+    }),
+    traceExporter: exporter,
+  });
+
+  sdk.start();
+}
+```
+
+#### Option 2: Using Vercel's Otel Setup
+
+If you're deploying to Vercel, you can use their OpenTelemetry setup:
+
+1. Install the required dependencies:
+
+```bash copy
+npm install @opentelemetry/api @vercel/otel
+```
+
+2. Create an instrumentation file at the root of your project (or in the src folder if using one):
+
+```ts filename="instrumentation.ts" copy
+import { registerOTel } from '@vercel/otel'
+
+export function register() {
+  registerOTel({ serviceName: 'your-project-name' })
+}
+```
+
+### Summary
+
+This setup will enable OpenTelemetry tracing for your Next.js application and Mastra operations.
+
+For more details, see the documentation for:
+- [Next.js Instrumentation](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation)
+- [Vercel OpenTelemetry](https://vercel.com/docs/observability/otel-overview/quickstart)