# Memory API

Memory API, Synapse'un kalbidir. Yapılandırılmış bellekleri saklamak, almak, aramak ve yönetmek için 22 uç nokta sağlar. Tüm uç noktalar kimlik doğrulama için bir Mind Key gerektirir.

> [!CRITICAL]
> **Her oturumun başında `GET /memory/recall` çağrısını daima yapın.** Bu, önceki oturumlardan bağlamı yeniden oluşturmanın tek yoludur.

## Kategoriler

Bellekler 8 kategoriye ayrılmıştır:

| Kategori | Kullanım Senaryosu |
|----------|----------|
| `identity` | Kullanıcı adı, rol, iletişim bilgisi, kendi hakkındaki tercihler |
| `preference` | Beğeniler, beğenmemeler, çalışma tarzı, iletişim tercihleri |
| `fact` | Doğrulanabilir bilgiler (proje detayları, tarihler, URL'ler) |
| `project` | Proje durumu, kilometre taşları, mimari |
| `skill` | Kullanıcının iyi olduğu şeyler |
| `mistake` | Geçmiş hatalar — tekrarlamaktan kaçının |
| `context` | Oturumla ilgili bağlam |
| `note` | Çeşitli notlar |

## Öncelikler

- `low` — bilmek güzel
- `normal` — varsayılan
- `high` — önemli
- `critical` — asla unutulmamalı (kullanıcı kimliği, yasal bilgiler)

## Çekirdek Uç Noktalar

### GET /memory/recall

Tüm bellekleri LLM için optimize edilmiş düz metin olarak döndürür. Her oturum başlangıcında çağırın.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/recall
```

Yanıt (text/plain):

```
Mind: Michael's Mind
Memories: 12 total (10 verified)

[001] identity (CRITICAL)
  user_name
  Michael Schäfer
  Tags: person, identity

...
```

### POST /memory

Yeni bir bellek sakla veya mevcut olanı güncelle (aynı kategori + anahtar = güncelleme).

```bash
curl -X POST https://synapse.schaefer.zone/memory \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "fact",
    "key": "user_name",
    "content": "The user's name is Michael Schäfer",
    "tags": ["person", "identity"],
    "priority": "critical"
  }'
```

Yanıt: `{ "id": "mem_001", "status": "stored" }`

### GET /memory

İsteğe bağlı filtrelerle bellekleri listele.

```bash
# All memories (JSON)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# Filter by category
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

# Filter by tag
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?tag=docker"
```

### PUT /memory/:id

ID'ye göre belirli bir belleği güncelle.

```bash
curl -X PUT https://synapse.schaefer.zone/memory/mem_001 \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated content", "priority": "high"}'
```

### DELETE /memory/:id

Tek bir belleği sil.

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mem_001
```

## Arama Uç Noktaları

### GET /memory/search

FTS5 kullanarak tam metin arama.

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

FTS5 sözdizimi:

- Birden çok kelime = AND: `docker swarm`
- Deyim: `"docker swarm"`
- Ön ek: `docker*`
- Boolean: `docker OR kubernetes`
- Hariç tutma: `docker -swarm`

### GET /memory/semantic-search

Gömme (embedding) kullanarak kavramsal arama (FTS5'ten daha yavaştır ama anlamı anlar).

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

Hiçbir anahtar kelime eşleşmese bile sorguya anlamsal olarak benzer bellekleri döndürür. X'in farklı şekilde tanımlandığı "X hakkındaki bellekleri bul" için yararlıdır.

### GET /memory/by-tag

Etikete göre bellek listele.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/by-tag?tag=docker"
```

### GET /memory/related/:id

Belirli bir bellekle ilgili bellekleri bul (paylaşılan etiketler aracılığıyla).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/related/mem_001
```

## Senkronizasyon & Diff

### GET /memory/diff

Artımlı senkronizasyon — bir zaman damgasından sonraki değişen bellekleri döndürür.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/diff?since=1700000000"
```

Yanıt: `{ "added": [...], "updated": [...], "deleted": [...] }`

### POST /memory/sync

Başka bir örnekten bir diff uygula (self-hosted senkronizasyon için).

```bash
curl -X POST https://synapse.schaefer.zone/memory/sync \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"added": [...], "updated": [...], "deleted": [...]}'
```

## Toplu İşlemler

### POST /memory/bulk-delete

ID'ye göre birden çok belleği sil.

```bash
curl -X POST https://synapse.schaefer.zone/memory/bulk-delete \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'
```

### POST /memory/embed-batch

Henüz gömmeye sahip olmayan bellekler için gömme oluştur (anlamsal arama için).

```bash
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'
```

### GET /memory/embed-batch-status

Gömme oluşturma ilerlemesini kontrol et.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status
```

## Doğrulama

Belleklerin bir `verified` bayrağı vardır. Ajan tarafından saklanan bellekler varsayılan olarak doğrulanmamıştır (`source=agent`); insan tarafından saklanan bellekler doğrulanmıştır (`source=user`).

### POST /memory/verify

Bir belleği doğrulanmış olarak işaretle (Mind Key değil, JWT gerektirir).

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \
  -H "Authorization: Bearer YOUR_JWT"
```

### POST /memory/unverify

Bir belleği doğrulanmamış olarak işaretle (JWT gerektirir).

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \
  -H "Authorization: Bearer YOUR_JWT"
```

### GET /memory/unverified

İnsan doğrulaması bekleyen bellekleri listele.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/unverified?limit=100"
```

## İstatistikler & Denetim

### GET /memory/stats

Mevcut mind için toplu istatistikler.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/stats
```

Döndürür: `{ "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }`

### GET /memory/audit

Tüm durum değiştiren işlemlerin denetim günlüğü.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/audit?limit=100&action=store"
```

### GET /memory/contradictions

Saklanan belleklerde olası çelişkileri tespit et.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/contradictions
```

### GET /memory/expiring

Son kullanma tarihi yaklaşan bellekleri listele.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/expiring?within=7d"
```

## Sağlık & Dışa Aktarma

### GET /memory/health

Bellek sistemi için hızlı sağlık kontrolü.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/health
```

### GET /memory/mind-export

Tüm belleklerin tam JSON dışa aktarımı (yedekleme için).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mind-export > backup.json
```

### POST /memory/compact

Benzer bellekleri sıkıştır (otomatik özetleme).

```bash
curl -X POST https://synapse.schaefer.zone/memory/compact \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'
```

## Sonraki Adımlar

- [LLM'ler için Hızlı Başlangıç](/docs/getting-started/quick-start-llm)
- [Bellek En İyi Uygulamaları](/docs/guides/memory-best-practices)
- [FTS5 Arama](/docs/concepts/fts5-search)
- [Anlamsal Arama](/docs/concepts/semantic-search)