Memory

Memory 配置现在需要显式参数，并更新了默认设置，以提高性能和可预测性。

已变更

语义召回和最近消息的默认设置

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

迁移时，如果依赖旧的默认值，请显式配置这些设置。

  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
+   },
  });

Memory 默认作用域从 thread 改为 resource

工作记忆和语义召回的默认作用域都已从 'thread' 改为 'resource'。这与应用需要跨会话记住用户信息的常见用例相符。启用语义召回后，现在默认搜索用户的所有会话，而不只是当前线程。

迁移时，如果希望保留按会话线程隔离 Memory 的旧行为，请显式设置 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
      },
    },
  });

线程标题生成选项的位置

generateTitle 选项已从 threads.generateTitle 迁移到 Memory 选项的顶层。将该选项移至更符合逻辑的位置可简化 API。

迁移时，请将 generateTitle 从 threads 配置移至 options 顶层。

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

优化语义召回的默认设置

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

迁移时，如果依赖之前的默认值，请显式设置这些值。

  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

readOnly 属性已从 Memory 选项的顶层移至 options 内。此变更让 readOnly 与 lastMessages、semanticRecall 等其他 Memory 配置选项保持一致。

迁移时，请将 readOnly 从顶层移至 options 内。

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

Codemod

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

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

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

Memory.query() 方法已重命名为 Memory.recall()。新方法返回更简单的 { messages: MastraDBMessage[] } 格式，不再提供多种格式变体。此变更更准确地描述了从 Memory 检索消息的操作，同时简化了 API。

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

- 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 自动更新代码：

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

Memory.recall() 参数变更

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

迁移时，请更新方法名、查询参数和向量搜索参数。

- 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 自动更新代码：

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

MastraMessageV2 类型重命名为 MastraDBMessage

为使含义更清晰，MastraMessageV2 类型已重命名为 MastraDBMessage。新名称更准确地说明了该类型作为数据库消息格式的用途。

迁移时，请将所有 MastraMessageV2 替换为 MastraDBMessage。

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

Codemod

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

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

已移除

工作记忆的 text-stream 模式

工作记忆的 use: "text-stream" 选项已移除，目前仅支持 tool-call 模式。移除可靠性较低的流式模式后，工作记忆 API 得到简化。

迁移时，请移除 use: "text-stream" 选项。工作记忆将默认使用 tool-call 模式。

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

Memory.rememberMessages() 方法

Memory.rememberMessages() 方法已移除。该方法与 query()（现为 recall()）功能相同，统一为一个方法可简化 API。

迁移时，请将 rememberMessages() 调用替换为 recall()。

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

Memory 方法中的 format 参数

所有 Memory get 方法中的 format 参数均已移除。MastraDBMessage 现在是各处的默认返回格式。AI SDK 格式转换已迁移到 @mastra/ai-sdk/ui 中的专用工具函数。将 UI 特有的转换代码移至独立包后，可改善 tree-shaking。

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

- 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 类型及相关转换方法已移除。消息现在直接在 MastraMessageV2（现为 MastraDBMessage）与 AI SDK v5 格式之间转换。移除中间格式后，架构得到简化。

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

- 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();

Memory 构造函数中的 processors 配置

Memory 构造函数中的 processors 配置选项已不再受支持，并会抛出错误。请在 Agent 层级配置 Processor，使其行为限定于 Agent 执行范围。

迁移时，请使用 inputProcessors 和/或 outputProcessors 将 Processor 配置从 Memory 移至 Agent。

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

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

此外，@mastra/memory/processors 导入路径已移除。请改为从 @mastra/core/processors 导入 Processor。详情请参阅 Processor 迁移指南。

有关在 Agent 中使用 Processor 的更多信息，请参阅 Processor 文档。有关结合 Memory 的完整示例，请参阅 TokenLimiter 参考。