@mastra/mcp-docs-server 0.13.39 → 1.0.0-beta.0

package/.docs/raw/reference/{observability/logging → logging}/pino-logger.mdx

@@ -7,12 +7,12 @@ description: Documentation for PinoLogger, which provides methods to record even
 
 A Logger instance is created using `new PinoLogger()` and provides methods to record events at various severity levels.
 
-When deploying to Mastra Cloud, logs are displayed on the [Logs](/docs/mastra-cloud/dashboard#logs) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
+When deploying to Mastra Cloud, logs are displayed on the [Logs](/docs/v1/mastra-cloud/dashboard#logs) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
 
 ## Usage example
 
 ```typescript title="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 import { PinoLogger } from "@mastra/loggers";
 
 export const mastra = new Mastra({

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

@@ -112,8 +112,8 @@ console.log(response.text);
 
 ### Related
 
-- [Memory Class Reference](/reference/memory/memory-class)
-- [Getting Started with Memory](/docs/memory/overview) (Covers threads concept)
-- [getThreadById](/reference/memory/getThreadById)
-- [getThreadsByResourceId](/reference/memory/getThreadsByResourceId)
-- [query](/reference/memory/query)
+- [Memory Class Reference](/reference/v1/memory/memory-class)
+- [Getting Started with Memory](/docs/v1/memory/overview) (Covers threads concept)
+- [getThreadById](/reference/v1/memory/getThreadById)
+- [listThreadsByResourceId](/reference/v1/memory/listThreadsByResourceId)
+- [query](/reference/v1/memory/query)

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

@@ -42,21 +42,21 @@ await memory?.deleteMessages(["671ae63f-3a91-4082-a907-fe7de78e10ec"]);
 
 ```typescript title="src/test-memory.ts" showLineNumbers copy
 import { mastra } from "./mastra";
-import { UIMessageWithMetadata } from "@mastra/core/agent";
+import { MastraDBMessage } from "@mastra/core";
 
 const agent = mastra.getAgent("agent");
 const memory = await agent.getMemory();
 
-const { uiMessages } = await memory!.query({ threadId: "thread-123" });
+const { messages } = await memory!.recall({ threadId: "thread-123" });
 
-const messageIds = uiMessages.map(
-  (message: UIMessageWithMetadata) => message.id,
+const messageIds = messages.map(
+  (message: MastraDBMessage) => message.id,
 );
 await memory?.deleteMessages([...messageIds]);
 ```
 
 ## Related
 
-- [Memory Class Reference](/reference/memory/memory-class)
-- [query](/reference/memory/query)
-- [Getting Started with Memory](/docs/memory/overview)
+- [Memory Class Reference](/reference/v1/memory/memory-class)
+- [recall](/reference/v1/memory/recall)
+- [Getting Started with Memory](/docs/v1/memory/overview)

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

@@ -41,7 +41,7 @@ await memory?.getThreadById({ threadId: "thread-123" });
 
 ### Related
 
-- [Memory Class Reference](/reference/memory/memory-class)
-- [Getting Started with Memory](/docs/memory/overview) (Covers threads concept)
-- [createThread](/reference/memory/createThread)
-- [getThreadsByResourceId](/reference/memory/getThreadsByResourceId)
+- [Memory Class Reference](/reference/v1/memory/memory-class)
+- [Getting Started with Memory](/docs/v1/memory/overview) (Covers threads concept)
+- [createThread](/reference/v1/memory/createThread)
+- [listThreadsByResourceId](/reference/v1/memory/listThreadsByResourceId)

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

@@ -0,0 +1,110 @@
+---
+title: "Reference: Memory.listThreadsByResourceId() | Memory | Mastra Docs"
+description: "Documentation for the `Memory.listThreadsByResourceId()` method in Mastra, which retrieves threads associated with a specific resource ID with pagination support."
+---
+
+# Memory.listThreadsByResourceId()
+
+The `.listThreadsByResourceId()` method retrieves threads associated with a specific resource ID with pagination support.
+
+## Usage Example
+
+```typescript copy
+await memory.listThreadsByResourceId({
+  resourceId: "user-123",
+  page: 0,
+  perPage: 10,
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "resourceId",
+      type: "string",
+      description: "The ID of the resource whose threads are to be retrieved",
+      isOptional: false,
+    },
+    {
+      name: "page",
+      type: "number",
+      description: "Page number (0-indexed) to retrieve",
+      isOptional: false,
+    },
+    {
+      name: "perPage",
+      type: "number",
+      description: "Maximum number of threads to return per page",
+      isOptional: false,
+    },
+    {
+      name: "orderBy",
+      type: "{ field: 'createdAt' | 'updatedAt', direction: 'ASC' | 'DESC' }",
+      description: "Sort configuration with field and direction (defaults to { field: 'createdAt', direction: 'DESC' })",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "result",
+      type: "Promise<StorageListThreadsByResourceIdOutput>",
+      description:
+        "A promise that resolves to paginated thread results with metadata",
+    },
+  ]}
+/>
+
+The return object contains:
+- `threads`: Array of thread objects
+- `total`: Total number of threads for this resource
+- `page`: Current page number (same as the input `page` parameter)
+- `perPage`: Items per page (same as the input `perPage` parameter)
+- `hasMore`: Boolean indicating if more results are available
+
+## Extended usage example
+
+```typescript title="src/test-memory.ts" showLineNumbers copy
+import { mastra } from "./mastra";
+
+const agent = mastra.getAgent("agent");
+const memory = await agent.getMemory();
+
+let currentPage = 0;
+const perPage = 25;
+let hasMorePages = true;
+
+while (hasMorePages) {
+  const result = await memory?.listThreadsByResourceId({
+    resourceId: "user-123",
+    page: currentPage,
+    perPage: perPage,
+    orderBy: { field: "createdAt", direction: "ASC" },
+  });
+
+  if (!result) {
+    console.log("No threads");
+    break;
+  }
+
+  result.threads.forEach((thread) => {
+    console.log(`Thread: ${thread.id}, Created: ${thread.createdAt}`);
+  });
+
+  hasMorePages = result.hasMore;
+  currentPage++; // Move to next page
+}
+```
+
+## Related
+
+- [Memory Class Reference](/reference/v1/memory/memory-class)
+- [Getting Started with Memory](/docs/v1/memory/overview) (Covers threads/resources concept)
+- [createThread](/reference/v1/memory/createThread)
+- [getThreadById](/reference/v1/memory/getThreadById)

package/.docs/raw/reference/memory/memory-class.mdx

@@ -137,9 +137,11 @@ export const agent = new Agent({
   model: openai("gpt-4o"),
   memory: new Memory({
     storage: new LibSQLStore({
+      id: 'test-agent-storage',
       url: "file:./working-memory.db",
     }),
     vector: new LibSQLVector({
+      id: 'test-agent-vector',
       connectionUrl: "file:./vector-memory.db",
     }),
     options: {
@@ -174,9 +176,11 @@ export const agent = new Agent({
   model: openai("gpt-4o"),
   memory: new Memory({
     storage: new PgStore({
+      id: 'pg-agent-storage',
       connectionString: process.env.DATABASE_URL,
     }),
     vector: new PgVector({
+      id: 'pg-agent-vector',
       connectionString: process.env.DATABASE_URL,
     }),
     embedder: openai.embedding("text-embedding-3-small"),
@@ -203,12 +207,12 @@ export const agent = new Agent({
 
 ### Related
 
-- [Getting Started with Memory](/docs/memory/overview)
-- [Semantic Recall](/docs/memory/semantic-recall)
-- [Working Memory](/docs/memory/working-memory)
-- [Memory Processors](/docs/memory/memory-processors)
-- [createThread](/reference/memory/createThread)
-- [query](/reference/memory/query)
-- [getThreadById](/reference/memory/getThreadById)
-- [getThreadsByResourceId](/reference/memory/getThreadsByResourceId)
-- [deleteMessages](/reference/memory/deleteMessages)
+- [Getting Started with Memory](/docs/v1/memory/overview)
+- [Semantic Recall](/docs/v1/memory/semantic-recall)
+- [Working Memory](/docs/v1/memory/working-memory)
+- [Memory Processors](/docs/v1/memory/memory-processors)
+- [createThread](/reference/v1/memory/createThread)
+- [recall](/reference/v1/memory/recall)
+- [getThreadById](/reference/v1/memory/getThreadById)
+- [listThreadsByResourceId](/reference/v1/memory/listThreadsByResourceId)
+- [deleteMessages](/reference/v1/memory/deleteMessages)

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

@@ -5,6 +5,10 @@ description: "Documentation for the `Memory.query()` method in Mastra, which ret
 
 # Memory.query()
 
+:::warning[Deprecated]
+The `Memory.query()` method has been renamed to [`Memory.recall()`](/reference/v1/memory/recall). This page is kept for reference, but please use `recall()` in new code.
+:::
+
 the `.query()` method retrieves messages from a specific thread, with support for pagination, filtering options, and semantic search.
 
 ## Usage Example
@@ -32,60 +36,55 @@ await memory?.query({ threadId: "user-123" });
       isOptional: true,
     },
     {
-      name: "selectBy",
-      type: "object",
-      description: "Options for filtering and selecting messages",
+      name: "vectorSearchString",
+      type: "string",
+      description:
+        "Search string for finding semantically similar messages. Requires semantic recall to be enabled in threadConfig.",
       isOptional: true,
     },
     {
-      name: "threadConfig",
-      type: "MemoryConfig",
+      name: "perPage",
+      type: "number | false",
       description:
-        "Configuration options for message retrieval and semantic search",
+        "Number of messages to retrieve per page. Set to false to fetch all messages without pagination.",
       isOptional: true,
     },
     {
-      name: "format",
-      type: "'v1' | 'v2'",
+      name: "page",
+      type: "number",
       description:
-        "Message format to return. Defaults to 'v2' for current format, 'v1' for backwards compatibility",
+        "Zero-based page number for pagination. Used with perPage to retrieve messages in batches.",
       isOptional: true,
     },
-  ]}
-/>
-
-### selectBy parameters
-
-<PropertiesTable
-  content={[
     {
-      name: "vectorSearchString",
-      type: "string",
+      name: "include",
+      type: "{ id: string; threadId?: string; withPreviousMessages?: number; withNextMessages?: number }[]",
       description:
-        "Search string for finding semantically similar messages. Requires semantic recall to be enabled in threadConfig.",
+        "Array of specific message IDs to include with optional context messages. Each item has an `id` (required), optional `threadId` (defaults to main threadId), `withPreviousMessages` (number of messages before, defaults to 2 for vector search, 0 otherwise), and `withNextMessages` (number of messages after, defaults to 2 for vector search, 0 otherwise).",
       isOptional: true,
     },
     {
-      name: "last",
-      type: "number | false",
+      name: "filter",
+      type: "{ dateRange?: { start?: Date; end?: Date } }",
       description:
-        "Number of most recent messages to retrieve. Set to false to disable limit. Note: threadConfig.lastMessages (default: 10) will override this if smaller.",
+        "Filter options for message retrieval. Currently supports `dateRange` to filter messages by creation date.",
       isOptional: true,
     },
     {
-      name: "include",
-      type: "{ id: string; threadId?: string; withPreviousMessages?: number; withNextMessages?: number }[]",
+      name: "orderBy",
+      type: "{ field: 'createdAt'; direction: 'ASC' | 'DESC' }",
       description:
-        "Array of specific message IDs to include with optional context messages. Each item has an `id` (required), optional `threadId` (defaults to main threadId), `withPreviousMessages` (number of messages before, defaults to 2 for vector search, 0 otherwise), and `withNextMessages` (number of messages after, defaults to 2 for vector search, 0 otherwise).",
+        "Sort order for retrieved messages. Defaults to descending by creation date.",
       isOptional: true,
     },
     {
-      name: "pagination",
-      type: "{ dateRange?: { start?: Date; end?: Date }; page?: number; perPage?: number }",
+      name: "threadConfig",
+      type: "MemoryConfig",
       description:
-        "Pagination options for retrieving messages in batches. Includes `dateRange` (filter by date range), `page` (0-based page number), and `perPage` (messages per page).",
+        "Configuration options for message retrieval and semantic search",
       isOptional: true,
     },
+
   ]}
 />
 
@@ -135,14 +134,8 @@ await memory?.query({ threadId: "user-123" });
   content={[
     {
       name: "messages",
-      type: "CoreMessage[]",
-      description: "Array of retrieved messages in their core format",
-    },
-    {
-      name: "uiMessages",
-      type: "UIMessageWithMetadata[]",
-      description:
-        "Array of messages formatted for UI display, including proper threading of tool calls and results",
+      type: "MastraDBMessage[]",
+      description: "Array of retrieved messages in the database format",
     },
   ]}
 />
@@ -155,34 +148,42 @@ import { mastra } from "./mastra";
 const agent = mastra.getAgent("agent");
 const memory = await agent.getMemory();
 
-const { messages, uiMessages } = await memory!.query({
+// Retrieve messages with pagination
+const { messages } = await memory!.query({
   threadId: "thread-123",
-  selectBy: {
-    last: 50,
-    vectorSearchString: "What messages are there?",
-    include: [
-      {
-        id: "msg-123",
-      },
-      {
-        id: "msg-456",
-        withPreviousMessages: 3,
-        withNextMessages: 1,
-      },
-    ],
-  },
+  perPage: 50,
+  vectorSearchString: "What messages are there?",
+  include: [
+    {
+      id: "msg-123",
+    },
+    {
+      id: "msg-456",
+      withPreviousMessages: 3,
+      withNextMessages: 1,
+    },
+  ],
   threadConfig: {
     semanticRecall: true,
   },
 });
 
-console.log(messages);
-console.log(uiMessages);
+console.log(messages); // MastraDBMessage[]
+
+// Fetch all messages without pagination
+const allMessages = await memory!.query({
+  threadId: "thread-123",
+  perPage: false, // Fetch all
+});
+
+// Convert to AI SDK format if needed
+import { toAISdkV5Messages } from '@mastra/ai-sdk/ui';
+const uiMessages = toAISdkV5Messages(messages);
 ```
 
 ### Related
 
-- [Memory Class Reference](/reference/memory/memory-class)
-- [Getting Started with Memory](/docs/memory/overview)
-- [Semantic Recall](/docs/memory/semantic-recall)
-- [createThread](/reference/memory/createThread)
+- [Memory Class Reference](/reference/v1/memory/memory-class)
+- [Getting Started with Memory](/docs/v1/memory/overview)
+- [Semantic Recall](/docs/v1/memory/semantic-recall)
+- [createThread](/reference/v1/memory/createThread)

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

@@ -0,0 +1,185 @@
+---
+title: "Reference: Memory.recall() | Memory | Mastra Docs"
+description: "Documentation for the `Memory.recall()` method in Mastra, which retrieves messages from a specific thread with support for pagination, filtering options, and semantic search."
+---
+
+# Memory.recall()
+
+the `.recall()` method retrieves messages from a specific thread, with support for pagination, filtering options, and semantic search.
+
+## Usage Example
+
+```typescript copy
+await memory?.recall({ threadId: "user-123" });
+```
+
+## 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: "vectorSearchString",
+      type: "string",
+      description:
+        "Search string for finding semantically similar messages. Requires semantic recall to be enabled in threadConfig.",
+      isOptional: true,
+    },
+    {
+      name: "perPage",
+      type: "number | false",
+      description:
+        "Number of messages to retrieve per page. Set to false to fetch all messages without pagination. If not provided, defaults to threadConfig.lastMessages.",
+      isOptional: true,
+    },
+    {
+      name: "page",
+      type: "number",
+      description:
+        "Zero-based page number for pagination. Used with perPage to retrieve messages in batches.",
+      isOptional: true,
+    },
+    {
+      name: "include",
+      type: "{ id: string; threadId?: string; withPreviousMessages?: number; withNextMessages?: number }[]",
+      description:
+        "Array of specific message IDs to include with optional context messages. Each item has an `id` (required), optional `threadId` (defaults to main threadId), `withPreviousMessages` (number of messages before, defaults to 2 for vector search, 0 otherwise), and `withNextMessages` (number of messages after, defaults to 2 for vector search, 0 otherwise).",
+      isOptional: true,
+    },
+    {
+      name: "filter",
+      type: "{ dateRange?: { start?: Date; end?: Date } }",
+      description:
+        "Filter options for message retrieval. Currently supports `dateRange` to filter messages by creation date.",
+      isOptional: true,
+    },
+    {
+      name: "orderBy",
+      type: "{ field: 'createdAt'; direction: 'ASC' | 'DESC' }",
+      description:
+        "Sort order for retrieved messages. Defaults to descending by creation date.",
+      isOptional: true,
+    },
+    {
+      name: "threadConfig",
+      type: "MemoryConfig",
+      description:
+        "Configuration options for message retrieval and semantic search",
+      isOptional: true,
+    },
+
+  ]}
+/>
+
+### threadConfig parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "lastMessages",
+      type: "number | false",
+      description:
+        "Number of most recent messages to retrieve. Set to false to disable. When perPage is not explicitly provided, this value is used as the default.",
+      isOptional: true,
+      defaultValue: "10",
+    },
+    {
+      name: "semanticRecall",
+      type: "boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }",
+      description:
+        "Enable semantic search in message history. Can be a boolean or an object with configuration options. When enabled, requires both vector store and embedder to be configured.",
+      isOptional: true,
+      defaultValue: "false",
+    },
+    {
+      name: "workingMemory",
+      type: "WorkingMemory",
+      description:
+        "Configuration for working memory feature. Can be `{ enabled: boolean; template?: string; schema?: ZodObject<any> | JSONSchema7; scope?: 'thread' | 'resource' }` or `{ enabled: boolean }` to disable.",
+      isOptional: true,
+      defaultValue:
+        "{ enabled: false, template: '# User Information\\n- **First Name**:\\n- **Last Name**:\\n...' }",
+    },
+    {
+      name: "threads",
+      type: "{ generateTitle?: boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> } }",
+      description:
+        "Settings related to memory thread creation. `generateTitle` controls automatic thread title generation from the user's first message. Can be a boolean or an object with custom model and instructions.",
+      isOptional: true,
+      defaultValue: "{ generateTitle: false }",
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "messages",
+      type: "MastraDBMessage[]",
+      description: "Array of retrieved messages in the database format",
+    },
+  ]}
+/>
+
+## Extended usage example
+
+```typescript title="src/test-memory.ts" showLineNumbers copy
+import { mastra } from "./mastra";
+
+const agent = mastra.getAgent("agent");
+const memory = await agent.getMemory();
+
+// Retrieve messages with pagination
+const { messages } = await memory!.recall({
+  threadId: "thread-123",
+  perPage: 50,
+  vectorSearchString: "What messages are there?",
+  include: [
+    {
+      id: "msg-123",
+    },
+    {
+      id: "msg-456",
+      withPreviousMessages: 3,
+      withNextMessages: 1,
+    },
+  ],
+  threadConfig: {
+    semanticRecall: true,
+  },
+});
+
+console.log(messages); // MastraDBMessage[]
+
+// Fetch all messages without pagination
+const allMessages = await memory!.recall({
+  threadId: "thread-123",
+  perPage: false, // Fetch all
+});
+
+// Convert to AI SDK format if needed
+import { toAISdkV5Messages } from '@mastra/ai-sdk/ui';
+const uiMessages = toAISdkV5Messages(messages);
+```
+
+### Related
+
+- [Memory Class Reference](/reference/v1/memory/memory-class)
+- [Getting Started with Memory](/docs/v1/memory/overview)
+- [Semantic Recall](/docs/v1/memory/semantic-recall)
+- [createThread](/reference/v1/memory/createThread)