内存

🌐 Memory

内存配置现在需要明确的参数，并且默认设置已更新，以实现更好的性能和可预测性。

🌐 Memory configuration now requires explicit parameters, and default settings have been updated for better performance and predictability.

已更改

🌐 Changed

语义回溯和最后消息的默认设置

🌐 Default settings for semantic recall and last messages

默认设置已根据使用模式更改为更合理的值。lastMessages 的默认值从 40 降到了 10，semanticRecall 现在默认禁用，线程标题生成默认也被禁用。这些更改提高了性能并减少了意外的 LLM API 调用。

🌐 Default settings have changed to more reasonable values based on usage patterns. The lastMessages default decreased from 40 to 10, semanticRecall is now disabled by default, and thread title generation is disabled by default. These changes improve performance and reduce unexpected LLM API calls.

如果要迁移，并且你以前依赖旧的默认设置，请明确配置这些设置。

🌐 To migrate, if you were relying on the old defaults, explicitly configure these settings.

  const memory = new Memory({
    storage,
    vector,
    embedder,
+   options: {
+     lastMessages: 40, // Was default before
+     semanticRecall: {
+       topK: 2,
+       messageRange: 2,
+       scope: 'thread',
+     }, // Was enabled by default before
+     generateTitle: true, // Was enabled by default before
+   },
  });

默认内存范围从 thread 到 resource

🌐 Default memory scope from thread to resource

工作内存和语义回忆的默认范围已从 'thread' 更改为 'resource'。此更改符合常见的使用场景，即应用希望在多次对话中记住用户信息。当启用语义回忆时，现在默认会搜索所有用户对话，而不仅仅是当前线程。

🌐 The default scope for both working memory and semantic recall has changed from 'thread' to 'resource'. This change aligns with common use cases where applications want to remember user information across conversations. When semantic recall is enabled, it now defaults to searching across all user conversations rather than just the current thread.

如果要迁移，并且希望保持每个会话线程内存隔离的旧行为，请明确设置 scope: 'thread'。

🌐 To migrate, if you want to maintain the old behavior where memory is isolated per conversation thread, explicitly set scope: 'thread'.

  const memory = new Memory({
    storage,
    vector,
    embedder,
    options: {
      workingMemory: {
        enabled: true,
+       scope: 'thread', // Explicitly set to thread-scoped
        template: `# User Profile...`,
      },
      semanticRecall: {
        topK: 3,
+       scope: 'thread', // Explicitly set to thread-scoped
      },
    },
  });

线程标题生成位置

🌐 Thread title generation location

generateTitle 选项已从 threads.generateTitle 移动到内存选项的顶层。此更改通过将选项移到其逻辑上所属的位置，从而简化了 API。

🌐 The generateTitle option has been moved from threads.generateTitle to the top-level of memory options. This change simplifies the API by moving the option to where it logically belongs.

要进行迁移，请将 generateTitle 从 threads 配置移到选项的顶层。

🌐 To migrate, move generateTitle from the threads config to the top level of options.

  const memory = new Memory({
    storage,
    vector,
    embedder,
    options: {
-     threads: {
-       generateTitle: true,
-     },
+     generateTitle: true,
    },
  });

语义回忆默认设置优化

🌐 Semantic recall default settings optimization

语义召回的默认设置已根据 RAG 研究进行了优化。topK 从 2 提升到 4，messageRange 从 { before: 2, after: 2 } 改为 { before: 1, after: 1 }。这些更改在仅略微增加消息数量的情况下提高了准确性。

🌐 The default settings for semantic recall have been optimized based on RAG research. The topK increased from 2 to 4, and messageRange changed from { before: 2, after: 2 } to { before: 1, after: 1 }. These changes provide better accuracy while only slightly increasing message count.

如果要迁移，并且之前依赖于默认设置，请明确设置这些值。

🌐 To migrate, if you were relying on the previous defaults, explicitly set these values.

  const memory = new Memory({
    storage,
    vector,
    embedder,
    options: {
      semanticRecall: {
+       topK: 2, // Was default before
+       messageRange: { before: 2, after: 2 }, // Was default before
      },
    },
  });

memory.readOnly 移动到了 memory.options.readOnly

🌐 memory.readOnly moved to memory.options.readOnly

readOnly 属性已从内存选项的顶层移动到 options 内部。此更改使 readOnly 与其他内存配置选项（如 lastMessages 和 semanticRecall）保持一致。

🌐 The readOnly property has been moved from the top-level of the memory option to inside options. This change aligns readOnly with other memory configuration options like lastMessages and semanticRecall.

要迁移，请将 readOnly 从顶层移动到 options 内部。

🌐 To migrate, move readOnly from the top level to inside options.

  agent.stream('Hello', {
    memory: {
      thread: threadId,
      resource: resourceId,
-     readOnly: true,
+     options: {
+       readOnly: true,
+     },
    },
  });

Codemod

你可以使用 Mastra 的 codemod CLI 来自动更新你的代码：

🌐 You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@latest v1/memory-readonly-to-options .

Memory.query() 已重命名为 Memory.recall()

🌐 Memory.query() renamed to Memory.recall()

Memory.query() 方法已重命名为 Memory.recall()。新方法返回一个更简单的格式，仅包含 { messages: MastraDBMessage[] }，而不是多种格式的变化。此更改更好地描述了从内存中检索消息的操作，并简化了 API。

🌐 The Memory.query() method has been renamed to Memory.recall(). The new method returns a simpler format with just { messages: MastraDBMessage[] } instead of multiple format variations. This change better describes the action of retrieving messages from memory and simplifies the API.

要进行迁移，请将 query() 重命名为 recall()，并更新依赖旧返回格式的代码。

🌐 To migrate, rename query() to recall() and update code that expects the old return format.

- const result = await memory.query({ threadId: 'thread-123' });
+ const result = await memory.recall({ threadId: 'thread-123' });
- // result: { messages: CoreMessage[], uiMessages: UIMessageWithMetadata[], messagesV2: MastraMessageV2[] }
+ // result: { messages: MastraDBMessage[] }
+ const messages = result.messages;

Codemod

你可以使用 Mastra 的 codemod CLI 来自动更新你的代码：

🌐 You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@latest v1/memory-query-to-recall .

Memory.recall() 参数更改

🌐 Memory.recall() parameter changes

Memory.recall() 方法现在使用带分页的 StorageListMessagesInput 格式，并且 vectorMessageSearch 参数已重命名为 vectorSearchString。这些更改使内存 API 与存储分页 API 保持一致，并提供更一致的命名。

🌐 The Memory.recall() method now uses StorageListMessagesInput format with pagination, and the vectorMessageSearch parameter has been renamed to vectorSearchString. These changes align the memory API with the storage pagination API and provide more consistent naming.

要迁移，请更新方法名称、查询参数以及向量搜索参数。

🌐 To migrate, update method name, query parameters, and the vector search parameter.

- memory.query({
+ memory.recall({
    threadId: 'thread-123',
-   vectorMessageSearch: 'What did we discuss?',
-   selectBy: { ... },
+   vectorSearchString: 'What did we discuss?',
+   page: 0,
+   perPage: 20,
+   orderBy: 'createdAt',
+   filter: { ... },
+   threadConfig: { semanticRecall: true },
  });

Codemod

你可以使用 Mastra 的 codemod CLI 来自动更新你的代码：

🌐 You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@latest v1/memory-vector-search-param .

MastraMessageV2 类型已重命名为 MastraDBMessage

🌐 MastraMessageV2 type renamed to MastraDBMessage

MastraMessageV2 类型已被重命名为 MastraDBMessage，以提高清晰度。此更改更好地描述了此类型作为数据库消息格式的用途。

🌐 The MastraMessageV2 type has been renamed to MastraDBMessage for clarity. This change better describes the purpose of this type as the database message format.

要迁移，请将所有MastraMessageV2实例替换为MastraDBMessage。

🌐 To migrate, replace all instances of MastraMessageV2 with MastraDBMessage.

- import { MastraMessageV2 } from '@mastra/core';
- function yourCustomFunction(input: MastraMessageV2) {}
+ import { MastraDBMessage } from '@mastra/core';
+ function yourCustomFunction(input: MastraDBMessage) {}

Codemod

你可以使用 Mastra 的 codemod CLI 来自动更新你的代码：

🌐 You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@latest v1/memory-message-v2-type .

已移除

🌐 Removed

工作内存 text-stream 模式

🌐 Working memory text-stream mode

工作内存 use: "text-stream" 选项已被移除。仅支持 tool-call 模式。此更改通过移除不太可靠的流模式简化了工作内存 API。

🌐 Working memory use: "text-stream" option has been removed. Only tool-call mode is supported. This change simplifies the working memory API by removing the less reliable streaming mode.

要迁移，请移除 use: "text-stream" 选项。工作内存将默认使用工具调用模式。

🌐 To migrate, remove the use: "text-stream" option. Working memory will default to tool-call mode.

  const memory = new Memory({
    storage,
    vector,
    embedder,
    options: {
      workingMemory: {
        enabled: true,
-       use: 'text-stream',
        template: '...',
      },
    },
  });

Memory.rememberMessages() 方法

🌐 Memory.rememberMessages() method

Memory.rememberMessages() 方法已被移除。该方法执行的功能与 query()（现为 recall()）相同，将其合并为一个方法可以简化 API。

🌐 The Memory.rememberMessages() method has been removed. This method performed the same function as query() (now recall()), and consolidating to one method simplifies the API.

要进行迁移，请将 rememberMessages() 调用替换为 recall()。

🌐 To migrate, replace rememberMessages() calls with recall().

- const { messages } = await memory.rememberMessages({
+ const { messages } = await memory.recall({
    threadId,
    resourceId,
  });

format 参数来自内存方法

🌐 format parameter from memory methods

format 参数已从所有内存获取方法中移除。MastraDBMessage 现在是所有地方的默认返回格式。AI SDK 的格式转换已移至 @mastra/ai-sdk/ui 中的专用工具函数。这一变化通过将特定于 UI 的转换代码移到单独的包中来改善树摇优化。

🌐 The format parameter has been removed from all memory get methods. MastraDBMessage is now the default return format everywhere. AI SDK format conversion has moved to dedicated utility functions in @mastra/ai-sdk/ui. This change improves tree-shaking by moving UI-specific conversion code to a separate package.

要进行迁移，请删除 format 参数并使用转换函数处理 AI SDK 格式。

🌐 To migrate, remove the format parameter and use conversion functions for AI SDK formats.

- const messages = await memory.getMessages({ threadId, format: 'v2' });
- const uiMessages = await memory.getMessages({ threadId, format: 'ui' });

+ const result = await memory.recall({ threadId });
+ const messages = result.messages; // Always MastraDBMessage[]
+ 
+ // Use conversion functions for AI SDK formats
+ import { toAISdkV5Messages } from '@mastra/ai-sdk/ui';
+ const uiMessages = toAISdkV5Messages(messages);

MastraMessageV3 型

🌐 MastraMessageV3 type

MastraMessageV3 类型及相关的转换方法已被移除。消息现在可以在 MastraMessageV2（现为 MastraDBMessage）和 AI SDK v5 格式之间直接转换。此更改通过移除中间格式简化了架构。

🌐 The MastraMessageV3 type and related conversion methods have been removed. Messages now convert directly between MastraMessageV2 (now MastraDBMessage) and AI SDK v5 formats. This change simplifies the architecture by removing an intermediary format.

要进行迁移，请直接使用 MastraDBMessage 进行存储或使用 AI SDK v5 消息格式。

🌐 To migrate, use MastraDBMessage for storage or AI SDK v5 message formats directly.

- import type { MastraMessageV3 } from '@mastra/core/agent';
- const v3Messages = messageList.get.all.v3();

+ // For storage
+ const v2Messages = messageList.get.all.v2();
+ 
+ // For AI SDK v5
+ const uiMessages = messageList.get.all.aiV5.ui();
+ const modelMessages = messageList.get.all.aiV5.model();

processors 配置来自 Memory 构造函数

🌐 processors config from Memory constructor

Memory 构造函数中的 processors 配置选项已被弃用，现在会抛出错误。处理器应在 Agent 级别进行配置。此更改提供了更清晰的配置边界和更好的封装性。

🌐 The processors config option in the Memory constructor has been deprecated and now throws an error. Processors should be configured at the Agent level instead. This change provides clearer configuration boundaries and better encapsulation.

要进行迁移，请使用 inputProcessors 和/或 outputProcessors 将处理器配置从内存移动到代理。

🌐 To migrate, move processor configuration from Memory to Agent using inputProcessors and/or outputProcessors.

+ import { TokenLimiter } from '@mastra/core/processors';
+
  const memory = new Memory({
    storage,
    vector,
    embedder,
-   processors: [/* ... */],
  });

  const agent = new Agent({
    memory,
+   inputProcessors: [
+     new TokenLimiter({ limit: 4000 }), // Limits historical messages to fit context window
+   ],
  });

此外，@mastra/memory/processors 导入路径已被移除。请改为从 @mastra/core/processors 导入处理器。有关详细信息，请参阅 处理器迁移指南。

🌐 Additionally, the @mastra/memory/processors import path has been removed. Import processors from @mastra/core/processors instead. See the processors migration guide for details.

有关在代理中使用处理器的更多信息，请参阅 Processors 文档。有关带有内存的完整示例，请参阅 TokenLimiter 参考。

🌐 For more information on using processors with agents, see the Processors docs. For a complete example with memory, see the TokenLimiter reference.