> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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` 工作 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 . > ``` ## 已移除 ### 工作 Memory 的 `text-stream` 模式 工作 Memory 的 `use: "text-stream"` 選項已移除，現在只支援 `tool-call` 模式。這項變更移除較不可靠的串流模式，簡化工作 Memory API。 遷移時，請移除 `use: "text-stream"` 選項。工作 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 執行。 遷移時，請將處理器設定從 Memory 移至 Agent，並使用 `inputProcessors` 及／或 `outputProcessors`。 ```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-TW/guides/migrations/upgrade-to-v1/processors)。 如需進一步瞭解如何將處理器與 Agent 搭配使用，請參閱[處理器文件](https://mastra.zisheng.pro/zh-TW/docs/agents/processors)。如需包含 Memory 的完整範例，請參閱 [TokenLimiter 參考文件](https://mastra.zisheng.pro/zh-TW/reference/processors/token-limiter-processor)。