# Pencarian Semantik (Embeddings)
SUMMARY: Pencarian memori konseptual menggunakan vektor embeddings — temukan berdasarkan makna, bukan hanya kata kunci.

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
[CODE BLOCK]
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
[CODE BLOCK]
Respons:
[CODE BLOCK]
Contoh
Mencari memori deployment
[CODE BLOCK]
Mengembalikan memori tentang "deployment", "release", "publishing", "rolling out",
dll.
Mencari pola autentikasi
[CODE BLOCK]
Mengembalikan memori tentang login, auth, JWT, manajemen sesi, OAuth, dll.
Mencari memori serupa
[CODE BLOCK]
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 —  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 (, )
- Model lokal (melalui Ollama atau serupa)
- Khusus (implementasikan antarmuka embeddings)
Konfigurasi melalui variabel lingkungan:
[CODE BLOCK]
Pembuatan batch
Untuk mind dengan banyak memori yang belum memiliki embeddings:
[CODE BLOCK]
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  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:
-  mengembalikan 503 Service Unavailable
-  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 — 
> - Pantau kesehatan provider — pencarian semantik bergantung padanya
> - Kombinasikan dengan tag — semantik + filter tag mempersempit hasil
Langkah Berikutnya
- Pencarian FTS5
- Memory API
- Arsitektur