> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/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,
+     },
    },
  });
```

:::tip\[코드모드]

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;
```

:::tip\[코드모드]

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

:::tip\[코드모드]

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

:::tip\[코드모드]

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

```bash
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 호출 모드를 사용합니다.

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

### `format`Memory 메소드의 매개변수

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

### `processors`Memory 생성자의 구성

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/ko/guides/migrations/upgrade-to-v1/processors)를 참조하세요. Agent와 함께 프로세서를 사용하는 방법에 관한 자세한 내용은 [프로세서 문서](https://mastra.zisheng.pro/ko/docs/agents/processors)를 참조하세요. Memory를 포함한 전체 예제는 [TokenLimiter 레퍼런스](https://mastra.zisheng.pro/ko/reference/processors/token-limiter-processor)를 참조하세요.