# Memory API

Memory API는 Synapse의 핵심입니다. 구조화된 메모리를 저장, 검색, 검색 및
관리하기 위한 22개의 엔드포인트를 제공합니다. 모든 엔드포인트는 인증을 위해
Mind Key가 필요합니다.

> [!CRITICAL]
> **모든 세션 시작 시 `GET /memory/recall`을 반드시 호출하십시오.** 이것이
> 이전 세션의 컨텍스트를 재구성하는 유일한 방법입니다.

## 카테고리

메모리는 8개 카테고리로 구성됩니다:

| 카테고리 | 사용 사례 |
|----------|----------|
| `identity` | 사용자 이름, 역할, 연락처 정보, 자신에 대한 선호도 |
| `preference` | 좋아함, 싫어함, 작업 스타일, 커뮤니케이션 선호도 |
| `fact` | 검증 가능한 사실 (프로젝트 세부 정보, 날짜, URL) |
| `project` | 프로젝트 상태, 마일스톤, 아키텍처 |
| `skill` | 사용자가 잘하는 것 |
| `mistake` | 과거 오류 — 반복 방지 |
| `context` | 세션 관련 컨텍스트 |
| `note` | 기타 노트 |

## 우선순위

- `low` — 알면 좋음
- `normal` — 기본값
- `high` — 중요
- `critical` — 절대 잊으면 안 됨 (사용자 정체성, 법적 정보)

## 핵심 엔드포인트

### GET /memory/recall

모든 메모리를 LLM에 최적화된 일반 텍스트로 반환합니다. 모든 세션 시작 시
호출하십시오.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/recall
```

응답 (text/plain):

```
Mind: Michael's Mind
Memories: 12 total (10 verified)

[001] identity (CRITICAL)
  user_name
  Michael Schäfer
  Tags: person, identity

...
```

### POST /memory

새 메모리를 저장하거나 기존 메모리를 업데이트합니다 (동일한 카테고리 + 키 = 업데이트).

```bash
curl -X POST https://synapse.schaefer.zone/memory \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "fact",
    "key": "user_name",
    "content": "The user's name is Michael Schäfer",
    "tags": ["person", "identity"],
    "priority": "critical"
  }'
```

응답: `{ "id": "mem_001", "status": "stored" }`

### GET /memory

선택적 필터로 메모리를 나열합니다.

```bash
# All memories (JSON)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# Filter by category
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

# Filter by tag
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?tag=docker"
```

### PUT /memory/:id

ID로 특정 메모리를 업데이트합니다.

```bash
curl -X PUT https://synapse.schaefer.zone/memory/mem_001 \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated content", "priority": "high"}'
```

### DELETE /memory/:id

단일 메모리를 삭제합니다.

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mem_001
```

## 검색 엔드포인트

### GET /memory/search

FTS5를 사용한 전문 검색입니다.

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

FTS5 구문:

- 여러 단어 = AND: `docker swarm`
- 구문: `"docker swarm"`
- 접두사: `docker*`
- 불린: `docker OR kubernetes`
- 제외: `docker -swarm`

### GET /memory/semantic-search

임베딩을 사용한 개념 검색입니다 (FTS5보다 느리지만 의미를 이해함).

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

키워드가 일치하지 않더라도 쿼리와 의미론적으로 유사한 메모리를
반환합니다. X가 다르게 설명된 "X에 대한 메모리 찾기"에 유용합니다.

### GET /memory/by-tag

태그로 메모리를 나열합니다.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/by-tag?tag=docker"
```

### GET /memory/related/:id

특정 메모리와 관련된 메모리를 찾습니다 (공유 태그 기준).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/related/mem_001
```

## 동기화 및 Diff

### GET /memory/diff

증분 동기화 — 타임스탬프 이후 변경된 메모리를 반환합니다.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/diff?since=1700000000"
```

응답: `{ "added": [...], "updated": [...], "deleted": [...] }`

### POST /memory/sync

다른 인스턴스에서 diff를 적용합니다 (자체 호스팅 동기화용).

```bash
curl -X POST https://synapse.schaefer.zone/memory/sync \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"added": [...], "updated": [...], "deleted": [...]}'
```

## 대량 작업

### POST /memory/bulk-delete

ID로 여러 메모리를 삭제합니다.

```bash
curl -X POST https://synapse.schaefer.zone/memory/bulk-delete \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'
```

### POST /memory/embed-batch

아직 임베딩이 없는 메모리의 임베딩을 생성합니다 (의미론적 검색용).

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

### GET /memory/embed-batch-status

임베딩 생성 진행 상황을 확인합니다.

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

## 검증

메모리에는 `verified` 플래그가 있습니다. 에이전트가 저장한 메모리는
기본적으로 미검증(`source=agent`)이며, 사람이 저장한 메모리는
검증됨(`source=user`)입니다.

### POST /memory/verify

메모리를 검증됨으로 표시합니다 (Mind Key가 아닌 JWT 필요).

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \
  -H "Authorization: Bearer YOUR_JWT"
```

### POST /memory/unverify

메모리를 미검증으로 표시합니다 (JWT 필요).

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \
  -H "Authorization: Bearer YOUR_JWT"
```

### GET /memory/unverified

사용자 검증 대기 중인 메모리를 나열합니다.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/unverified?limit=100"
```

## 통계 및 감사

### GET /memory/stats

현재 마인드에 대한 집계 통계입니다.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/stats
```

반환: `{ "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }`

### GET /memory/audit

상태를 변경하는 모든 작업의 감사 로그입니다.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/audit?limit=100&action=store"
```

### GET /memory/contradictions

저장된 메모리의 잠재적 모순을 감지합니다.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/contradictions
```

### GET /memory/expiring

만료일이 다가오는 메모리를 나열합니다.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/expiring?within=7d"
```

## 상태 및 내보내기

### GET /memory/health

메모리 시스템의 빠른 상태 확인입니다.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/health
```

### GET /memory/mind-export

모든 메모리의 전체 JSON 내보내기입니다 (백업용).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mind-export > backup.json
```

### POST /memory/compact

유사한 메모리를 압축합니다 (자동 요약).

```bash
curl -X POST https://synapse.schaefer.zone/memory/compact \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'
```

## 다음 단계

- [LLM을 위한 빠른 시작](/docs/getting-started/quick-start-llm)
- [메모리 모범 사례](/docs/guides/memory-best-practices)
- [FTS5 검색](/docs/concepts/fts5-search)
- [의미론적 검색](/docs/concepts/semantic-search)