# 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

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

Yanıt:

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

## Örnekler

### Dağıtım belleklerini bul

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

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

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

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

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

## Performans

| İşlem | Gecikme |
|-----------|---------|
| Gömme üretimi (OpenAI) | 100-200ms |
| Anlamsal arama (1k bellek) | 50-100ms |
| Anlamsal arama (10k bellek) | 200-500ms |
| Toplu üretim (100 bellek) | 10-20s |

> [!NOTE]
> Anlamsal arama, vektör hesaplaması nedeniyle FTS5'ten daha yavaştır. Bilinen anahtar kelimeler için FTS5, kavramsal sorgular için anlamsal arama kullanın.

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

> [!TIP]
> - **Kavramsal sorgular için anlamsal kullanın** — "X'i nasıl ele alıyoruz?"
> - **Belirli terimler için FTS5 kullanın** — "docker swarm"
> - **Gömmeleri düzenli olarak geri doldurun** — `POST /memory/embed-batch`
> - **Sağlayıcı sağlığını izleyin** — anlamsal arama buna bağlıdır
> - **Etiketlerle birleştirin** — anlamsal + etiket filtresi sonuçları daraltır

## Sonraki Adımlar

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