@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

package/.docs/raw/reference/index.mdx

@@ -0,0 +1,12 @@
+---
+title: "API Reference"
+description: "Mastra API Reference"
+---
+
+import { ReferenceCards } from "../../components/reference-cards";
+
+# Reference
+
+The Reference section provides documentation of Mastra's API, including parameters, types and usage examples.
+
+<ReferenceCards />

package/.docs/raw/reference/memory/Memory.mdx

@@ -0,0 +1,212 @@
+# Memory Class Reference
+
+The `Memory` class provides a robust system for managing conversation history and thread-based message storage in Mastra. It enables persistent storage of conversations, semantic search capabilities, and efficient message retrieval. By default, it uses LibSQL for storage and vector search, and FastEmbed for embeddings.
+
+## Basic Usage
+
+```typescript copy showLineNumbers
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  memory: new Memory(),
+  ...otherOptions,
+});
+```
+
+## Custom Configuration
+
+```typescript copy showLineNumbers
+import { Memory } from "@mastra/memory";
+import { LibSQLStore } from "@mastra/core/storage/libsql";
+import { LibSQLVector } from "@mastra/core/vector/libsql";
+import { Agent } from "@mastra/core/agent";
+
+const memory = new Memory({
+  // Optional storage configuration - libsql will be used by default
+  storage: new LibSQLStore({
+    url: "file:memory.db",
+  }),
+
+  // Optional vector database for semantic search - libsql will be used by default
+  vector: new LibSQLVector({
+    url: "file:vector.db",
+  }),
+
+  // Memory configuration options
+  options: {
+    // Number of recent messages to include
+    lastMessages: 20,
+
+    // Semantic search configuration
+    semanticRecall: {
+      topK: 3, // Number of similar messages to retrieve
+      messageRange: {
+        // Messages to include around each result
+        before: 2,
+        after: 1,
+      },
+    },
+
+    // Working memory configuration
+    workingMemory: {
+      enabled: true,
+      template: `
+# User
+- First Name:
+- Last Name:
+`,
+    },
+  },
+});
+
+const agent = new Agent({
+  memory,
+  ...otherOptions,
+});
+```
+
+### Working Memory
+
+The working memory feature allows agents to maintain persistent information across conversations. When enabled, the Memory class will automatically manage working memory updates through either text stream tags or tool calls.
+
+There are two modes for handling working memory updates:
+
+1. **text-stream** (default): The agent includes working memory updates directly in its responses using XML tags containing Markdown (`<working_memory># User \n ## Preferences...</working_memory>`). These tags are automatically processed and stripped from the visible output.
+
+2. **tool-call**: The agent uses a dedicated tool to update working memory. This mode should be used when working with `toDataStream()` as text-stream mode is not compatible with data streaming. Additionally, this mode provides more explicit control over memory updates and may be preferred when working with agents that are better at using tools than managing text tags.
+
+Example configuration:
+
+```typescript copy showLineNumbers
+const memory = new Memory({
+  options: {
+    workingMemory: {
+      enabled: true,
+      template: "# User\n- **First Name**:\n- **Last Name**:",
+      use: "tool-call", // or 'text-stream'
+    },
+  },
+});
+```
+
+If no template is provided, the Memory class uses a default template that includes fields for user details, preferences, goals, and other contextual information in Markdown format. See the [Working Memory guide](/docs/memory/working-memory.mdx#designing-effective-templates) for detailed usage examples and best practices.
+
+### embedder
+
+By default, Memory uses FastEmbed with the `bge-small-en-v1.5` model, which provides a good balance of performance and model size (~130MB). You only need to specify an embedder if you want to use a different model or provider.
+
+For environments where local embedding isn't supported, you can use an API-based embedder:
+
+```typescript {6}
+import { Memory } from "@mastra/memory";
+import { openai } from "@ai-sdk/openai";
+
+const agent = new Agent({
+  memory: new Memory({
+    embedder: openai.embedding("text-embedding-3-small"), // Adds network request
+  }),
+});
+```
+
+Mastra supports many embedding models through the [Vercel AI SDK](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings), including options from OpenAI, Google, Mistral, and Cohere.
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "storage",
+      type: "MastraStorage",
+      description: "Storage implementation for persisting memory data",
+      isOptional: true,
+    },
+    {
+      name: "vector",
+      type: "MastraVector",
+      description: "Vector store for semantic search capabilities",
+      isOptional: true,
+    },
+    {
+      name: "embedder",
+      type: "EmbeddingModel",
+      description:
+        "Embedder instance for vector embeddings. Uses FastEmbed (bge-small-en-v1.5) by default",
+      isOptional: true,
+    },
+    {
+      name: "options",
+      type: "MemoryConfig",
+      description: "General memory configuration options",
+      isOptional: true,
+    },
+  ]}
+/>
+
+### options
+
+<PropertiesTable
+  content={[
+    {
+      name: "lastMessages",
+      type: "number | false",
+      description:
+        "Number of most recent messages to retrieve. Set to false to disable.",
+      isOptional: true,
+      defaultValue: "40",
+    },
+    {
+      name: "semanticRecall",
+      type: "boolean | SemanticRecallConfig",
+      description:
+        "Enable semantic search in message history. Automatically enabled when vector store is provided.",
+      isOptional: true,
+      defaultValue: "false (true if vector store provided)",
+    },
+    {
+      name: "topK",
+      type: "number",
+      description:
+        "Number of similar messages to retrieve when using semantic search",
+      isOptional: true,
+      defaultValue: "2",
+    },
+    {
+      name: "messageRange",
+      type: "number | { before: number; after: number }",
+      description:
+        "Range of messages to include around semantic search results",
+      isOptional: true,
+      defaultValue: "2",
+    },
+    {
+      name: "workingMemory",
+      type: "{ enabled: boolean; template?: string; use?: 'text-stream' | 'tool-call' }",
+      description:
+        "Configuration for working memory feature that allows persistent storage of user information across conversations. The 'use' setting determines how working memory updates are handled - either through text stream tags or tool calls. Working memory uses Markdown format to structure and store continuously relevant information.",
+      isOptional: true,
+      defaultValue:
+        "{ enabled: false, template: '# User Information\\n- **First Name**:\\n- **Last Name**:\\n...', use: 'text-stream' }",
+    },
+    {
+      name: "threads",
+      type: "{ generateTitle?: boolean }",
+      description:
+        "Settings related to memory thread creation. `generateTitle` will cause the thread.title to be generated from an llm summary of the users first message.",
+      isOptional: true,
+      defaultValue: "{ generateTitle: true }",
+    },
+  ]}
+/>
+
+### Related
+
+- [Getting Started with Memory](/docs/memory/overview.mdx)
+- [Semantic Recall](/docs/memory/semantic-recall.mdx)
+- [Working Memory](/docs/memory/working-memory.mdx)
+- [Memory Processors](/docs/memory/memory-processors.mdx)
+- [createThread](/reference/memory/createThread.mdx)
+- [query](/reference/memory/query.mdx)
+- [getThreadById](/reference/memory/getThreadById.mdx)
+- [getThreadsByResourceId](/reference/memory/getThreadsByResourceId.mdx)
+

package/.docs/raw/reference/memory/createThread.mdx

@@ -0,0 +1,95 @@
+# createThread
+
+Creates a new conversation thread in the memory system. Each thread represents a distinct conversation or context and can contain multiple messages.
+
+## Usage Example
+
+```typescript
+import { Memory } from "@mastra/memory";
+
+const memory = new Memory({ /* config */ });
+const thread = await memory.createThread({
+  resourceId: "user-123",
+  title: "Support Conversation",
+  metadata: {
+    category: "support",
+    priority: "high"
+  }
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "resourceId",
+      type: "string",
+      description: "Identifier for the resource this thread belongs to (e.g., user ID, project ID)",
+      isOptional: false,
+    },
+    {
+      name: "threadId",
+      type: "string",
+      description: "Optional custom ID for the thread. If not provided, one will be generated.",
+      isOptional: true,
+    },
+    {
+      name: "title",
+      type: "string",
+      description: "Optional title for the thread",
+      isOptional: true,
+    },
+    {
+      name: "metadata",
+      type: "Record<string, unknown>",
+      description: "Optional metadata to associate with the thread",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Unique identifier of the created thread",
+    },
+    {
+      name: "resourceId",
+      type: "string",
+      description: "Resource ID associated with the thread",
+    },
+    {
+      name: "title",
+      type: "string",
+      description: "Title of the thread (if provided)",
+    },
+    {
+      name: "createdAt",
+      type: "Date",
+      description: "Timestamp when the thread was created",
+    },
+    {
+      name: "updatedAt",
+      type: "Date",
+      description: "Timestamp when the thread was last updated",
+    },
+    {
+      name: "metadata",
+      type: "Record<string, unknown>",
+      description: "Additional metadata associated with the thread",
+    },
+  ]}
+/>
+
+### Related
+
+- [Memory Class Reference](/reference/memory/Memory.mdx)
+- [Getting Started with Memory](/docs/memory/overview.mdx) (Covers threads concept)
+- [getThreadById](/reference/memory/getThreadById.mdx)
+- [getThreadsByResourceId](/reference/memory/getThreadsByResourceId.mdx)
+- [query](/reference/memory/query.mdx)

package/.docs/raw/reference/memory/getThreadById.mdx

@@ -0,0 +1,46 @@
+# getThreadById Reference
+
+The `getThreadById` function retrieves a specific thread by its ID from storage.
+
+## Usage Example
+
+```typescript
+import { Memory } from "@mastra/core/memory";
+
+const memory = new Memory(config);
+
+const thread = await memory.getThreadById({ threadId: "thread-123" });
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "threadId",
+      type: "string",
+      description: "The ID of the thread to be retrieved.",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "StorageThreadType | null",
+      type: "Promise",
+      description:
+        "A promise that resolves to the thread associated with the given ID, or null if not found.",
+    },
+  ]}
+/>
+
+### Related
+
+- [Memory Class Reference](/reference/memory/Memory.mdx)
+- [Getting Started with Memory](/docs/memory/overview.mdx) (Covers threads concept)
+- [createThread](/reference/memory/createThread.mdx)
+- [getThreadsByResourceId](/reference/memory/getThreadsByResourceId.mdx)

package/.docs/raw/reference/memory/getThreadsByResourceId.mdx

@@ -0,0 +1,48 @@
+# getThreadsByResourceId Reference
+
+The `getThreadsByResourceId` function retrieves all threads associated with a specific resource ID from storage.
+
+## Usage Example
+
+```typescript
+import { Memory } from "@mastra/core/memory";
+
+const memory = new Memory(config);
+
+const threads = await memory.getThreadsByResourceId({
+  resourceId: "resource-123",
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "resourceId",
+      type: "string",
+      description: "The ID of the resource whose threads are to be retrieved.",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "StorageThreadType[]",
+      type: "Promise",
+      description:
+        "A promise that resolves to an array of threads associated with the given resource ID.",
+    },
+  ]}
+/>
+
+### Related
+
+- [Memory Class Reference](/reference/memory/Memory.mdx)
+- [Getting Started with Memory](/docs/memory/overview.mdx) (Covers threads/resources concept)
+- [createThread](/reference/memory/createThread.mdx)
+- [getThreadById](/reference/memory/getThreadById.mdx)

package/.docs/raw/reference/memory/query.mdx

@@ -0,0 +1,167 @@
+# query
+
+Retrieves messages from a specific thread, with support for pagination and filtering options.
+
+## Usage Example
+
+```typescript
+import { Memory } from "@mastra/memory";
+
+const memory = new Memory({
+  /* config */
+});
+
+// Get last 50 messages
+const { messages, uiMessages } = await memory.query({
+  threadId: "thread-123",
+  selectBy: {
+    last: 50,
+  },
+});
+
+// Get messages with context around specific messages
+const { messages: contextMessages } = await memory.query({
+  threadId: "thread-123",
+  selectBy: {
+    include: [
+      {
+        id: "msg-123", // Get just this message (no context)
+      },
+      {
+        id: "msg-456", // Get this message with custom context
+        withPreviousMessages: 3, // 3 messages before
+        withNextMessages: 1, // 1 message after
+      },
+    ],
+  },
+});
+
+// Semantic search in messages
+const { messages } = await memory.query({
+  threadId: "thread-123",
+  selectBy: {
+    vectorSearchString: "What was discussed about deployment?",
+  },
+  threadConfig: {
+    historySearch: true,
+  },
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "threadId",
+      type: "string",
+      description:
+        "The unique identifier of the thread to retrieve messages from",
+      isOptional: false,
+    },
+    {
+      name: "resourceId",
+      type: "string",
+      description:
+        "Optional ID of the resource that owns the thread. If provided, validates thread ownership",
+      isOptional: true,
+    },
+    {
+      name: "selectBy",
+      type: "object",
+      description: "Options for filtering messages",
+      isOptional: true,
+    },
+    {
+      name: "threadConfig",
+      type: "MemoryConfig",
+      description: "Configuration options for message retrieval",
+      isOptional: true,
+    },
+  ]}
+/>
+
+### selectBy
+
+<PropertiesTable
+  content={[
+    {
+      name: "vectorSearchString",
+      type: "string",
+      description: "Search string for finding semantically similar messages",
+      isOptional: true,
+    },
+    {
+      name: "last",
+      type: "number | false",
+      description:
+        "Number of most recent messages to retrieve. Set to false to disable limit. Note: threadConfig.lastMessages (default: 40) will override this if smaller.",
+      isOptional: true,
+      defaultValue: "40",
+    },
+    {
+      name: "include",
+      type: "array",
+      description: "Array of message IDs to include with context",
+      isOptional: true,
+    },
+  ]}
+/>
+
+### include
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "ID of the message to include",
+      isOptional: false,
+    },
+    {
+      name: "withPreviousMessages",
+      type: "number",
+      description:
+        "Number of messages to include before this message. Defaults to 2 when using vector search, 0 otherwise.",
+      isOptional: true,
+    },
+    {
+      name: "withNextMessages",
+      type: "number",
+      description:
+        "Number of messages to include after this message. Defaults to 2 when using vector search, 0 otherwise.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "messages",
+      type: "CoreMessage[]",
+      description: "Array of retrieved messages in their core format",
+    },
+    {
+      name: "uiMessages",
+      type: "AiMessage[]",
+      description: "Array of messages formatted for UI display",
+    },
+  ]}
+/>
+
+## Additional Notes
+
+The `query` function returns two different message formats:
+
+- `messages`: Core message format used internally
+- `uiMessages`: Formatted messages suitable for UI display, including proper threading of tool calls and results
+
+### Related
+
+- [Memory Class Reference](/reference/memory/Memory.mdx)
+- [Getting Started with Memory](/docs/memory/overview.mdx)
+- [Semantic Recall](/docs/memory/semantic-recall.mdx)
+- [createThread](/reference/memory/createThread.mdx)