@mastra/mcp-docs-server 0.0.6 → 0.0.7

package/.docs/raw/agents/agent-memory.mdx

@@ -5,613 +5,62 @@ description: Documentation on how agents in Mastra use memory to store conversat
 
 # Agent Memory
 
-Agents in Mastra have a sophisticated memory system that stores conversation history and contextual information. This memory system supports both traditional message storage and vector-based semantic search, enabling agents to maintain state across interactions and retrieve relevant historical context.
+Agents in Mastra can leverage a powerful memory system to store conversation history, recall relevant information, and maintain persistent context across interactions. This allows agents to have more natural, stateful conversations.
 
-## Threads and Resources
+## Enabling Memory for an Agent
 
-In Mastra, you can organize conversations by a `thread_id`. This allows the system to maintain context and retrieve historical messages that belong to the same discussion.
+To enable memory, simply instantiate the `Memory` class and pass it to your agent's configuration. You also need to install the memory package:
 
-Mastra also supports the concept of a `resource_id`, which typically represents the user involved in the conversation, ensuring that the agent's memory and context are correctly associated with the right entity.
-
-This separation allows you to manage multiple conversations (threads) for a single user or even share conversation context across users if needed.
-
-```typescript copy showLineNumbers
-import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
-
-const agent = new Agent({
-  name: "Project Manager",
-  instructions:
-    "You are a project manager. You are responsible for managing the project and the team.",
-  model: openai("gpt-4o-mini"),
-});
-
-await agent.stream("When will the project be completed?", {
-  threadId: "project_123",
-  resourceId: "user_123",
-});
-```
-
-## Managing Conversation Context
-
-The key to getting good responses from LLMs is feeding them the right context.
-
-Mastra has a Memory API that stores and manages conversation history and contextual information. The Memory API uses a storage backend to persist conversation history and contextual information (more on this later).
-
-The Memory API uses two main mechanisms to maintain context in conversations, recent message history and semantic search.
-
-### Recent Message History
-
-By default, Memory keeps track of the 40 most recent messages in a conversation. You can customize this with the `lastMessages` setting:
-
-```typescript copy showLineNumbers
-const memory = new Memory({
-  options: {
-    lastMessages: 5, // Keep 5 most recent messages
-  },
-});
-
-// When user asks this question, the agent will see the last 10 messages,
-await agent.stream("Can you summarize the search feature requirements?", {
-  memoryOptions: {
-    lastMessages: 10,
-  },
-});
-```
-
-### Semantic Search
-
-Semantic search is enabled by default in Mastra. While FastEmbed (bge-small-en-v1.5) and LibSQL are included by default, you can use any embedder (like OpenAI or Cohere) and vector database (like PostgreSQL, Pinecone, or Chroma) that fits your needs.
-
-This allows your agent to find and recall relevant information from earlier in the conversation:
-
-```typescript copy showLineNumbers
-const memory = new Memory({
-  options: {
-    semanticRecall: {
-      topK: 10, // Include 10 most relevant past messages
-      messageRange: 2, // Messages before and after each result
-    },
-  },
-});
-
-// Example: User asks about a past feature discussion
-await agent.stream("What did we decide about the search feature last week?", {
-  memoryOptions: {
-    lastMessages: 10,
-    semanticRecall: {
-      topK: 3,
-      messageRange: 2,
-    },
-  },
-});
+```bash npm2yarn copy
+npm install @mastra/memory
 ```
 
-When semantic search is used:
-
-1. The message is converted to a vector embedding
-2. Similar messages are found using vector similarity search
-3. Surrounding context is included based on `messageRange`
-4. All relevant context is provided to the agent
-
-You can also customize the vector database and embedder:
-
-```typescript copy showLineNumbers
-import { openai } from "@ai-sdk/openai";
-import { PgVector } from "@mastra/pg";
-
-const memory = new Memory({
-  // Use a different vector database (libsql is default)
-  vector: new PgVector("postgresql://user:pass@localhost:5432/db"),
-  // Or a different embedder (fastembed is default)
-  embedder: openai.embedding("text-embedding-3-small"),
-});
-```
-
-## Memory Configuration
-
-The Mastra memory system is highly configurable and supports multiple storage backends. By default, it uses LibSQL for storage and vector search, and FastEmbed for embeddings.
-
-### Basic Configuration
-
-For most use cases, you can use the default configuration:
-
-```typescript copy showLineNumbers
+```typescript
+import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
+import { openai } from "@ai-sdk/openai";
 
+// Basic memory setup
 const memory = new Memory();
-```
-
-### Custom Configuration
-
-For more control, you can customize the storage backend, vector database, and memory options:
-
-```typescript copy showLineNumbers
-import { Memory } from "@mastra/memory";
-import { PostgresStore, PgVector } from "@mastra/pg";
-
-const memory = new Memory({
-  storage: new PostgresStore({
-    host: "localhost",
-    port: 5432,
-    user: "postgres",
-    database: "postgres",
-    password: "postgres",
-  }),
-  vector: new PgVector("postgresql://user:pass@localhost:5432/db"),
-  options: {
-    // Number of recent messages to include (false to disable)
-    lastMessages: 10,
-    // Configure vector-based semantic search (false to disable)
-    semanticRecall: {
-      topK: 3, // Number of semantic search results
-      messageRange: 2, // Messages before and after each result
-    },
-  },
-});
-```
-
-### Overriding Memory Settings
-
-When you initialize a Mastra instance with memory configuration, all agents will automatically use these memory settings when you call their `stream()` or `generate()` methods. You can override these default settings for individual calls:
-
-```typescript copy showLineNumbers
-// Use default memory settings from Memory configuration
-const response1 = await agent.generate("What were we discussing earlier?", {
-  resourceId: "user_123",
-  threadId: "thread_456",
-});
-
-// Override memory settings for this specific call
-const response2 = await agent.generate("What were we discussing earlier?", {
-  resourceId: "user_123",
-  threadId: "thread_456",
-  memoryOptions: {
-    lastMessages: 5, // Only inject 5 recent messages
-    semanticRecall: {
-      topK: 2, // Only get 2 semantic search results
-      messageRange: 1, // Context around each result
-    },
-  },
-});
-```
-
-### Configuring Memory for Different Use Cases
-
-You can adjust memory settings based on your agent's needs:
-
-```typescript copy showLineNumbers
-// Customer support agent with minimal context
-await agent.stream("What are your store hours?", {
-  threadId,
-  resourceId,
-  memoryOptions: {
-    lastMessages: 5, // Quick responses need minimal conversation history
-    semanticRecall: false, // no need to search through earlier messages
-  },
-});
-
-// Project management agent with extensive context
-await agent.stream("Update me on the project status", {
-  threadId,
-  resourceId,
-  memoryOptions: {
-    lastMessages: 50, // Maintain longer conversation history across project discussions
-    semanticRecall: {
-      topK: 5, // Find more relevant project details
-      messageRange: 3, // Number of messages before and after each result
-    },
-  },
-});
-```
-
-## Storage Options
-
-Mastra currently supports several storage backends:
-
-### LibSQL Storage
-
-```typescript copy showLineNumbers
-import { LibSQLStore } from "@mastra/core/storage/libsql";
-
-const storage = new LibSQLStore({
-  config: {
-    url: "file:example.db",
-  },
-});
-```
-
-### PostgreSQL Storage
-
-```typescript copy showLineNumbers
-import { PostgresStore } from "@mastra/pg";
-
-const storage = new PostgresStore({
-  host: "localhost",
-  port: 5432,
-  user: "postgres",
-  database: "postgres",
-  password: "postgres",
-});
-```
-
-### Upstash KV Storage
-
-```typescript copy showLineNumbers
-import { UpstashStore } from "@mastra/upstash";
-
-const storage = new UpstashStore({
-  url: "http://localhost:8089",
-  token: "your_token",
-});
-```
-
-## Vector Search
-
-Mastra supports semantic search through vector embeddings. When configured with a vector store, agents can find relevant historical messages based on semantic similarity. To enable vector search:
-
-1. Configure a vector store (currently supports PostgreSQL):
-
-```typescript copy showLineNumbers
-import { PgVector } from "@mastra/pg";
-
-const vector = new PgVector(connectionString);
-
-const memory = new Memory({ vector });
-```
-
-2. Configure embedding options:
-
-```typescript copy showLineNumbers
-const memory = new Memory({
-  vector,
-  embedder: openai.embedding("text-embedding-3-small"),
-});
-```
-
-3. Enable vector search in memory configuration options:
-
-```typescript copy showLineNumbers
-const memory = new Memory({
-  vector,
-  embedder,
-
-  options: {
-    semanticRecall: {
-      topK: 3, // Number of similar messages to find
-      messageRange: 2, // Context around each result
-    },
-  },
-});
-```
-
-## Using Memory in Agents
-
-Once configured, the memory system is automatically used by agents. Here's how to use it:
-
-```typescript copy showLineNumbers
-// Initialize Agent with memory
-const myAgent = new Agent({
-  memory,
-  // other agent options
-});
-// Add agent to mastra
-const mastra = new Mastra({
-  agents: { myAgent },
-});
-
-// Memory is automatically used in agent interactions when resourceId and threadId are added
-const response = await myAgent.generate(
-  "What were we discussing earlier about performance?",
-  {
-    resourceId: "user_123",
-    threadId: "thread_456",
-  },
-);
-```
-
-The memory system will automatically:
-
-1. Store all messages in the configured storage backend
-2. Create vector embeddings for semantic search (if configured)
-3. Inject relevant historical context into new conversations
-4. Maintain conversation threads and context
-
-## useChat()
-
-When using `useChat` from the AI SDK, you must send only the latest message or you will encounter message ordering bugs.
-
-If the `useChat()` implementation for your framework supports `experimental_prepareRequestBody`, you can do the following:
-
-```ts
-const { messages } = useChat({
-  api: "api/chat",
-  experimental_prepareRequestBody({ messages, id }) {
-    return { message: messages.at(-1), id };
-  },
-});
-```
-
-This will only ever send the latest message to the server.
-In your chat server endpoint you can then pass a threadId and resourceId when calling stream or generate and the agent will have access to the memory thread messages:
-
-```ts
-const { messages } = await request.json();
-
-const stream = await myAgent.stream(messages, {
-  threadId,
-  resourceId,
-});
-
-return stream.toDataStreamResponse();
-```
-
-If the `useChat()` for your framework (svelte for example) doesn't support `experimental_prepareRequestBody`, you can pick and use the last message before calling stream or generate:
-
-```ts
-const { messages } = await request.json();
-
-const stream = await myAgent.stream([messages.at(-1)], {
-  threadId,
-  resourceId,
-});
-
-return stream.toDataStreamResponse();
-```
-
-See the [AI SDK documentation on message persistence](https://sdk.vercel.ai/docs/ai-sdk-ui/chatbot-message-persistence) for more information.
-
-## Manually Managing Threads
-
-While threads are automatically managed when using agent methods, you can also manually manage threads using the memory API directly. This is useful for advanced use cases like:
-
-- Creating threads before starting conversations
-- Managing thread metadata
-- Explicitly saving or retrieving messages
-- Cleaning up old threads
-
-Here's how to manually work with threads:
-
-```typescript copy showLineNumbers
-import { Memory } from "@mastra/memory";
-import { PostgresStore } from "@mastra/pg";
-
-// Initialize memory
-const memory = new Memory({
-  storage: new PostgresStore({
-    host: "localhost",
-    port: 5432,
-    user: "postgres",
-    database: "postgres",
-    password: "postgres",
-  }),
-});
-
-// Create a new thread
-const thread = await memory.createThread({
-  resourceId: "user_123",
-  title: "Project Discussion",
-  metadata: {
-    project: "mastra",
-    topic: "architecture",
-  },
-});
-
-// Manually save messages to a thread
-await memory.saveMessages({
-  messages: [
-    {
-      id: "msg_1",
-      threadId: thread.id,
-      role: "user",
-      content: "What's the project status?",
-      createdAt: new Date(),
-      type: "text",
-    },
-  ],
-});
-
-// Get messages from a thread with various filters
-const messages = await memory.query({
-  threadId: thread.id,
-  selectBy: {
-    last: 10, // Get last 10 messages
-    vectorSearchString: "performance", // Find messages about performance
-  },
-});
-
-// Get thread by ID
-const existingThread = await memory.getThreadById({
-  threadId: "thread_123",
-});
-
-// Get all threads for a resource
-const threads = await memory.getThreadsByResourceId({
-  resourceId: "user_123",
-});
-
-// Update thread metadata
-await memory.updateThread({
-  id: thread.id,
-  title: "Updated Project Discussion",
-  metadata: {
-    status: "completed",
-  },
-});
-
-// Delete a thread and all its messages
-await memory.deleteThread(thread.id);
-```
-
-Note that in most cases, you won't need to manage threads manually since the agent's `generate()` and `stream()` methods handle thread management automatically. Manual thread management is primarily useful for advanced use cases or when you need more fine-grained control over the conversation history.
-
-## Working Memory
-
-Working memory is a powerful feature that allows agents to maintain persistent information across conversations, even with minimal context. This is particularly useful for remembering user preferences, personal details, or any other contextual information that should persist throughout interactions.
-
-Inspired by the working memory concept from the MemGPT whitepaper, our implementation improves upon it in several key ways:
-
-- No extra roundtrips or tool calls required
-- Full support for streaming messages
-- Seamless integration with the agent's natural response flow
-
-#### How It Works
-
-Working memory operates through a system of organized data and automatic updates:
-
-1. **Template Structure**: Define what information should be remembered using Markdown. The Memory class comes with a comprehensive default template for user information, or you can create your own template to match your specific needs.
-
-2. **Automatic Updates**: The Memory class injects special instructions into the agent's system prompt that tell it to:
-
-   - Store relevant information by including `<working_memory>...</working_memory>` tags in its responses
-   - Update information proactively when anything changes
-   - Maintain the Markdown structure while updating values
-   - Keep this process invisible to users
-
-3. **Memory Management**: The system:
-   - Extracts working memory blocks from agent responses
-   - Stores them for future use
-   - Injects working memory into the system prompt on the next agent call
-
-The agent is instructed to be proactive about storing information - if there's any doubt about whether something might be useful later, it should be stored. This helps maintain conversation context even when using very small context windows.
-
-#### Basic Usage
-
-```typescript copy showLineNumbers
-import { openai } from "@ai-sdk/openai";
 
 const agent = new Agent({
-  name: "Customer Service",
-  instructions:
-    "You are a helpful customer service agent. Remember customer preferences and past interactions.",
-  model: openai("gpt-4o-mini"),
-
-  memory: new Memory({
-    options: {
-      workingMemory: {
-        enabled: true, // enables working memory
-      },
-      lastMessages: 5, // Only keep recent context
-    },
-  }),
-});
-```
-
-Working memory becomes particularly powerful when combined with specialized system prompts. For example, you could create a TODO list manager that maintains state even though it only has access to the previous message:
-
-```typescript copy showLineNumbers
-const todoAgent = new Agent({
-  name: "TODO Manager",
-  instructions:
-    "You are a TODO list manager. Update the todo list in working memory whenever tasks are added, completed, or modified.",
-  model: openai("gpt-4o-mini"),
-  memory: new Memory({
-    options: {
-      workingMemory: {
-        enabled: true,
-
-        // optional Markdown template to encourage agent to store specific kinds of info.
-        // if you leave this out a default template will be used
-        template: `# Todo List
-## In Progress
-- 
-## Pending
-- 
-## Completed
-- 
-`,
-      },
-      lastMessages: 1, // Only keep the last message in context
-    },
-  }),
+  name: "MyMemoryAgent",
+  instructions: "You are a helpful assistant with memory.",
+  model: openai("gpt-4o"),
+  memory: memory, // Attach the memory instance
 });
 ```
 
-### Handling Memory Updates in Streaming
-
-When an agent responds, it includes working memory updates directly in its response stream. These updates appear as tagged blocks in the text:
-
-```typescript copy showLineNumbers
-// Raw agent response stream:
-Let me help you with that! <working_memory># User Information
-- **First Name**: John
-- **Last Name**:
-- **Location**:
-...</working_memory> Based on your question...
-```
-
-To prevent these memory blocks from being visible to users while still allowing the system to process them, use the `maskStreamTags` utility:
+This basic setup uses default settings, including LibSQL for storage and FastEmbed for embeddings. For detailed setup instructions, see the [Memory Getting Started guide](/docs/memory/getting-started).
 
-```typescript copy showLineNumbers
-import { maskStreamTags } from "@mastra/core/utils";
+## Using Memory in Agent Calls
 
-// Basic usage - just mask the working_memory tags
-for await (const chunk of maskStreamTags(
-  response.textStream,
-  "working_memory",
-)) {
-  process.stdout.write(chunk);
-}
+To utilize memory during interactions, you **must** provide `resourceId` and `threadId` when calling the agent's `stream()` or `generate()` methods.
 
-// Without masking: "Let me help you! <working_memory>...</working_memory> Based on..."
-// With masking: "Let me help you! Based on..."
-```
+- `resourceId`: Typically identifies the user or entity (e.g., `user_123`).
+- `threadId`: Identifies a specific conversation thread (e.g., `support_chat_456`).
 
-You can also hook into memory update events:
+```typescript
+// Example agent call using memory
+await agent.stream("Remember my favorite color is blue.", {
+  resourceId: "user_alice",
+  threadId: "preferences_thread",
+});
 
-```typescript copy showLineNumbers
-const maskedStream = maskStreamTags(response.textStream, "working_memory", {
-  onStart: () => showLoadingSpinner(),
-  onEnd: () => hideLoadingSpinner(),
-  onMask: (chunk) => console.debug(chunk),
+// Later in the same thread...
+const response = await agent.stream("What's my favorite color?", {
+  resourceId: "user_alice",
+  threadId: "preferences_thread",
 });
+// Agent will use memory to recall the favorite color.
 ```
 
-The `maskStreamTags` utility:
-
-- Removes content between specified XML tags in a streaming response
-- Optionally provides lifecycle callbacks for memory updates
-- Handles tags that might be split across stream chunks
-
-### Accessing Thread and Resource IDs in Tools
+These IDs ensure that conversation history and context are correctly stored and retrieved for the appropriate user and conversation.
 
-When creating custom tools, you can access the `threadId` and `resourceId` directly in the tool's execute function. These parameters are automatically provided by the Mastra runtime:
-
-```typescript copy showLineNumbers
-import { Memory } from "@mastra/memory";
-const memory = new Memory();
+## Next Steps
 
-const myTool = createTool({
-  id: "Thread Info Tool",
-  inputSchema: z.object({
-    fetchMessages: z.boolean().optional(),
-  }),
-  description: "A tool that demonstrates accessing thread and resource IDs",
-  execute: async ({ threadId, resourceId, context }) => {
-    // threadId and resourceId are directly available in the execute parameters
-    console.log(`Executing in thread ${threadId}`);
-
-    if (!context.fetchMessages) {
-      return { threadId, resourceId };
-    }
-
-    const recentMessages = await memory.query({
-      threadId,
-      selectBy: { last: 5 },
-    });
-
-    return {
-      threadId,
-      resourceId,
-      messageCount: recentMessages.length,
-    };
-  },
-});
-```
+Explore Mastra's memory capabilities further:
 
-This allows tools to:
+- **[Getting Started](/docs/memory/getting-started)**: Learn how to add basic memory to your agents.
+- **[Memory Features](/docs/memory/overview)**: Understand core features like Threads, Conversation History, Semantic Recall, Working Memory, Tools & Memory interaction, and Frontend Integration.
 
-- Access the current conversation context
-- Store or retrieve thread-specific data
-- Associate tool actions with specific users/resources
-- Maintain state across multiple tool invocations

package/.docs/raw/deployment/server.mdx

@@ -65,6 +65,25 @@ export const mastra = new Mastra({
 });
 ```
 
+## Custom CORS Config
+
+Mastra allows you to configure CORS (Cross-Origin Resource Sharing) settings for your server.
+
+```typescript copy showLineNumbers
+import { Mastra } from '@mastra/core';
+
+export const mastra = new Mastra({
+  server: {
+    cors: {
+      origin: ['https://example.com'], // Allow specific origins or '*' for all
+      allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+      allowHeaders: ['Content-Type', 'Authorization'],
+      credentials: false,
+    }
+  }
+});
+```
+
 ## Middleware
 
 Mastra allows you to configure custom middleware functions that will be applied to API routes. This is useful for adding authentication, logging, CORS, or other HTTP-level functionality to your API endpoints.