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

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

Respons:

{
  "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

# 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

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

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

Mencari memori serupa

# 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:

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

Pembuatan batch

Untuk mind dengan banyak memori yang belum memiliki embeddings:

# 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

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

Langkah Berikutnya

• Pencarian FTS5
• Memory API
• Arsitektur