@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-esbuild-bundle-worker-20260807182016

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

@@ -0,0 +1,73 @@
+# Advanced configuration of semantic recall
+
+Configure semantic recall with the `semanticRecall` option:
+
+```typescript
+const memory = new Memory({
+  storage: new LibSQLStore({
+    id: 'learning-memory-storage',
+    url: 'file:../../memory.db', // relative path from the `.mastra/output` directory
+  }),
+  vector: new LibSQLVector({
+    url: '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,
+      },
+      scope: 'resource', // Search all threads for this resource
+      filter: { projectId: { $eq: 'project-a' } },
+    },
+  },
+})
+```
+
+The `topK` parameter controls how many similar messages Mastra retrieves. A higher value retrieves more messages, which can help with complex topics but may include less relevant information. The default value is `4`.
+
+The `messageRange` parameter controls how much context Mastra includes with each match. Messages before and after the match help the agent understand the matched message.
+
+The `scope` parameter controls whether Mastra searches the current thread (`'thread'`) or all threads owned by a resource (`'resource'`). Use `scope: 'resource'` to let the agent recall information from past conversations for the same resource.
+
+The `filter` parameter restricts semantic recall results to messages with matching thread metadata, such as a project ID or category.
+
+Filters match metadata stored on message embeddings when messages are saved. If thread metadata changes later, existing embeddings keep their previous metadata until those messages are saved or indexed again.
+
+Supported filter operators:
+
+- `$and`: Logical AND
+- `$eq`: Equal to
+- `$gt`: Greater than
+- `$gte`: Greater than or equal
+- `$in`: In array
+- `$lt`: Less than
+- `$lte`: Less than or equal
+- `$ne`: Not equal to
+- `$nin`: Not in array
+- `$or`: Logical OR
+
+The following example demonstrates metadata filters for common use cases:
+
+```typescript
+// Filter by project
+const options = {
+  semanticRecall: { filter: { projectId: { $eq: 'my-project' } } },
+}
+
+// Filter by multiple categories
+const options = {
+  semanticRecall: { filter: { category: { $in: ['work', 'research'] } } },
+}
+
+// Filter by project and priority
+const options = {
+  semanticRecall: {
+    filter: {
+      $and: [{ projectId: { $eq: 'project-a' } }, { priority: { $gte: 3 } }],
+    },
+  },
+}
+```

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

@@ -0,0 +1,64 @@
+# 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 { LibSQLStore, LibSQLVector } from '@mastra/libsql'
+
+// Create a memory instance with working memory configuration
+const memory = new Memory({
+  storage: new LibSQLStore({
+    id: 'learning-memory-storage',
+    url: 'file:../../memory.db', // relative path from the `.mastra/output` directory
+  }), // Storage for message history
+  vector: new LibSQLVector({
+    id: 'learning-memory-vector',
+    url: 'file:../../vector.db', // relative path from the `.mastra/output` directory
+  }), // Vector database for semantic search
+  embedder: 'openai/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-5.4',
+  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/course/03-agent-memory/22-custom-working-memory-templates.md

@@ -0,0 +1,89 @@
+# 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'
+
+// Create a memory instance with a custom working memory template
+const memory = new Memory({
+  storage: new LibSQLStore({
+    id: 'learning-memory-storage',
+    url: 'file:../../memory.db', // relative path from the `.mastra/output` directory
+  }), // Storage for message history
+  vector: new LibSQLVector({
+    url: 'file:../../vector.db', // relative path from the `.mastra/output` directory
+  }), // Vector database for semantic search
+  embedder: 'openai/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-5.4',
+  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/course/03-agent-memory/25-combining-memory-features.md

@@ -0,0 +1,80 @@
+# 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 { LibSQLStore, LibSQLVector } from '@mastra/libsql'
+
+// Create a comprehensive memory configuration
+const memory = new Memory({
+  storage: new LibSQLStore({
+    id: 'learning-memory-storage',
+    url: 'file:../../memory.db', // relative path from the `.mastra/output` directory
+  }),
+  vector: new LibSQLVector({
+    url: 'file:../../vector.db', // relative path from the `.mastra/output` directory
+  }),
+  embedder: 'openai/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 memory system that maintains context across conversations and provides personalized responses.

package/.docs/course/03-agent-memory/27-creating-learning-assistant.md

@@ -0,0 +1,103 @@
+# Creating a Practical Example: Personal Learning Assistant
+
+Let's create a practical example of a memory-enhanced agent: a Personal Learning Assistant that helps users learn new skills and tracks their progress.
+
+```typescript
+// src/mastra/agents/learning-assistant.ts
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { LibSQLStore, LibSQLVector } from '@mastra/libsql'
+
+// Create a specialized memory configuration for the learning assistant
+const learningMemory = new Memory({
+  storage: new LibSQLStore({
+    id: 'learning-memory-storage',
+    url: 'file:../../memory.db', // relative path from the `.mastra/output` directory
+  }),
+  vector: new LibSQLVector({
+    url: 'file:../../vector.db', // relative path from the `.mastra/output` directory
+  }),
+  embedder: 'openai/text-embedding-3-small',
+  options: {
+    lastMessages: 20,
+    semanticRecall: {
+      topK: 3,
+      messageRange: {
+        before: 2,
+        after: 1,
+      },
+    },
+    workingMemory: {
+      enabled: true,
+      template: `
+# Learner Profile
+
+## Personal Info
+- Name:
+- Learning Style: [Visual, Auditory, Reading/Writing, Kinesthetic]
+
+## Learning Journey
+- Current Topics:
+  - [Topic 1]:
+    - Skill Level: [Beginner, Intermediate, Advanced]
+    - Started: [Date]
+    - Goals:
+    - Resources:
+    - Progress Notes:
+  - [Topic 2]:
+    - Skill Level: [Beginner, Intermediate, Advanced]
+    - Started: [Date]
+    - Goals:
+    - Resources:
+    - Progress Notes:
+
+## Session State
+- Current Focus:
+- Questions to Revisit:
+- Recommended Next Steps:
+`,
+    },
+  },
+})
+
+// Create the learning assistant agent
+export const learningAssistantAgent = new Agent({
+  name: 'Learning Assistant',
+  instructions: `
+    You are a personal learning assistant that helps users learn new skills and tracks their progress.
+    
+    ## Your Capabilities
+    
+    - You help users set learning goals and track their progress
+    - You provide explanations and resources tailored to their skill level
+    - You remember what topics they're learning and their progress in each
+    - You adapt your teaching style to match their learning preferences
+    
+    ## Guidelines for Using Memory
+    
+    - When the user shares information about their learning style or preferences,
+      update your working memory.
+    
+    - When the user asks about a topic they've mentioned before, use your semantic
+      recall to provide continuity in your teaching.
+    
+    - When explaining concepts, check your working memory to understand their
+      current skill level and provide an explanation at the appropriate depth.
+    
+    Always be encouraging and supportive. Focus on building the user's confidence
+    and celebrating their progress.
+  `,
+  model: 'openai/gpt-5.4',
+  memory: learningMemory,
+})
+
+// Don't forget to export this agent in your src/mastra/index.ts file
+```
+
+This example demonstrates how to create a specialized agent with a memory configuration tailored to a specific use case. The Learning Assistant uses:
+
+1. A custom working memory template designed to track learning progress
+2. Specialized instructions that guide the agent on how to use memory for educational purposes
+3. All three memory features (conversation history, semantic recall, and working memory) working together
+
+This type of specialized agent can provide a much more personalized and effective learning experience compared to a generic chatbot without memory capabilities.

package/.docs/course/04-workflows/01-introduction-to-workflows.md

@@ -0,0 +1,44 @@
+# Introduction to Workflows
+
+Welcome to the fourth lesson of the Mastra course! In this lesson, you'll learn about Mastra Workflows - a powerful way to orchestrate complex sequences of operations.
+
+## What are Workflows?
+
+Workflows in Mastra let you chain together multiple operations in a predictable, type-safe manner. Think of them as a recipe that breaks down complex tasks into smaller, manageable steps.
+
+Instead of writing one big function that does everything, workflows let you:
+
+- Break complex operations into smaller, reusable steps
+- Define clear inputs and outputs for each step
+- Chain steps together with automatic data validation
+- Handle errors gracefully at each step
+
+## Simple Example
+
+Without workflows, you might write:
+
+```typescript
+async function processContent(text: string) {
+  // All logic in one function - hard to test and reuse
+  const validated = validateText(text)
+  const enhanced = enhanceText(validated)
+  const summarized = summarizeText(enhanced)
+  return summarized
+}
+```
+
+With workflows, the same logic becomes modular and reusable with tracing built in at every step.
+
+```typescript
+export const contentWorkflow = createWorkflow({...})
+  .then(validateStep)
+  .then(enhanceStep)
+  .then(summarizeStep)
+  .commit();
+```
+
+## What You'll Build
+
+In this lesson, you'll create a content processing workflow that validates, enhances, and summarizes text content using multiple connected steps.
+
+Let's start by understanding the basic building blocks!

package/.docs/course/04-workflows/02-understanding-steps.md

@@ -0,0 +1,53 @@
+# Understanding Steps
+
+Steps are the building blocks of workflows. Each step is a self-contained unit that takes some input, processes it, and produces an output.
+
+## What is a Step?
+
+A step has three main parts:
+
+1. **Input Schema** - what data it expects to receive
+2. **Output Schema** - what data it will produce
+3. **Execute Function** - the logic that transforms input to output
+
+## Step Structure
+
+Every step follows this pattern:
+
+```typescript
+const myStep = createStep({
+  id: 'unique-step-name',
+  description: 'What this step does',
+  inputSchema: z.object({
+    // Define expected input structure
+  }),
+  outputSchema: z.object({
+    // Define output structure
+  }),
+  execute: async ({ inputData }) => {
+    // Your logic here
+    return {
+      // Return data matching output schema
+    }
+  },
+})
+```
+
+## Why Use Schemas?
+
+Schemas provide several benefits:
+
+- **Type Safety**: TypeScript knows exactly what data flows between steps
+- **Runtime Validation**: Invalid data is caught immediately with helpful error messages
+- **Documentation**: Schemas serve as living documentation of your workflow
+- **Debugging**: Clear contracts make it easy to identify issues
+
+## Key Benefits
+
+- **Reusable**: Steps can be used in multiple workflows
+- **Testable**: Each step can be tested in isolation
+- **Composable**: Steps can be combined in different ways
+- **Reliable**: Schemas catch data flow issues early
+- **Traceable**: Every step is traced so you can see the flow of data
+
+Next, you'll create your first step!

package/.docs/course/04-workflows/03-creating-your-first-step.md

@@ -0,0 +1,57 @@
+# Creating Your First Step
+
+Let's create your first workflow step! We'll build a step that validates text content.
+
+## Setting Up
+
+First, create a new file for your workflow in the `src/mastra/workflows` directory. Let's name this file `content-workflow.ts`
+
+## Creating a Validation Step
+
+Add this code to your workflow file:
+
+```typescript
+import { createStep } from '@mastra/core/workflows'
+import { z } from 'zod'
+
+const validateContentStep = createStep({
+  id: 'validate-content',
+  description: 'Validates incoming text content',
+  inputSchema: z.object({
+    content: z.string().min(1, 'Content cannot be empty'),
+    type: z.enum(['article', 'blog', 'social']).default('article'),
+  }),
+  outputSchema: z.object({
+    content: z.string(),
+    type: z.string(),
+    wordCount: z.number(),
+    isValid: z.boolean(),
+  }),
+  execute: async ({ inputData }) => {
+    const { content, type } = inputData
+
+    const wordCount = content.trim().split(/\s+/).length
+    const isValid = wordCount >= 5 // Minimum 5 words
+
+    if (!isValid) {
+      throw new Error(`Content too short: ${wordCount} words`)
+    }
+
+    return {
+      content: content.trim(),
+      type,
+      wordCount,
+      isValid,
+    }
+  },
+})
+```
+
+## Understanding the Code
+
+- **ID**: Unique identifier for this step
+- **Input Schema**: Expects `content` (string) and optional `type`
+- **Output Schema**: Returns content, type, word count, and validation status
+- **Execute**: Contains the validation logic
+
+Your first step is ready! Next, you'll test it to make sure it works correctly.

package/.docs/course/04-workflows/04-creating-a-second-step.md

@@ -0,0 +1,58 @@
+# Creating a Second Step
+
+Now let's create a second step that enhances the validated content with metadata.
+
+## The Enhancement Step
+
+Add this step to your workflow file:
+
+```typescript
+const enhanceContentStep = createStep({
+  id: 'enhance-content',
+  description: 'Adds metadata to validated content',
+  inputSchema: z.object({
+    content: z.string(),
+    type: z.string(),
+    wordCount: z.number(),
+    isValid: z.boolean(),
+  }),
+  outputSchema: z.object({
+    content: z.string(),
+    type: z.string(),
+    wordCount: z.number(),
+    metadata: z.object({
+      readingTime: z.number(),
+      difficulty: z.enum(['easy', 'medium', 'hard']),
+      processedAt: z.string(),
+    }),
+  }),
+  execute: async ({ inputData }) => {
+    const { content, type, wordCount } = inputData
+
+    // Calculate reading time (200 words per minute)
+    const readingTime = Math.ceil(wordCount / 200)
+
+    // Determine difficulty based on word count
+    let difficulty: 'easy' | 'medium' | 'hard' = 'easy'
+    if (wordCount > 100) difficulty = 'medium'
+    if (wordCount > 300) difficulty = 'hard'
+
+    return {
+      content,
+      type,
+      wordCount,
+      metadata: {
+        readingTime,
+        difficulty,
+        processedAt: new Date().toISOString(),
+      },
+    }
+  },
+})
+```
+
+## Notice the Input Schema
+
+The input schema of this step matches the output schema of the previous step. This is important for chaining steps together!
+
+Your second step is ready! Next, you'll learn how to chain these steps together into a complete workflow.

package/.docs/course/04-workflows/05-chaining-steps-together.md

@@ -0,0 +1,57 @@
+# Chaining Steps Together
+
+Now you'll learn how to chain your steps together to create a complete workflow.
+
+## Creating the Workflow
+
+Add this workflow definition to your file:
+
+```typescript
+import { createWorkflow } from '@mastra/core/workflows'
+
+export const contentWorkflow = createWorkflow({
+  id: 'content-processing-workflow',
+  description: 'Validates and enhances content',
+  inputSchema: z.object({
+    content: z.string(),
+    type: z.enum(['article', 'blog', 'social']).default('article'),
+  }),
+  outputSchema: z.object({
+    content: z.string(),
+    type: z.string(),
+    wordCount: z.number(),
+    metadata: z.object({
+      readingTime: z.number(),
+      difficulty: z.enum(['easy', 'medium', 'hard']),
+      processedAt: z.string(),
+    }),
+  }),
+})
+  .then(validateContentStep)
+  .then(enhanceContentStep)
+  .commit()
+```
+
+## Understanding the Workflow
+
+- **Input Schema**: Defines what data the workflow expects
+- **Output Schema**: Defines what the workflow will return
+- **Steps**: Chained using `.then()` in the order they should execute
+- **Commit**: Finalizes the workflow definition
+
+## How Data Flows
+
+1. Workflow receives input matching the input schema
+2. First step processes input and outputs validated data
+3. Second step receives the first step's output as its input
+4. Workflow returns the final step's output
+
+## Schema Validation
+
+The workflow automatically validates:
+
+- Input data matches the workflow's input schema
+- Each step's output matches the next step's input schema
+- Final output matches the workflow's output schema
+
+Your workflow is now ready to run! Next, you'll test the complete workflow.