> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# Memory API

Memory API는 Mastra에서 대화 스레드 및 메시지 기록을 관리하는 방법을 제공합니다.

## 모든 스레드 가져오기

특정 리소스에 대한 모든 Memory 스레드를 검색합니다.

```typescript
const threads = await mastraClient.listMemoryThreads({
  resourceId: 'resource-1',
  agentId: 'agent-1', // Optional - can be omitted if storage is configured
})
```

`agentId`가 생략되고 서버에 스토리지가 구성되어 있으면 스토리지를 직접 사용하여 스레드를 가져옵니다. 여러 Agent가 동일한 스레드를 공유할 때 유용합니다(예: 여러 Agent 단계가 포함된 Workflow).

## 새 스레드 만들기

새 Memory 스레드를 만듭니다.

```typescript
const thread = await mastraClient.createMemoryThread({
  title: 'New Conversation',
  metadata: { category: 'support' },
  resourceId: 'resource-1',
  agentId: 'agent-1',
})
```

## 특정 스레드로 작업하기

특정 Memory 스레드의 인스턴스를 가져옵니다.

```typescript
const thread = mastraClient.getMemoryThread({ threadId: 'thread-id', agentId: 'agent-id' })
```

## 스레드 방법

### 스레드 세부정보 가져오기

특정 스레드에 대한 세부정보를 검색합니다.

```typescript
const details = await thread.get()
```

### 스레드 업데이트

스레드 속성 업데이트:

```typescript
const updated = await thread.update({
  title: 'Updated Title',
  metadata: { status: 'resolved' },
  resourceId: 'resource-1',
})
```

### 스레드 삭제

스레드 및 해당 메시지를 삭제합니다.

```typescript
await thread.delete()
```

### 스레드 복제

모든 메시지가 포함된 스레드의 복사본을 만듭니다.

```typescript
const { thread: clonedThread, clonedMessages } = await thread.clone()
```

옵션을 사용하여 복제:

```typescript
const { thread: clonedThread, clonedMessages } = await thread.clone({
  newThreadId: 'custom-clone-id',
  title: 'Cloned Conversation',
  metadata: { branch: 'experiment-1' },
  options: {
    messageLimit: 10, // Only clone last 10 messages
  },
})
```

메시지 필터링을 사용하여 복제:

```typescript
const { thread: clonedThread } = await thread.clone({
  options: {
    messageFilter: {
      startDate: new Date('2024-01-01'),
      endDate: new Date('2024-01-31'),
    },
  },
})
```

복제 응답에는 다음이 포함됩니다.

- `thread`: 복제 메타데이터가 포함된 새로 생성된 복제 스레드
- `clonedMessages`: 새 ID를 가진 복제된 메시지 배열

## 메시지 작업

### 메시지 저장

메시지를 Memory에 저장합니다.

```typescript
const result = await mastraClient.saveMessageToMemory({
  messages: [
    {
      role: 'user',
      content: 'Hello!',
      id: '1',
      threadId: 'thread-1',
      resourceId: 'resource-1',
      createdAt: new Date(),
      format: 2,
    },
  ],
  agentId: 'agent-1',
})

// result.messages contains the saved messages
console.log(result.messages)
```

### 스레드 메시지 검색

Memory 스레드와 관련된 메시지를 가져옵니다.

```typescript
// Get all messages in the thread (paginated)
const result = await thread.listMessages()
console.log(result.messages) // Array of messages
console.log(result.total) // Total count
console.log(result.hasMore) // Whether more pages exist

// Get messages with pagination
const result = await thread.listMessages({
  page: 0,
  perPage: 20,
})

// Get messages with ordering
const result = await thread.listMessages({
  orderBy: { field: 'createdAt', direction: 'ASC' },
})

// Get messages with shallow metadata filters
const result = await thread.listMessages({
  filter: {
    metadata: {
      category: 'billing',
      escalated: true,
      priority: 2,
      archivedAt: null,
    },
  },
})
```

메타데이터 필터는 얕은 스칼라 값인 `string`, 유한한 `number`, `boolean`, `null`만 일치시킵니다. 모든 키-값 쌍은 AND 의미 체계에 따라 일치해야 합니다. `null`은 값이 명시적으로 `null`로 설정된 키에만 일치합니다. 메타데이터 키는 문자 또는 밑줄로 시작해야 하며 영숫자 또는 밑줄만 포함할 수 있습니다. 길이는 128자로 제한됩니다. `__proto__`, `constructor`, `prototype`과 같은 예약된 프로토타입 키는 허용되지 않습니다. 성능은 서버 스토리지 백엔드에 따라 달라지며, 임의의 메타데이터 필터를 사용하면 후보 메시지를 스캔해야 할 수 있습니다.

### 메시지 삭제

스레드에서 하나 이상의 메시지를 삭제합니다.

```typescript
// Delete a single message
const result = await thread.deleteMessages('message-id')

// Delete multiple messages
const result = await thread.deleteMessages(['message-1', 'message-2', 'message-3'])

// Returns: { success: true, message: "Message deleted successfully" }
```

## 작업기억

작업 Memory를 통해 Agent는 상호 작용 전반에 걸쳐 사용자에 대한 지속적인 정보를 유지할 수 있습니다. 특정 스레드 또는 리소스(사용자)에 대한 모든 스레드로 범위를 지정할 수 있습니다.

### 작업 기억 얻기

스레드의 현재 작업 Memory를 검색합니다.

```typescript
const workingMemory = await mastraClient.getWorkingMemory({
  agentId: 'agent-1',
  threadId: 'thread-1',
  resourceId: 'user-123', // Optional, required for resource-scoped memory
})
```

응답에는 다음이 포함됩니다.

- `workingMemory`: 현재 작업 Memory 내용(문자열 또는 null)
- `source`: Memory의 출처가 `"thread"` 범위인지 `"resource"` 범위인지 나타냅니다
- `workingMemoryTemplate`: 작업 Memory에 사용되는 템플릿(구성된 경우)
- `threadExists`: 스레드가 존재하는지 여부

### 작업 기억 업데이트

스레드의 작업 Memory 내용을 업데이트합니다.

```typescript
await mastraClient.updateWorkingMemory({
  agentId: 'agent-1',
  threadId: 'thread-1',
  workingMemory: `# User Profile
- Name: John Doe
- Location: New York
- Preferences: Prefers formal communication
`,
  resourceId: 'user-123', // Optional, required for resource-scoped memory
})

// Returns: { success: true }
```

리소스 범위 작업 Memory에는 `resourceId` 매개변수를 제공해야 합니다. 이를 통해 해당 사용자의 모든 대화 스레드에서 Memory가 유지됩니다.

### Memory 상태 가져오기

Memory 시스템의 상태를 확인하십시오.

```typescript
const status = await mastraClient.getMemoryStatus('agent-id')
```