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

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

@@ -1,226 +0,0 @@
----
-title: "Semantic Recall | Memory | Mastra Docs"
-description: "Learn how to use semantic recall in Mastra to retrieve relevant messages from past conversations using vector search and embeddings."
----
-
-# Semantic Recall
-
-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.
-
-> **📹 Watch**: What semantic recall is, how it works, and how to configure it in Mastra → [YouTube (5 minutes)](https://youtu.be/UVZtK8cK8xQ)
-
-## 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="/image/semantic-recall.png"
-  alt="Diagram showing Mastra Memory semantic recall"
-  width={800}
-/>
-
-When it's enabled, new messages are used to query a vector DB for semantically similar messages.
-
-After getting a response from the LLM, all new messages (user, assistant, and tool calls/results) are inserted into the vector DB to be recalled in later interactions.
-
-## 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 three 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
-3. **scope**: Whether to search within the current thread or across all threads owned by a resource. Using `scope: 'resource'` allows the agent to recall information from any of the user's past conversations.
-
-```typescript {5-7}
-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
-        scope: 'resource', // Search across all threads for this user
-      },
-    },
-  }),
-});
-```
-
-Note: currently, `scope: 'resource'` for semantic recall is supported by the following storage adapters: LibSQL, Postgres, and Upstash.
-
-### 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, LibSQLVector } from "@mastra/libsql";
-
-const agent = new Agent({
-  memory: new Memory({
-    // this is the default storage db if omitted
-    storage: new LibSQLStore({
-      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 on an [embedding model](/reference/memory/Memory#embedder) to convert messages into embeddings. Mastra supports embedding models through the model router using `provider/model` strings, or you can use any [embedding model](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings) compatible with the AI SDK.
-
-#### Using the Model Router (Recommended)
-
-The simplest way is to use a `provider/model` string with autocomplete support:
-
-```ts {7}
-import { Memory } from "@mastra/memory";
-import { Agent } from "@mastra/core/agent";
-
-const agent = new Agent({
-  memory: new Memory({
-    // ... other memory options
-    embedder: "openai/text-embedding-3-small", // TypeScript autocomplete supported
-  }),
-});
-```
-
-Supported embedding models:
-- **OpenAI**: `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`
-- **Google**: `gemini-embedding-001`, `text-embedding-004`
-
-The model router automatically handles API key detection from environment variables (`OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`).
-
-#### Using AI SDK Packages
-
-You can also use AI SDK embedding models directly:
-
-```ts {3,8}
-import { Memory } from "@mastra/memory";
-import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
-
-const agent = new Agent({
-  memory: new Memory({
-    // ... other memory options
-    embedder: openai.embedding("text-embedding-3-small"),
-  }),
-});
-```
-
-#### Using FastEmbed (Local)
-
-To use FastEmbed (a local embedding model), install `@mastra/fastembed`:
-
-```bash npm2yarn copy
-npm install @mastra/fastembed
-```
-
-Then configure it in your memory:
-
-```ts {3,8}
-import { Memory } from "@mastra/memory";
-import { Agent } from "@mastra/core/agent";
-import { fastembed } from "@mastra/fastembed";
-
-const agent = new Agent({
-  memory: new Memory({
-    // ... other memory options
-    embedder: fastembed,
-  }),
-});
-```
-
-### PostgreSQL Index Optimization
-
-When using PostgreSQL as your vector store, you can optimize semantic recall performance by configuring the vector index. This is particularly important for large-scale deployments with thousands of messages.
-
-PostgreSQL supports both IVFFlat and HNSW indexes. By default, Mastra creates an IVFFlat index, but HNSW indexes typically provide better performance, especially with OpenAI embeddings which use inner product distance.
-
-```typescript {9-18}
-import { Memory } from "@mastra/memory";
-import { PgStore, PgVector } from "@mastra/pg";
-
-const agent = new Agent({
-  memory: new Memory({
-    storage: new PgStore({
-      connectionString: process.env.DATABASE_URL,
-    }),
-    vector: new PgVector({
-      connectionString: process.env.DATABASE_URL,
-    }),
-    options: {
-      semanticRecall: {
-        topK: 5,
-        messageRange: 2,
-        indexConfig: {
-          type: 'hnsw',           // Use HNSW for better performance
-          metric: 'dotproduct',   // Best for OpenAI embeddings  
-          m: 16,                  // Number of bi-directional links (default: 16)
-          efConstruction: 64,    // Size of candidate list during construction (default: 64)
-        },
-      },
-    },
-  }),
-});
-```
-
-For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](/reference/vectors/pg#index-configuration-guide).
-
-### 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 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.
-
-## Viewing Recalled Messages
-
-When tracing is enabled, any messages retrieved via semantic recall will appear in the agent’s trace output, alongside recent conversation history (if configured).
-
-For more info on viewing message traces, see [Viewing Retrieved Messages](./overview.mdx#viewing-retrieved-messages).

package/.docs/raw/memory/threads-and-resources.mdx

@@ -1,94 +0,0 @@
----
-title: "Memory Threads and Resources | Memory | Mastra Docs"
-description: "Learn how Mastra's memory system works with working memory, conversation history, and semantic recall."
----
-
-import { Callout } from "nextra/components";
-
-# Memory threads and resources
-
-Mastra organizes memory into threads, which are records that group related interactions, using two identifiers:
-
-1. **`thread`**: A globally unique ID representing the conversation (e.g., `support_123`). Must be unique across all resources.
-2. **`resource`**: The user or entity that owns the thread (e.g., `user_123`, `org_456`).
-
-The `resource` is especially important for [resource-scoped memory](./working-memory.mdx#resource-scoped-memory), which allows memory to persist across all threads associated with the same user or entity.
-
-```typescript {4} showLineNumbers
-const stream = await agent.stream("message for agent", {
-  memory: {
-    thread: "user-123",
-    resource: "test-123"
-  }
-});
-```
-
-<Callout type="warning">
-Even with memory configured, agents won’t store or recall information unless both `thread` and `resource` are provided.
-</Callout>
-
-> Mastra Playground sets `thread` and `resource` IDs automatically. In your own application, you must provide them manually as part of each `.generate()` or `.stream()` call.
-
-### Thread title generation
-
-Mastra can automatically generate descriptive thread titles based on the user's first message. Enable this by setting `generateTitle` to `true`. This improves organization and makes it easier to display conversations in your UI.
-
-```typescript {3-7} showLineNumbers
-export const testAgent = new Agent({
-  memory: new Memory({
-    options: {
-      threads: {
-        generateTitle: true,
-      }
-    },
-  })
-});
-```
-
-> Title generation runs asynchronously after the agent responds and does not affect response time. See the [full configuration reference](../../reference/memory/Memory.mdx#thread-title-generation) for details and examples.
-
-#### Optimizing title generation
-
-Titles are generated using your agent's model by default. To optimize cost or behavior, provide a smaller `model` and custom `instructions`. This keeps title generation separate from main conversation logic.
-
-```typescript {5-9} showLineNumbers
-export const testAgent = new Agent({
-  // ...
-  memory: new Memory({
-    options: {
-      threads: {
-        generateTitle: {
-          model: openai("gpt-4.1-nano"),
-          instructions: "Generate a concise title based on the user's first message",
-        },
-      },
-    }
-  })
-});
-```
-
-#### Dynamic model selection and instructions
-
-You can configure thread title generation dynamically by passing functions to `model` and `instructions`. These functions receive the `runtimeContext` object, allowing you to adapt title generation based on user-specific values.
-
-```typescript {7-16} showLineNumbers
-export const testAgent = new Agent({
-  // ...
-  memory: new Memory({
-    options: {
-      threads: {
-        generateTitle: {
-          model: ({ runtimeContext }) => {
-            const userTier = runtimeContext.get("userTier");
-            return userTier === "premium" ? openai("gpt-4.1") : openai("gpt-4.1-nano");
-          },
-          instructions: ({ runtimeContext }) => {
-            const language = runtimeContext.get("userLanguage") || "English";
-            return `Generate a concise, engaging title in ${language} based on the user's first message.`;
-          }
-        }
-      }
-    }
-  })
-});
-```

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

@@ -1,378 +0,0 @@
----
-title: "Working Memory | Memory | Mastra Docs"
-description: "Learn how to configure working memory in Mastra to store persistent user data, preferences."
----
-
-import YouTube from "@/components/youtube";
-
-# Working Memory
-
-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.
-
-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.
-
-Working memory can persist at two different scopes:
-- **Thread-scoped** (default): Memory is isolated per conversation thread
-- **Resource-scoped**: Memory persists across all conversation threads for the same user
-
-**Important:** Switching between scopes means the agent won't see memory from the other scope - thread-scoped memory is completely separate from resource-scoped memory.
-
-
-## 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,
-      },
-    },
-  }),
-});
-```
-
-## 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="UMy_JHLf1n8" />
-
-## Memory Persistence Scopes
-
-Working memory can operate in two different scopes, allowing you to choose how memory persists across conversations:
-
-### Thread-Scoped Memory (Default)
-
-By default, working memory is scoped to individual conversation threads. Each thread maintains its own isolated memory:
-
-```typescript
-const memory = new Memory({
-  storage,
-  options: {
-    workingMemory: {
-      enabled: true,
-      scope: 'thread', // Default - memory is isolated per thread
-      template: `# User Profile
-- **Name**:
-- **Interests**:
-- **Current Goal**:
-`,
-    },
-  },
-});
-```
-
-**Use cases:**
-- Different conversations about separate topics
-- Temporary or session-specific information
-- Workflows where each thread needs working memory but threads are ephemeral and not related to each other
-
-### Resource-Scoped Memory
-
-Resource-scoped memory persists across all conversation threads for the same user (resourceId), enabling persistent user memory:
-
-```typescript
-const memory = new Memory({
-  storage,
-  options: {
-    workingMemory: {
-      enabled: true,
-      scope: 'resource', // Memory persists across all user threads
-      template: `# User Profile
-- **Name**:
-- **Location**:
-- **Interests**:
-- **Preferences**:
-- **Long-term Goals**:
-`,
-    },
-  },
-});
-```
-
-**Use cases:**
-- Personal assistants that remember user preferences
-- Customer service bots that maintain customer context
-- Educational applications that track student progress
-
-### Usage with Agents
-
-When using resource-scoped memory, make sure to pass the `resourceId` parameter:
-
-```typescript
-// Resource-scoped memory requires resourceId
-const response = await agent.generate("Hello!", {
-  threadId: "conversation-123",
-  resourceId: "user-alice-456" // Same user across different threads
-});
-```
-
-## Storage Adapter Support
-
-Resource-scoped working memory requires specific storage adapters that support the `mastra_resources` table:
-
-### ✅ Supported Storage Adapters
-- **LibSQL** (`@mastra/libsql`)
-- **PostgreSQL** (`@mastra/pg`)
-- **Upstash** (`@mastra/upstash`)
-
-## 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]
-`,
-    },
-  },
-});
-```
-
-## Designing Effective Templates
-
-A well-structured template keeps the information easy for the agent to parse and update. Treat the
-template as a short form that you want the assistant to keep up to date.
-
-- **Short, focused labels.** Avoid paragraphs or very long headings. Keep labels brief (for example
-  `## Personal Info` or `- Name:`) so updates are easy to read and less likely to be truncated.
-- **Use consistent casing.** Inconsistent capitalization (`Timezone:` vs `timezone:`) can cause messy
-  updates. Stick to Title Case or lower case for headings and bullet labels.
-- **Keep placeholder text simple.** Use hints such as `[e.g., Formal]` or `[Date]` to help the LLM
-  fill in the correct spots.
-- **Abbreviate very long values.** If you only need a short form, include guidance like
-  `- Name: [First name or nickname]` or `- Address (short):` rather than the full legal text.
-- **Mention update rules in `instructions`.** You can instruct how and when to fill or clear parts of
-  the template directly in the agent's `instructions` field.
-
-### Alternative Template Styles
-
-Use a shorter single block if you only need a few items:
-
-```typescript
-const basicMemory = new Memory({
-  options: {
-    workingMemory: {
-      enabled: true,
-      template: `User Facts:\n- Name:\n- Favorite Color:\n- Current Topic:`,
-    },
-  },
-});
-```
-
-You can also store the key facts in a short paragraph format if you prefer a more narrative style:
-
-```typescript
-const paragraphMemory = new Memory({
-  options: {
-    workingMemory: {
-      enabled: true,
-      template: `Important Details:\n\nKeep a short paragraph capturing the user's important facts (name, main goal, current task).`,
-    },
-  },
-});
-```
-
-## Structured Working Memory
-
-Working memory can also be defined using a structured schema instead of a Markdown template. This allows you to specify the exact fields and types that should be tracked, using a [Zod](https://zod.dev/) schema. When using a schema, the agent will see and update working memory as a JSON object matching your schema.
-
-**Important:** You must specify either `template` or `schema`, but not both.
-
-### Example: Schema-Based Working Memory
-
-```typescript
-import { z } from 'zod';
-import { Memory } from '@mastra/memory';
-
-const userProfileSchema = z.object({
-  name: z.string().optional(),
-  location: z.string().optional(),
-  timezone: z.string().optional(),
-  preferences: z.object({
-    communicationStyle: z.string().optional(),
-    projectGoal: z.string().optional(),
-    deadlines: z.array(z.string()).optional(),
-  }).optional(),
-});
-
-const memory = new Memory({
-  options: {
-    workingMemory: {
-      enabled: true,
-      schema: userProfileSchema,
-      // template: ... (do not set)
-    },
-  },
-});
-```
-
-When a schema is provided, the agent receives the working memory as a JSON object. For example:
-
-```json
-{
-  "name": "Sam",
-  "location": "Berlin",
-  "timezone": "CET",
-  "preferences": {
-    "communicationStyle": "Formal",
-    "projectGoal": "Launch MVP",
-    "deadlines": ["2025-07-01"]
-  }
-}
-```
-
-## Choosing Between Template and Schema
-
-- Use a **template** (Markdown) if you want the agent to maintain memory as a free-form text block, such as a user profile or scratchpad.
-- Use a **schema** if you need structured, type-safe data that can be validated and programmatically accessed as JSON.
-- Only one mode can be active at a time: setting both `template` and `schema` is not supported.
-
-## Example: Multi-step Retention
-
-Below is a simplified view of how the `User Profile` template updates across a short user
-conversation:
-
-```nohighlight
-# User Profile
-
-## Personal Info
-
-- Name:
-- Location:
-- Timezone:
-
---- After user says "My name is **Sam** and I'm from **Berlin**" ---
-
-# User Profile
-- Name: Sam
-- Location: Berlin
-- Timezone:
-
---- After user adds "By the way I'm normally in **CET**" ---
-
-# User Profile
-- Name: Sam
-- Location: Berlin
-- Timezone: CET
-```
-
-The agent can now refer to `Sam` or `Berlin` in later responses without requesting the information
-again because it has been stored in working memory.
-
-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 agent's `instructions` setting.
-
-## Setting Initial Working Memory
-
-While agents typically update working memory through the `updateWorkingMemory` tool, you can also set initial working memory programmatically when creating or updating threads. This is useful for injecting user data (like their name, preferences, or other info) that you want available to the agent without passing it in every request.
-
-### Setting Working Memory via Thread Metadata
-
-When creating a thread, you can provide initial working memory through the metadata's `workingMemory` key:
-
-```typescript filename="src/app/medical-consultation.ts" showLineNumbers copy
-// Create a thread with initial working memory
-const thread = await memory.createThread({
-  threadId: "thread-123",
-  resourceId: "user-456",
-  title: "Medical Consultation",
-  metadata: {
-    workingMemory: `# Patient Profile
-- Name: John Doe
-- Blood Type: O+
-- Allergies: Penicillin
-- Current Medications: None
-- Medical History: Hypertension (controlled)
-`
-  }
-});
-
-// The agent will now have access to this information in all messages
-await agent.generate("What's my blood type?", {
-  threadId: thread.id,
-  resourceId: "user-456"
-});
-// Response: "Your blood type is O+."
-```
-
-### Updating Working Memory Programmatically
-
-You can also update an existing thread's working memory:
-
-```typescript filename="src/app/medical-consultation.ts" showLineNumbers copy
-// Update thread metadata to add/modify working memory
-await memory.updateThread({
-  id: "thread-123",
-  title: thread.title,
-  metadata: {
-    ...thread.metadata,
-    workingMemory: `# Patient Profile
-- Name: John Doe
-- Blood Type: O+
-- Allergies: Penicillin, Ibuprofen  // Updated
-- Current Medications: Lisinopril 10mg daily  // Added
-- Medical History: Hypertension (controlled)
-`
-  }
-});
-```
-
-### Direct Memory Update
-
-Alternatively, use the `updateWorkingMemory` method directly:
-
-```typescript filename="src/app/medical-consultation.ts" showLineNumbers copy
-await memory.updateWorkingMemory({
-  threadId: "thread-123",
-  resourceId: "user-456", // Required for resource-scoped memory
-  workingMemory: "Updated memory content..."
-});
-```
-
-## Examples
-
-- [Basic working memory](/examples/memory/working-memory-basic)
-- [Working memory with template](/examples/memory/working-memory-template)
-- [Working memory with schema](/examples/memory/working-memory-schema)
-- [Per-resource working memory](https://github.com/mastra-ai/mastra/tree/main/examples/memory-per-resource-example) - Complete example showing resource-scoped memory persistence