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

# 의미적 회상

그만큼`SemanticRecall`는**하이브리드 프로세서**벡터 임베딩을 사용하여 대화 기록에 대한 의미 검색을 가능하게 합니다. 입력 시 의미론적 검색을 수행하여 관련 역사적 메시지를 찾습니다. 출력 시에는 향후 의미 검색이 가능하도록 새 메시지에 대한 임베딩을 생성합니다.

## 사용예

```typescript
import { SemanticRecall } from '@mastra/core/processors'
import { openai } from '@ai-sdk/openai'

const processor = new SemanticRecall({
  storage: memoryStorage,
  vector: vectorStore,
  embedder: openai.embedding('text-embedding-3-small'),
  topK: 5,
  messageRange: 2,
  scope: 'resource',
})
```

## 생성자 매개변수

**options** (`SemanticRecallOptions`): 의미론적 회상 프로세서의 구성 옵션

**options.storage** (`MemoryStorage`): 메시지를 가져올 스토리지 인스턴스

**options.vector** (`MastraVector`): 의미론적 검색을 위한 벡터 저장소

**options.embedder** (`MastraEmbeddingModel<string>`): 쿼리 임베딩을 생성하는 임베더

**options.topK** (`number`): 가장 유사한 메시지 중 가져올 개수

**options.messageRange** (`number | { before: number; after: number }`): 각 일치 항목 전후에 포함할 컨텍스트 메시지 수. 단일 숫자(양쪽에 동일하게 적용) 또는 별도 값을 가진 객체를 사용할 수 있습니다

**options.scope** (`'thread' | 'resource'`): 의미론적 검색의 범위. 'thread'는 현재 스레드 내에서만 검색합니다. 'resource'는 해당 리소스의 모든 스레드를 검색합니다

**options.threshold** (`number`): 최소 유사도 점수 임곗값(0\~1). 이 임곗값보다 낮은 메시지는 필터링됩니다

**options.indexName** (`string`): 벡터 저장소의 인덱스 이름. 제공하지 않으면 임베더 Model을 기반으로 자동 생성됩니다

**options.logger** (`IMastraLogger`): 구조화된 로깅을 위한 선택적 로거 인스턴스

## 보고

**id** (`string`): 'semantic-recall'로 설정된 프로세서 식별자

**name** (`string`): 'SemanticRecall'로 설정된 프로세서 표시 이름

**processInput** (`(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>`): 과거 메시지를 의미론적으로 검색하고 관련 컨텍스트를 메시지 목록에 추가합니다

**processOutputResult** (`(args: { messages: MastraDBMessage[]; messageList?: MessageList; abort: (reason?: string) => never; tracingContext?: TracingContext; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>`): 향후 의미론적 검색을 사용할 수 있도록 새 메시지의 임베딩을 생성합니다

## 확장된 사용 예

```typescript
import { Agent } from '@mastra/core/agent'
import { SemanticRecall, MessageHistory } from '@mastra/core/processors'
import { PostgresStorage } from '@mastra/pg'
import { PgVector } from '@mastra/pg'
import { openai } from '@ai-sdk/openai'

const storage = new PostgresStorage({
  id: 'pg-storage',
  connectionString: process.env.DATABASE_URL,
})

const vector = new PgVector({
  id: 'pg-vector',
  connectionString: process.env.DATABASE_URL,
})

const semanticRecall = new SemanticRecall({
  storage,
  vector,
  embedder: openai.embedding('text-embedding-3-small'),
  topK: 5,
  messageRange: { before: 2, after: 1 },
  scope: 'resource',
  threshold: 0.7,
})

export const agent = new Agent({
  id: 'semantic-memory-agent',
  name: 'semantic-memory-agent',
  instructions: 'You are a helpful assistant with semantic memory recall',
  model: 'openai/gpt-5.6-sol',
  inputProcessors: [semanticRecall, new MessageHistory({ storage, lastMessages: 50 })],
  outputProcessors: [semanticRecall, new MessageHistory({ storage })],
})
```

## 행동

### 입력 처리

1. 마지막 사용자 메시지에서 사용자 쿼리를 추출합니다.
2. 쿼리의 임베딩을 생성합니다.
3. 의미론적으로 유사한 메시지를 찾기 위해 벡터 검색을 수행합니다.
4. `messageRange`에 따라 주변 컨텍스트와 함께 일치하는 메시지를 가져옵니다.
5. `scope: 'resource'`인 경우 스레드 간 메시지를 타임스탬프가 포함된 시스템 메시지로 구성합니다.
6. 가져온 메시지를 `source: 'memory'` 태그와 함께 추가합니다.

### 출력 처리

1. 새로운 사용자 및 보조자 메시지에서 텍스트 콘텐츠를 추출합니다.
2. 각 메시지에 대한 임베딩을 생성합니다.
3. 메타데이터(메시지 ID, 스레드 ID, 리소스 ID, 역할, 콘텐츠, 타임스탬프)와 함께 벡터 저장소에 임베딩을 저장합니다.
4. 중복 API 호출을 방지하기 위해 임베딩에 LRU 캐싱을 사용합니다.

### 크로스 스레드 리콜

`scope`를 `'resource'`로 설정하면 프로세서가 다른 스레드의 메시지를 회상할 수 있습니다. 이러한 스레드 간 메시지는 대화가 언제 어디서 이루어졌는지에 관한 컨텍스트를 제공하도록 타임스탬프와 대화 레이블이 포함된 시스템 메시지로 구성됩니다.

## 관련된

- [난간](https://mastra.zisheng.pro/ko/docs/agents/guardrails)