@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/.docs/raw/course/03-agent-memory/04-creating-basic-memory-agent.md

@@ -1,36 +0,0 @@
-# Creating a Basic Memory Agent
-
-Now, let's create a simple agent with memory capabilities. We'll start with the basics and add more advanced features in the following steps.
-
-Create or update your `src/mastra/agents/index.ts` file:
-
-```typescript
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-import { LibSQLStore } from "@mastra/libsql";
-import { openai } from "@ai-sdk/openai";
-
-// Create a basic memory instance
-const memory = new Memory({
-  storage: new LibSQLStore({
-    url: "file:../../memory.db", // relative path from the `.mastra/output` directory
-  }),
-});
-
-// Create an agent with memory
-export const memoryAgent = new Agent({
-  name: "MemoryAgent",
-  instructions: `
-    You are a helpful assistant with memory capabilities.
-    You can remember previous conversations and user preferences.
-    When a user shares information about themselves, acknowledge it and remember it for future reference.
-    If asked about something mentioned earlier in the conversation, recall it accurately.
-  `,
-  model: openai("gpt-4o"), // You can use "gpt-3.5-turbo" if you prefer
-  memory: memory,
-});
-```
-
-In this example, we're creating a basic `Memory` instance without any special configuration. This default configuration will still provide your agent with the ability to remember previous messages in the conversation.
-
-The key part is adding the `memory` property to your agent configuration, which connects the memory instance to your agent.

package/.docs/raw/course/03-agent-memory/05-updating-mastra-export.md

@@ -1,18 +0,0 @@
-# Updating Your Mastra Export
-
-Make sure to update your `src/mastra/index.ts` file to include your new memory agent:
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { memoryAgent } from "./agents";
-
-export const mastra: Mastra = new Mastra({
-  agents: {
-    memoryAgent,
-  },
-});
-```
-
-This step is essential for making your agent available in the Mastra playground. The `mastra` export is the main entry point for your Mastra application, and it needs to include all the agents you want to use.
-
-By adding your `memoryAgent` to the `agents` object in the Mastra configuration, you're registering it with the Mastra system, making it available for use in the playground and other parts of your application.

package/.docs/raw/course/03-agent-memory/07-understanding-memory-threads.md

@@ -1,14 +0,0 @@
-# Managing Conversation History
-
-In this step, we'll learn how to configure conversation history and understand memory threads in Mastra. Conversation history allows your agent to remember recent interactions, which is essential for maintaining context in ongoing conversations.
-
-## Understanding Memory Threads
-
-Mastra organizes memory into threads, which are records that identify specific conversation histories. Each thread uses two important 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_alice`)
-
-These identifiers allow memory to work properly outside of the playground. They help Mastra distinguish between different conversations and users, ensuring that the right memory is associated with the right conversation.
-
-Without these identifiers, your agent would have no way to know which conversation history to retrieve when a user sends a message. The playground handles these identifiers automatically, but you'll need to manage them yourself when using memory in your own applications.

package/.docs/raw/course/03-agent-memory/08-configuring-conversation-history.md

@@ -1,37 +0,0 @@
-# Configuring Conversation History
-
-By default, the `Memory` instance includes the last 10 messages from the current memory thread in each new request. You can customize this by configuring the `lastMessages` option:
-
-```typescript
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
-import { LibSQLStore } from "@mastra/libsql";
-
-// Create a memory instance with custom conversation history settings
-const memory = new Memory({
-  storage: new LibSQLStore({
-    url: "file:../../memory.db",
-  }),
-  options: {
-    lastMessages: 20, // Include the last 20 messages in the context instead of the default 10
-  },
-});
-
-// Create an agent with the configured memory
-export const memoryAgent = new Agent({
-  name: "MemoryAgent",
-  instructions: `
-    You are a helpful assistant with memory capabilities.
-    You can remember previous conversations and user preferences.
-    When a user shares information about themselves, acknowledge it and remember it for future reference.
-    If asked about something mentioned earlier in the conversation, recall it accurately.
-  `,
-  model: openai("gpt-4o"),
-  memory: memory,
-});
-```
-
-The `lastMessages` option controls how many of the most recent messages are included in the agent's context window. This is important because language models have a limited context window size, and including too many messages can push out other important information.
-
-You'll want to balance between having enough context for the agent to understand the conversation and not overwhelming the context window with too much history.

package/.docs/raw/course/03-agent-memory/09-using-memory-in-application.md

@@ -1,19 +0,0 @@
-# Using Memory in Your Application
-
-When using memory in your own application (outside the playground), you need to provide the `resourceId` and `threadId` with each agent call:
-
-```typescript
-// Example of using memory in your application
-const response = await memoryAgent.stream("Hello, my name is Alice.", {
-  resourceId: "user_alice",
-  threadId: "conversation_123",
-});
-```
-
-**Important:** Without these IDs, your agent will not use memory, even if memory is properly configured. The playground handles this for you, but you need to add IDs yourself when using memory in your application.
-
-The `resourceId` should be a unique identifier for the user or entity that owns the conversation. This could be a user ID from your authentication system, an email address, or any other unique identifier.
-
-The `threadId` should be a unique identifier for the specific conversation. This allows a single user to have multiple separate conversations with your agent, each with its own memory thread.
-
-In a real application, you might generate these IDs when a user starts a new conversation and store them in your database or client-side storage to reuse in subsequent requests.

package/.docs/raw/course/03-agent-memory/10-storage-configuration.md

@@ -1,30 +0,0 @@
-# Storage Configuration
-
-Conversation history relies on a storage adapter to persist messages. By default, Mastra uses a LibSQL store that saves messages to a local database. You can configure this or use other storage options:
-
-```typescript
-import { Memory } from "@mastra/memory";
-import { LibSQLStore } from "@mastra/libsql";
-
-const memory = new Memory({
-  // Configure storage
-  storage: new LibSQLStore({
-    config: {
-      url: "file:../../memory.db", // Local database. Relative to the output folder
-    },
-  }),
-  options: {
-    lastMessages: 20,
-  },
-});
-```
-
-Mastra supports several storage options, including:
-
-- LibSQL (default, local SQLite)
-- PostgreSQL
-- Upstash (Redis)
-
-The storage adapter is responsible for persisting memory data, including conversation history and working memory. This allows your agent to remember conversations even after your application restarts.
-
-For development and testing, the default LibSQL store is usually sufficient. For production applications, you might want to use a more robust storage option like PostgreSQL or a cloud-based solution like Upstash.

package/.docs/raw/course/03-agent-memory/12-handling-memory-frontend.md

@@ -1,62 +0,0 @@
-# Handling Memory in Frontend Applications
-
-When building a frontend application that uses Mastra memory, it's important to 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.
-
-Here's a simplified example of how to handle this in a React application:
-
-```tsx
-import { useState } from "react";
-import { memoryAgent } from "./agents";
-
-function ChatApp() {
-  const [messages, setMessages] = useState([]);
-  const [input, setInput] = useState("");
-
-  const handleSendMessage = async () => {
-    // Add user message to UI
-    setMessages([...messages, { role: "user", content: input }]);
-
-    // Only send the newest message to the agent
-    const response = await memoryAgent.stream(input, {
-      resourceId: "user_123",
-      threadId: "conversation_456",
-    });
-
-    // Add agent response to UI
-    setMessages([...messages, { role: "assistant", content: response }]);
-    setInput("");
-  };
-
-  return (
-    <div>
-      {/* Display messages */}
-      <div>
-        {messages.map((msg, index) => (
-          <div key={index}>
-            <strong>{msg.role}:</strong> {msg.content}
-          </div>
-        ))}
-      </div>
-
-      {/* Input for new messages */}
-      <input
-        value={input}
-        onChange={(e) => setInput(e.target.value)}
-        onKeyPress={(e) => e.key === "Enter" && handleSendMessage()}
-      />
-      <button onClick={handleSendMessage}>Send</button>
-    </div>
-  );
-}
-```
-
-This example demonstrates a common pattern for handling memory in a frontend application:
-
-1. Store the conversation messages in the UI state for display purposes
-2. When sending a message to the agent, only send the newest message
-3. Include the `resourceId` and `threadId` with each agent call
-4. Let Mastra handle retrieving and injecting the conversation history
-
-This approach ensures that your agent has access to the conversation history without duplicating messages in the context window.
-
-In the next step, we'll explore semantic recall, which allows your agent to remember information from older conversations that are no longer in the recent history.

package/.docs/raw/course/03-agent-memory/13-vector-store-configuration.md

@@ -1,27 +0,0 @@
-# Vector Store Configuration
-
-In addition to the memory storage adapters, Mastra also provides vector store adapters useful for storing and retrieving vector embeddings. One of these is the `LibSQLVector` adapter, which provides a simple interface for storing and retrieving vector embeddings in a LibSQL vector database.
-
-```typescript
-import { Memory } from "@mastra/memory";
-import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
-
-const memory = new Memory({
-  storage: new LibSQLStore({
-    url: "file:../../memory.db", // relative path from the `.mastra/output` directory
-  }),
-  vector: new LibSQLVector({
-    connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
-  }),
-});
-```
-
-Mastra supports several vector store options, including:
-
-- LibSQL
-- Chroma
-- Pinecone
-- Qdrant
-- Postgres (with pgvector)
-
-The vector store is responsible for storing and retrieving the vector embeddings used for semantic search.

package/.docs/raw/course/03-agent-memory/16-configuring-semantic-recall.md

@@ -1,41 +0,0 @@
-# Configuring Semantic Recall
-
-Let's update our agent with custom semantic recall settings:
-
-```typescript
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
-import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
-
-// Create a memory instance with semantic recall configuration
-const memory = new Memory({
-  storage: new LibSQLStore({
-    url: "file:../../memory.db", // relative path from the `.mastra/output` directory
-  }), // Storage for message history
-  vector: new LibSQLVector({
-    connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
-  }), // Vector database for semantic search
-  embedder: openai.embedding("text-embedding-3-small"), // Embedder for message embeddings
-  options: {
-    lastMessages: 20, // Include the last 20 messages in the context
-    semanticRecall: true, // Enable semantic recall with default settings
-  },
-});
-
-// Create an agent with the configured memory
-export const memoryAgent = new Agent({
-  name: "MemoryAgent",
-  instructions: `
-    You are a helpful assistant with advanced memory capabilities.
-    You can remember previous conversations and user preferences.
-    When a user shares information about themselves, acknowledge it and remember it for future reference.
-    If asked about something mentioned earlier in the conversation, recall it accurately.
-    You can also recall relevant information from older conversations when appropriate.
-  `,
-  model: openai("gpt-4o"),
-  memory: memory,
-});
-```
-
-For semantic recall to work, you need to have a **vector store** configured. You also need to have an **embedder** configured. You may use any `@ai-sdk`-compatible embedding model for this. In this example, we're using OpenAI's `text-embedding-3-small` model.

package/.docs/raw/course/03-agent-memory/18-advanced-configuration-semantic-recall.md

@@ -1,28 +0,0 @@
-# Advanced Configuration of Semantic Recall
-
-We can configure semantic recall in more detail by setting options for the `semanticRecall` option:
-
-```typescript
-const memory = new Memory({
-  storage: new LibSQLStore({
-    url: "file:../../memory.db", // relative path from the `.mastra/output` directory
-  }),
-  vector: new LibSQLVector({
-    connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
-  }),
-  embedder: openai.embedding("text-embedding-3-small"),
-  options: {
-    semanticRecall: {
-      topK: 3,
-      messageRange: {
-        before: 2,
-        after: 1,
-      },
-    },
-  },
-});
-```
-
-The `topK` parameter controls how many semantically similar messages are retrieved. A higher value will retrieve more messages, which can be helpful for complex topics but may also include less relevant information. The default value is `2`.
-
-The `messageRange` parameter controls how much context is included with each match. This is important because the matching message alone might not provide enough context to understand the conversation. Including messages before and after the match helps the agent understand the context of the matched message.

package/.docs/raw/course/03-agent-memory/21-configuring-working-memory.md

@@ -1,63 +0,0 @@
-# Configuring Working Memory
-
-Let's update our agent with working memory capabilities:
-
-```typescript
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
-import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
-
-// Create a memory instance with working memory configuration
-const memory = new Memory({
-  storage: new LibSQLStore({
-    url: "file:../../memory.db", // relative path from the `.mastra/output` directory
-  }), // Storage for message history
-  vector: new LibSQLVector({
-    connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
-  }), // Vector database for semantic search
-  embedder: openai.embedding("text-embedding-3-small"), // Embedder for message embeddings
-  options: {
-    semanticRecall: {
-      topK: 3,
-      messageRange: {
-        before: 2,
-        after: 1,
-      },
-    },
-    workingMemory: {
-      enabled: true,
-    },
-  },
-});
-
-// Create an agent with the configured memory
-export const memoryAgent = new Agent({
-  name: "MemoryAgent",
-  instructions: `
-    You are a helpful assistant with advanced memory capabilities.
-    You can remember previous conversations and user preferences.
-    
-    IMPORTANT: You have access to working memory to store persistent information about the user.
-    When you learn something important about the user, update your working memory.
-    This includes:
-    - Their name
-    - Their location
-    - Their preferences
-    - Their interests
-    - Any other relevant information that would help personalize the conversation
-    
-    Always refer to your working memory before asking for information the user has already provided.
-    Use the information in your working memory to provide personalized responses.
-  `,
-  model: openai("gpt-4o"),
-  memory: memory,
-});
-```
-
-The `workingMemory` configuration has several important options:
-
-- `enabled`: Whether working memory is enabled
-- `template`: A template for the working memory content
-
-The instructions for the agent are also important. They guide the agent on what information to store in working memory and how to use that information when responding to the user.

package/.docs/raw/course/03-agent-memory/22-custom-working-memory-templates.md

@@ -1,89 +0,0 @@
-# Custom Working Memory 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.
-
-Let's update our agent with a custom working memory template:
-
-```typescript
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
-
-// Create a memory instance with a custom working memory template
-const memory = new Memory({
-  storage: new LibSQLStore({
-    url: "file:../../memory.db", // relative path from the `.mastra/output` directory
-  }), // Storage for message history
-  vector: new LibSQLVector({
-    connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
-  }), // Vector database for semantic search
-  embedder: openai.embedding("text-embedding-3-small"), // Embedder for message embeddings
-  options: {
-    semanticRecall: {
-      topK: 3,
-      messageRange: {
-        before: 2,
-        after: 1,
-      },
-    },
-    workingMemory: {
-      enabled: true,
-    },
-    workingMemory: {
-      enabled: true,
-      template: `
-# User Profile
-
-## Personal Info
-
-- Name:
-- Location:
-- Timezone:
-
-## Preferences
-
-- Communication Style: [e.g., Formal, Casual]
-- Interests:
-- Favorite Topics:
-
-## Session State
-
-- Current Topic:
-- Open Questions:
-  - [Question 1]
-  - [Question 2]
-`,
-    },
-  },
-});
-
-// Create an agent with the configured memory
-export const memoryAgent = new Agent({
-  name: "MemoryAgent",
-  instructions: `
-    You are a helpful assistant with advanced memory capabilities.
-    You can remember previous conversations and user preferences.
-    
-    IMPORTANT: You have access to working memory to store persistent information about the user.
-    When you learn something important about the user, update your working memory according to the template.
-    
-    Always refer to your working memory before asking for information the user has already provided.
-    Use the information in your working memory to provide personalized responses.
-    
-    When the user shares personal information such as their name, location, or preferences,
-    acknowledge it and update your working memory accordingly.
-  `,
-  model: openai("gpt-4o"),
-  memory: memory,
-});
-```
-
-The template is a Markdown document that defines the structure of the working memory. It includes sections for different types of information, such as personal info, preferences, and session state.
-
-The template serves several important purposes:
-
-1. It guides the agent on what information to track and how to organize it
-2. It provides a consistent structure for the working memory across conversations
-3. It makes it easier for the agent to find and update specific pieces of information
-
-You should design your template based on the specific needs of your agent and the type of information it needs to remember about users or tasks.

package/.docs/raw/course/03-agent-memory/25-combining-memory-features.md

@@ -1,80 +0,0 @@
-# Building a Complete Memory-Enhanced Agent
-
-In this final step, we'll bring together all the memory features we've explored to create a complete memory-enhanced agent. We'll also create a practical example that demonstrates how these features work together.
-
-## Combining All Memory Features
-
-Let's create a comprehensive agent that utilizes conversation history, semantic recall, and working memory:
-
-```typescript
-// src/mastra/agents/memory-agent.ts
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
-import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
-
-// Create a comprehensive memory configuration
-const memory = new Memory({
-  storage: new LibSQLStore({
-    url: "file:../../memory.db", // relative path from the `.mastra/output` directory
-  }),
-  vector: new LibSQLVector({
-    connectionUrl: "file:../../vector.db", // relative path from the `.mastra/output` directory
-  }),
-  embedder: openai.embedding("text-embedding-3-small"),
-  options: {
-    // Conversation history configuration
-    lastMessages: 20, // Include the last 20 messages in the context
-
-    // Semantic recall configuration
-    semanticRecall: {
-      topK: 3, // Retrieve 3 most similar messages
-      messageRange: {
-        before: 2, // Include 2 messages before each match
-        after: 1, // Include 1 message after each match
-      },
-    },
-
-    // Working memory configuration
-    workingMemory: {
-      enabled: true,
-      template: `
-# User Profile
-
-## Personal Info
-- Name:
-- Location:
-- Timezone:
-- Occupation:
-
-## Preferences
-- Communication Style:
-- Topics of Interest:
-- Learning Goals:
-
-## Project Information
-- Current Projects:
-  - [Project 1]:
-    - Deadline:
-    - Status:
-  - [Project 2]:
-    - Deadline:
-    - Status:
-
-## Session State
-- Current Topic:
-- Open Questions:
-- Action Items:
-`,
-    },
-  },
-});
-```
-
-This comprehensive memory configuration combines all three memory features we've explored:
-
-1. **Conversation history** with the `lastMessages` option
-2. **Semantic recall** with the `semanticRecall` option
-3. **Working memory** with the `workingMemory` option
-
-Each feature serves a different purpose in enhancing your agent's memory capabilities, and together they create a powerful memory system that can maintain context across conversations and provide personalized responses.

package/.docs/raw/course/03-agent-memory/26-updating-mastra-export-comprehensive.md

@@ -1,32 +0,0 @@
-# Updating Your Mastra Export
-
-Make sure to update your `src/mastra/index.ts` file to include your new comprehensive memory agent:
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { memoryMasterAgent } from "./agents/memory-agent";
-
-export const mastra: Mastra = new Mastra({
-  agents: {
-    memoryMasterAgent,
-  },
-});
-```
-
-This step is essential for making your comprehensive memory agent available in the Mastra playground. The `mastra` export is the main entry point for your Mastra application, and it needs to include all the agents you want to use.
-
-By adding your `memoryMasterAgent` to the `agents` object in the Mastra configuration, you're registering it with the Mastra system, making it available for use in the playground and other parts of your application.
-
-If you have multiple agents, you can include them all in the `agents` object:
-
-```typescript
-export const mastra: Mastra = new Mastra({
-  agents: {
-    memoryMasterAgent,
-    learningAssistantAgent,
-    // Other agents...
-  },
-});
-```
-
-This allows you to switch between different agents in the playground, each with its own specialized memory configuration and capabilities.