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,
+     },
    },
  });

:::tip[코드모드]

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;

:::tip[코드모드]

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 },
  });

:::tip[코드모드]

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) {}

:::tip[코드모드]

Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

npx @mastra/codemod@latest v1/memory-message-v2-type .

:::

제거됨

작업기억text-stream mode

작업 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,
  });

formatMemory 메소드의 매개변수

모든 Memory get 메서드에서 format 매개변수가 제거되었습니다. 이제 어디서나 MastraDBMessage가 기본 반환 형식입니다. AI SDK 형식 변환은 @mastra/ai-sdk/ui의 전용 유틸리티 함수로 이동했습니다. 이 변경은 UI 전용 변환 코드를 별도 패키지로 이동하여 트리 셰이킹을 개선합니다. 마이그레이션하려면 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();

processorsMemory 생성자의 구성

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 레퍼런스를 참조하세요.