# Pencarian Semantik (Embeddings)

Synapse mendukung pencarian semantik menggunakan vektor embeddings. Berbeda
dengan FTS5 (pencocokan kata kunci), pencarian semantik menemukan memori
berdasarkan **makna** — bahkan jika tidak ada kata kunci yang cocok.

## Cara Kerja

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

### Apa itu embeddings?

Embeddings adalah representasi vektor numerik dari teks. Teks dengan makna
serupa memiliki vektor yang serupa. Synapse membuat vektor (mis. 1536 dimensi)
untuk konten setiap memori.

### Cosine similarity

Untuk menemukan memori yang mirip secara semantik, Synapse menghitung cosine
similarity antara vektor kueri dan setiap vektor memori. Kesamaan lebih tinggi
= lebih relevan.

## Kapan Menggunakan Pencarian Semantik

### Gunakan pencarian semantik ketika:

- Anda ingin "memori tentang X" di mana X dideskripsikan secara berbeda dari yang disimpan
- FTS5 tidak mengembalikan hasil (tidak ada cocok kata kunci)
- Anda ingin pengelompokan konseptual (mis. semua memori "deployment", bahkan jika beberapa menyebut "release")
- Kueri adalah pertanyaan: "bagaimana kita menangani autentikasi?"

### Gunakan FTS5 ketika:

- Anda tahu kata kunci persis
- Anda memerlukan logika boolean (AND, OR, NOT)
- Anda memerlukan respons sub-milidetik
- Anda ingin pencocokan frasa

## Endpoint

### GET /memory/semantic-search

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

Respons:

```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
    }
  ]
}
```

## Contoh

### Mencari memori deployment

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

Mengembalikan memori tentang "deployment", "release", "publishing", "rolling out",
dll.

### Mencari pola autentikasi

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

Mengembalikan memori tentang login, auth, JWT, manajemen sesi, OAuth, dll.

### Mencari memori serupa

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

Menggunakan kesamaan semantik (melalui tag bersama DAN vektor embeddings).

## Pembuatan Embedding

### Kapan embeddings dibuat?

- **Saat penyimpanan memori** — jika layanan embeddings dikonfigurasi, embedding dibuat secara sinkron
- **Pembuatan batch** — `POST /memory/embed-batch` membuat embeddings untuk memori yang belum memilikinya
- **Pembaruan asinkron** — saat konten diperbarui, embedding dibuat ulang

### Provider embedding

Synapse mendukung provider embedding yang dapat dikonfigurasi:

- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)
- **Model lokal** (melalui Ollama atau serupa)
- **Khusus** (implementasikan antarmuka embeddings)

Konfigurasi melalui variabel lingkungan:

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

### Pembuatan batch

Untuk mind dengan banyak memori yang belum memiliki embeddings:

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

## Performa

| Operasi | Latensi |
|-----------|---------|
| Membuat embedding (OpenAI) | 100-200ms |
| Pencarian semantik (1k memori) | 50-100ms |
| Pencarian semantik (10k memori) | 200-500ms |
| Pembuatan batch (100 memori) | 10-20s |

> [!NOTE]
> Pencarian semantik lebih lambat dari FTS5 karena komputasi vektor. Gunakan
> FTS5 untuk kata kunci yang diketahui, semantik untuk kueri konseptual.

## Batasan

### Biaya embeddings

Jika menggunakan OpenAI, membuat embeddings memerlukan biaya (~$0,02 per 1M
token untuk text-embedding-3-small). Untuk 10.000 memori rata-rata 100 token
masing-masing, itu ~$0,02 — dapat diabaikan.

### Cold start

Memori yang disimpan sebelum embeddings dikonfigurasi tidak akan memiliki
embeddings. Jalankan `POST /memory/embed-batch` untuk backfill.

### Ketergantungan provider

Jika provider embeddings tidak aktif, pencarian semantik gagal dengan baik
(mengembalikan hasil kosong atau error). FTS5 masih berfungsi.

## Saat Embeddings Tidak Tersedia

Jika layanan embeddings tidak dikonfigurasi:

- `GET /memory/semantic-search` mengembalikan 503 Service Unavailable
- `POST /memory` masih berfungsi (hanya tidak ada embedding yang dibuat)
- Pencarian FTS5 masih berfungsi

## Praktik Terbaik

> [!TIP]
> - **Gunakan semantik untuk kueri konseptual** — "bagaimana kita menangani X?"
> - **Gunakan FTS5 untuk istilah spesifik** — "docker swarm"
> - **Backfill embeddings secara teratur** — `POST /memory/embed-batch`
> - **Pantau kesehatan provider** — pencarian semantik bergantung padanya
> - **Kombinasikan dengan tag** — semantik + filter tag mempersempit hasil

## Langkah Berikutnya

- [Pencarian FTS5](/docs/concepts/fts5-search)
- [Memory API](/docs/api/memory)
- [Arsitektur](/docs/concepts/architecture)