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

工作 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 .

已移除

工作 Memory 的 text-stream 模式

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

遷移時，請移除 use: "text-stream" 選項。工作 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 執行。

遷移時，請將處理器設定從 Memory 移至 Agent，並使用 inputProcessors 及／或 outputProcessors。

+ 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 參考文件。