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

working memory 及語義回憶的預設範圍已從 '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 設定移至選項頂層。

  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 與儲存空間分頁 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 .

已移除

Working memory text-stream 模式

working memory 的 use: "text-stream" 選項已移除，現在只支援 tool-call 模式。這項變更移除較不可靠的串流模式，令 working memory API 更簡潔。

如要遷移，請移除 use: "text-stream" 選項。working memory 將預設使用 Tool 呼叫模式。

  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 層級設定處理器，讓處理器行為限定於 Agent 執行範圍內。

如要遷移，請使用 inputProcessors 及／或 outputProcessors，將處理器設定從 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 匯入處理器。詳情請參閱處理器遷移指南。

如要進一步了解如何搭配 Agent 使用處理器，請參閱處理器文件。如要查看搭配 Memory 的完整範例，請參閱 TokenLimiter 參考資料。