@mastra/mcp-docs-server 0.0.0-default-storage-virtual-file-20250410035748

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](/docs/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](/docs/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](/docs/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)

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

@@ -0,0 +1,115 @@
+---
+title: "Tracing | Mastra Observability Documentation"
+description: "Set up OpenTelemetry tracing for Mastra applications"
+---
+
+import Image from "next/image";
+
+# Tracing
+
+Mastra supports the OpenTelemetry Protocol (OTLP) for tracing and monitoring your application. When telemetry is enabled, Mastra automatically traces all core primitives including agent operations, LLM interactions, tool executions, integration calls, workflow runs, and database operations. Your telemetry data can then be exported to any OTEL collector.
+
+### Basic Configuration
+
+Here's a simple example of enabling telemetry:
+
+```ts filename="mastra.config.ts" showLineNumbers copy
+export const mastra = new Mastra({
+  // ... other config
+  telemetry: {
+    serviceName: "my-app",
+    enabled: true,
+    sampling: {
+      type: "always_on",
+    },
+    export: {
+      type: "otlp",
+      endpoint: "http://localhost:4318", // SigNoz local endpoint
+    },
+  },
+});
+```
+
+### Configuration Options
+
+The telemetry config accepts these properties:
+
+```ts
+type OtelConfig = {
+  // Name to identify your service in traces (optional)
+  serviceName?: string;
+
+  // Enable/disable telemetry (defaults to true)
+  enabled?: boolean;
+
+  // Control how many traces are sampled
+  sampling?: {
+    type: "ratio" | "always_on" | "always_off" | "parent_based";
+    probability?: number; // For ratio sampling
+    root?: {
+      probability: number; // For parent_based sampling
+    };
+  };
+
+  // Where to send telemetry data
+  export?: {
+    type: "otlp" | "console";
+    endpoint?: string;
+    headers?: Record<string, string>;
+  };
+};
+```
+
+See the [OtelConfig reference documentation](/docs/reference/observability/otel-config.mdx) for more details.
+
+### Environment Variables
+
+You can configure the OTLP endpoint and headers through environment variables:
+
+```env filename=".env" copy
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-api-key
+```
+
+Then in your config:
+
+```ts filename="mastra.config.ts" showLineNumbers copy
+export const mastra = new Mastra({
+  // ... other config
+  telemetry: {
+    serviceName: "my-app",
+    enabled: true,
+    export: {
+      type: "otlp",
+      // endpoint and headers will be picked up from env vars
+    },
+  },
+});
+```
+
+### Example: SigNoz Integration
+
+Here's what a traced agent interaction looks like in [SigNoz](https://signoz.io):
+
+<img
+  src="/docs/signoz-telemetry-demo.png"
+  alt="Agent interaction trace showing spans, LLM calls, and tool executions"
+  style={{ maxWidth: "800px", width: "100%", margin: "8px 0" }}
+  className="nextra-image rounded-md"
+  data-zoom
+  width={800}
+  height={400}
+/>
+
+### Other Supported Providers
+
+For a complete list of supported observability providers and their configuration details, see the [Observability Providers reference](../reference/observability/providers/).
+
+### Next.js-specific Tracing steps
+
+If you're using Next.js, you have three additional configuration steps:
+1. Enable the instrumentation hook in `next.config.ts`
+2. Configure Mastra telemetry settings
+3. Set up an OpenTelemetry exporter
+
+For implementation details, see the [Next.js Tracing](./nextjs-tracing) guide.

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

@@ -0,0 +1,156 @@
+---
+title: Chunking and Embedding Documents | RAG | Mastra Docs
+description: Guide on chunking and embedding documents in Mastra for efficient processing and retrieval.
+---
+
+## Chunking and Embedding Documents
+
+Before processing, create a MDocument instance from your content. You can initialize it from various formats:
+
+```ts showLineNumbers copy
+const docFromText = MDocument.fromText("Your plain text content...");
+const docFromHTML = MDocument.fromHTML("<html>Your HTML content...</html>");
+const docFromMarkdown = MDocument.fromMarkdown("# Your Markdown content...");
+const docFromJSON = MDocument.fromJSON(`{ "key": "value" }`);
+```
+
+## Step 1: Document Processing
+
+Use `chunk` to split documents into manageable pieces. Mastra supports multiple chunking strategies optimized for different document types:
+
+- `recursive`: Smart splitting based on content structure
+- `character`: Simple character-based splits
+- `token`: Token-aware splitting
+- `markdown`: Markdown-aware splitting
+- `html`: HTML structure-aware splitting
+- `json`: JSON structure-aware splitting
+- `latex`: LaTeX structure-aware splitting
+
+Here's an example of how to use the `recursive` strategy:
+
+```ts showLineNumbers copy
+const chunks = await doc.chunk({
+  strategy: "recursive",
+  size: 512,
+  overlap: 50,
+  separator: "\n",
+  extract: {
+    metadata: true, // Optionally extract metadata
+  },
+});
+```
+
+**Note:** Metadata extraction may use LLM calls, so ensure your API key is set.
+
+We go deeper into chunking strategies in our [chunk documentation](/docs/reference/rag/chunk.mdx).
+
+## Step 2: Embedding Generation
+
+Transform chunks into embeddings using your preferred provider. Mastra supports many embedding providers, including OpenAI and Cohere:
+
+### Using OpenAI
+
+```ts showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { embedMany } from "ai";
+
+const { embeddings } = await embedMany({
+  model: openai.embedding('text-embedding-3-small'),
+  values: chunks.map(chunk => chunk.text),
+});
+```
+
+### Using Cohere
+
+```ts showLineNumbers copy
+import { cohere } from '@ai-sdk/cohere';
+import { embedMany } from 'ai';
+
+const { embeddings } = await embedMany({
+  model: cohere.embedding('embed-english-v3.0'),
+  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
+
+Embedding models typically output vectors with a fixed number of dimensions (e.g., 1536 for OpenAI's `text-embedding-3-small`). 
+Some models support reducing this dimensionality, which can help:
+- Decrease storage requirements in vector databases
+- Reduce computational costs for similarity searches
+
+Here are some supported models:
+
+OpenAI (text-embedding-3 models):
+  ```ts
+  const { embeddings } = await embedMany({
+    model: openai.embedding('text-embedding-3-small', {
+      dimensions: 256  // Only supported in text-embedding-3 and later
+    }),
+    values: chunks.map(chunk => chunk.text),
+  });
+  ```
+
+Google (text-embedding-004):
+  ```ts
+  const { embeddings } = await embedMany({
+    model: google.textEmbeddingModel('text-embedding-004', {
+      outputDimensionality: 256  // Truncates excessive values from the end
+    }),
+    values: chunks.map(chunk => chunk.text),
+  });
+  ```
+
+## Example: Complete Pipeline
+
+Here's an example showing document processing and embedding generation with both providers:
+
+```ts showLineNumbers copy
+import { embedMany } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { cohere } from "@ai-sdk/cohere";
+
+import { MDocument } from "@mastra/rag";
+
+// Initialize document
+const doc = MDocument.fromText(`
+  Climate change poses significant challenges to global agriculture.
+  Rising temperatures and changing precipitation patterns affect crop yields.
+`);
+
+// Create chunks
+const chunks = await doc.chunk({
+  strategy: "recursive",
+  size: 256,
+  overlap: 50,
+});
+
+// Generate embeddings with OpenAI
+const { embeddings: openAIEmbeddings } = await embedMany({
+  model: openai.embedding('text-embedding-3-small'),
+  values: chunks.map(chunk => chunk.text),
+});
+
+// OR
+
+// Generate embeddings with Cohere
+const { embeddings: cohereEmbeddings } = await embedMany({
+  model: cohere.embedding('embed-english-v3.0'),
+  values: chunks.map(chunk => chunk.text),
+});
+
+// Store embeddings in your vector database
+await vectorStore.upsert({
+  indexName: "embeddings",
+  vectors: embeddings,
+});
+```
+
+##
+For more examples of different chunking strategies and embedding configurations, see:
+
+- [Adjust Chunk Size](/docs/reference/rag/chunk.mdx#adjust-chunk-size)
+- [Adjust Chunk Delimiters](/docs/reference/rag/chunk.mdx#adjust-chunk-delimiters)
+- [Embed Text with Cohere](/docs/reference/rag/embeddings.mdx#using-cohere)