> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt # Memory Memory 配置现在需要显式参数，并更新了默认设置，以提高性能和可预测性。 ## 已变更 ### 语义召回和最近消息的默认设置 默认设置已根据使用模式调整为更合理的值。`lastMessages` 的默认值从 40 降至 10，`semanticRecall` 现在默认禁用，线程标题生成也默认禁用。这些变更可提高性能，并减少意外的 LLM API 调用。 迁移时，如果依赖旧的默认值，请显式配置这些设置。 ```diff 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'`。 ```diff 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 顶层。 ```diff 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 }`。这些变更仅略微增加消息数量，同时提高准确性。 迁移时，如果依赖之前的默认值，请显式设置这些值。 ```diff 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` 内。 ```diff agent.stream('Hello', { memory: { thread: threadId, resource: resourceId, - readOnly: true, + options: { + readOnly: true, + }, }, }); ``` > **Codemod:** 你可以使用 Mastra 的 codemod CLI 自动更新代码： > > ```bash > npx @mastra/codemod@latest v1/memory-readonly-to-options . > ``` ### `Memory.query()` 重命名为 `Memory.recall()` `Memory.query()` 方法已重命名为 `Memory.recall()`。新方法返回更简单的 `{ messages: MastraDBMessage[] }` 格式，不再提供多种格式变体。此变更更准确地描述了从 Memory 检索消息的操作，同时简化了 API。 迁移时，请将 `query()` 重命名为 `recall()`，并更新依赖旧返回格式的代码。 ```diff - 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 自动更新代码： > > ```bash > npx @mastra/codemod@latest v1/memory-query-to-recall . > ``` ### `Memory.recall()` 参数变更 `Memory.recall()` 方法现在使用带分页的 `StorageListMessagesInput` 格式，`vectorMessageSearch` 参数也已重命名为 `vectorSearchString`。这些变更让 Memory API 与 Storage 分页 API 保持一致，并提供更统一的命名。 迁移时，请更新方法名、查询参数和向量搜索参数。 ```diff - 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 自动更新代码： > > ```bash > npx @mastra/codemod@latest v1/memory-vector-search-param . > ``` ### `MastraMessageV2` 类型重命名为 `MastraDBMessage` 为使含义更清晰，`MastraMessageV2` 类型已重命名为 `MastraDBMessage`。新名称更准确地说明了该类型作为数据库消息格式的用途。 迁移时，请将所有 `MastraMessageV2` 替换为 `MastraDBMessage`。 ```diff - import { MastraMessageV2 } from '@mastra/core'; - function yourCustomFunction(input: MastraMessageV2) {} + import { MastraDBMessage } from '@mastra/core'; + function yourCustomFunction(input: MastraDBMessage) {} ``` > **Codemod:** 你可以使用 Mastra 的 codemod CLI 自动更新代码： > > ```bash > npx @mastra/codemod@latest v1/memory-message-v2-type . > ``` ## 已移除 ### 工作记忆的 `text-stream` 模式 工作记忆的 `use: "text-stream"` 选项已移除，目前仅支持 `tool-call` 模式。移除可靠性较低的流式模式后，工作记忆 API 得到简化。 迁移时，请移除 `use: "text-stream"` 选项。工作记忆将默认使用 tool-call 模式。 ```diff const memory = new Memory({ storage, vector, embedder, options: { workingMemory: { enabled: true, - use: 'text-stream', template: '...', }, }, }); ``` ### `Memory.rememberMessages()` 方法 `Memory.rememberMessages()` 方法已移除。该方法与 `query()`（现为 `recall()`）功能相同，统一为一个方法可简化 API。 迁移时，请将 `rememberMessages()` 调用替换为 `recall()`。 ```diff - 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 格式。 ```diff - 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 消息格式。 ```diff - 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。 ```diff + 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 迁移指南](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/processors)。 有关在 Agent 中使用 Processor 的更多信息，请参阅 [Processor 文档](https://mastra.zisheng.pro/docs/agents/processors)。有关结合 Memory 的完整示例，请参阅 [TokenLimiter 参考](https://mastra.zisheng.pro/reference/processors/token-limiter-processor)。