> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/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` working memory 及語義回憶的預設範圍已從 `'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` 設定移至選項頂層。 ```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 與儲存空間分頁 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 . > ``` ## 已移除 ### Working memory `text-stream` 模式 working memory 的 `use: "text-stream"` 選項已移除，現在只支援 `tool-call` 模式。這項變更移除較不可靠的串流模式，令 working memory API 更簡潔。 如要遷移，請移除 `use: "text-stream"` 選項。working memory 將預設使用 Tool 呼叫模式。 ```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 層級設定處理器，讓處理器行為限定於 Agent 執行範圍內。 如要遷移，請使用 `inputProcessors` 及／或 `outputProcessors`，將處理器設定從 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` 匯入處理器。詳情請參閱[處理器遷移指南](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/processors)。 如要進一步了解如何搭配 Agent 使用處理器，請參閱[處理器文件](https://mastra.zisheng.pro/zh-HK/docs/agents/processors)。如要查看搭配 Memory 的完整範例，請參閱 [TokenLimiter 參考資料](https://mastra.zisheng.pro/zh-HK/reference/processors/token-limiter-processor)。