# 의미론적 검색 (임베딩)

Synapse는 벡터 임베딩을 사용한 의미론적 검색을 지원합니다. FTS5 (키워드
매칭)와 달리 의미론적 검색은 키워드가 일치하지 않더라도 **의미**로
메모리를 찾습니다.

## 작동 방식

```
1. Memory stored → embedding generated → vector stored
2. Search query → embedding generated → vector compared
3. Cosine similarity → top N results returned
```

### 임베딩이란?

임베딩은 텍스트의 수치적 벡터 표현입니다. 유사한 의미를 가진 텍스트는
유사한 벡터를 가집니다. Synapse는 각 메모리의 콘텐츠에 대해 벡터 (예:
1536차원)를 생성합니다.

### 코사인 유사도

의미론적으로 유사한 메모리를 찾기 위해 Synapse는 쿼리 벡터와 각 메모리
벡터 간의 코사인 유사도를 계산합니다. 유사도가 높을수록 더 관련성이
높습니다.

## 의미론적 검색 사용 시기

### 의미론적 검색을 사용할 때:

- 저장된 것과 다르게 설명된 "X에 대한 메모리"를 원할 때
- FTS5가 결과를 반환하지 않을 때 (키워드 매칭 없음)
- 개념적 그룹화를 원할 때 (예: 일부가 "release"라고 말하더라도 모든 "deployment" 메모리)
- 쿼리가 질문일 때: "인증은 어떻게 처리합니까?"

### FTS5를 사용할 때:

- 정확한 키워드를 알 때
- 불린 로직 (AND, OR, NOT)이 필요할 때
- 서브밀리초 응답이 필요할 때
- 구문 매칭을 원할 때

## 엔드포인트

### GET /memory/semantic-search

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"
```

응답:

```json
{
  "results": [
    {
      "id": "mem_001",
      "category": "project",
      "key": "project_synapse_deployment",
      "content": "Synapse deployed using Docker Swarm on vps1...",
      "tags": ["docker", "swarm", "deployment"],
      "similarity": 0.89
    },
    {
      "id": "mem_042",
      "category": "fact",
      "key": "kubernetes_cluster",
      "content": "We use Kubernetes for production orchestration...",
      "tags": ["kubernetes", "orchestration"],
      "similarity": 0.84
    }
  ]
}
```

## 예시

### 배포 메모리 찾기

```bash
# FTS5 might miss some — semantic catches all
curl .../memory/semantic-search?q=deployment+process
```

"deployment", "release", "publishing", "rolling out" 등에 대한 메모리를
반환합니다.

### 인증 패턴 찾기

```bash
curl .../memory/semantic-search?q=how+do+users+log+in
```

login, auth, JWT, session management, OAuth 등에 대한 메모리를 반환합니다.

### 유사한 메모리 찾기

```bash
# Find memories similar to a specific one
curl .../memory/related/mem_001
```

(공유 태그 및 임베딩 벡터를 통해) 의미론적 유사도를 사용합니다.

## 임베딩 생성

### 임베딩은 언제 생성되나요?

- **메모리 저장 시** — 임베딩 서비스가 구성된 경우, 동기적으로 임베딩 생성
- **배치 생성** — `POST /memory/embed-batch`가 임베딩이 없는 메모리의 임베딩 생성
- **비동기 업데이트** — 콘텐츠가 업데이트되면 임베딩 재생성

### 임베딩 제공자

Synapse는 구성 가능한 임베딩 제공자를 지원합니다:

- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)
- **로컬 모델** (Ollama 등을 통해)
- **사용자 정의** (임베딩 인터페이스 구현)

환경 변수로 구성:

```bash
EMBEDDINGS_PROVIDER=openai
EMBEDDINGS_API_KEY=sk-...
EMBEDDINGS_MODEL=text-embedding-3-small
```

### 배치 생성

임베딩이 누락된 메모리가 많은 마인드의 경우:

```bash
# Generate embeddings for up to 100 memories
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'

# Check progress
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status
```

## 성능

| 작업 | 지연 시간 |
|-----------|---------|
| 임베딩 생성 (OpenAI) | 100-200ms |
| 의미론적 검색 (1k 메모리) | 50-100ms |
| 의미론적 검색 (10k 메모리) | 200-500ms |
| 배치 생성 (100 메모리) | 10-20s |

> [!NOTE]
> 의미론적 검색은 벡터 계산으로 인해 FTS5보다 느립니다. 알려진 키워드에는
> FTS5를, 개념적 쿼리에는 의미론적 검색을 사용하십시오.

## 제한 사항

### 임베딩 비용

OpenAI를 사용하는 경우, 임베딩 생성에 비용이 듭니다 (text-embedding-3-small의
경우 1M 토큰당 ~$0.02). 평균 100 토큰인 10,000개 메모리의 경우
~$0.02 — 무시할 수 있는 수준입니다.

### 콜드 스타트

임베딩이 구성되기 전에 저장된 메모리는 임베딩이 없습니다. `POST
/memory/embed-batch`를 실행하여 백필하십시오.

### 제공자 의존성

임베딩 제공자가 다운된 경우, 의미론적 검색은 정상적으로 실패합니다 (빈
결과 또는 오류 반환). FTS5는 여전히 작동합니다.

## 임베딩을 사용할 수 없는 경우

임베딩 서비스가 구성되지 않은 경우:

- `GET /memory/semantic-search`가 503 Service Unavailable 반환
- `POST /memory`는 여전히 작동 (임베딩만 생성 안 됨)
- FTS5 검색은 여전히 작동

## 모범 사례

> [!TIP]
> - **개념적 쿼리에 의미론적 검색 사용** — "X를 어떻게 처리합니까?"
> - **특정 용어에 FTS5 사용** — "docker swarm"
> - **정기적으로 임베딩 백필** — `POST /memory/embed-batch`
> - **제공자 상태 모니터링** — 의미론적 검색은 이에 의존
> - **태그와 결합** — 의미론적 + 태그 필터가 결과를 좁힘

## 다음 단계

- [FTS5 검색](/docs/concepts/fts5-search)
- [Memory API](/docs/api/memory)
- [아키텍처](/docs/concepts/architecture)