Anlamsal Arama (Gömmeler)

Synapse, vektör gömmeleri kullanarak anlamsal aramayı destekler. FTS5'ten (anahtar kelime eşleştirme) farklı olarak anlamsal arama bellekleri anlama göre bulur — hiçbir anahtar kelime eşleşmese bile.

Nasıl Çalışır

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

Gömmeler nedir?

Gömmeler, metnin sayısal vektör temsilleridir. Benzer anlama sahip metinlerin benzer vektörleri vardır. Synapse, her belleğin içeriği için bir vektör (örn. 1536 boyut) üretir.

Kosinüs benzerliği

Anlamsal olarak benzer bellekleri bulmak için Synapse, sorgu vektörü ile her bellek vektörü arasındaki kosinüs benzerliğini hesaplar. Daha yüksek benzerlik = daha alakalı.

Anlamsal Arama Ne Zaman Kullanılır

Anlamsal aramayı şu durumda kullanın:

• Saklandığından farklı şekilde tanımlanan "X hakkındaki bellekler" istediğinizde
• FTS5 sonuç döndürmediğinde (anahtar kelime eşleşmesi yok)
• Kavramsal gruplandırma istediğinizde (örn. tüm "dağıtım" bellekleri, bazıları "release" dese bile)
• Sorgu bir soru olduğunda: "kimlik doğrulamayı nasıl ele alıyoruz?"

FTS5'i şu durumda kullanın:

• Tam anahtar kelimeleri biliyorsanız
• Boolean mantığı (AND, OR, NOT) gerekiyorsa
• Milisaniyenin altında yanıt gerekiyorsa
• Deyim eşleştirme istiyorsanız

Uç Nokta

GET /memory/semantic-search

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

Yanıt:

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

Örnekler

Dağıtım belleklerini bul

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

"deployment", "release", "publishing", "rolling out" vb. hakkındaki bellekleri döndürür.

Kimlik doğrulama desenlerini bul

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

Login, auth, JWT, oturum yönetimi, OAuth vb. hakkındaki bellekleri döndürür.

Benzer bellekleri bul

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

Anlamsal benzerlik kullanır (paylaşılan etiketler VE gömme vektörleri aracılığıyla).

Gömme Üretimi

Gömmeler ne zaman üretilir?

• Bellek saklandığında — gömme hizmeti yapılandırılmışsa, gömme senkron olarak üretilir
• Toplu üretim — POST /memory/embed-batch, gömmesi eksik olan bellekler için gömme üretir
• Asenkron güncellemeler — içerik güncellendiğinde gömme yeniden üretilir

Gömme sağlayıcıları

Synapse, yapılandırılabilir gömme sağlayıcılarını destekler:

• OpenAI (text-embedding-3-small, text-embedding-3-large)
• Yerel modeller (Ollama veya benzeri ile)
• Özel (gömme arayüzünü uygulayın)

Ortam değişkenleriyle yapılandırın:

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

Toplu üretim

Gömmesi eksik birçok belleği olan mind'ler için:

# 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

Performans

Sınırlamalar

Gömme maliyeti

OpenAI kullanıyorsanız, gömme üretimi paraya mal olur (text-embedding-3-small için 1M token başına ~$0.02). Ortalama 100 token olan 10.000 bellek için ~$0.02 — ihmal edilebilir.

Soğuk başlangıç

Gömmeler yapılandırılmadan önce saklanan belleklerin gömmesi olmaz. Geri doldurmak için POST /memory/embed-batch çalıştırın.

Sağlayıcı bağımlılığı

Gömme sağlayıcısı çökerse, anlamsal arama zarif bir şekilde başarısız olur (boş sonuçlar veya hata döndürür). FTS5 hala çalışır.

Gömmeler Mevcut Değilse

Gömme hizmeti yapılandırılmamışsa:

• GET /memory/semantic-search 503 Service Unavailable döndürür
• POST /memory hala çalışır (sadece gömme üretilmez)
• FTS5 arama hala çalışır

En İyi Uygulamalar

Sonraki Adımlar

• FTS5 Arama
• Memory API
• Mimari