# Bellek En İyi Uygulamaları

Bellekleri nasıl yapılandırdığınız ne kadar yararlı olduklarını belirler. Bu rehber, LLM'in doğru zamanda doğru bilgiyi geri çağırabilmesi için kategorize etme, etiketleme ve önceliklendirme desenlerini kapsar.

## Kategoriler: En Spesifiği Seçin

| Kategori | Kullanım | Örnek |
|----------|---------|---------|
| `identity` | Kullanıcı adı, rol, iletişim bilgisi | `"user_name": "Michael Schäfer"` |
| `preference` | Beğeniler, beğenmemeler, çalışma tarzı | `"communication": "Prefers concise responses"` |
| `fact` | Doğrulanabilir bilgiler | `"office_location": "Berlin, Germany"` |
| `project` | Proje durumu, kararlar | `"project_synapse": "v1.5.0 deployed"` |
| `skill` | Kullanıcının becerileri | `"skill_python": "Advanced, 10+ years"` |
| `mistake` | Kaçınılacak geçmiş hatalar | `"mistake_npm_version": "Always bump version"` |
| `context` | Oturumla ilgili bağlam | `"current_focus": "Working on docs system"` |
| `note` | Çeşitli notlar | `"note_idea": "Try Redis for caching"` |

> [!TIP]
> Şüphede kaldığınızda, doğrulanabilir bilgiler için `fact`, diğer her şey için `note` kullanın. Aşırı kategorize etmeyin — kafa karıştırıcı bir `context`'ten daha iyi net bir `fact`.

## Anahtarlar: Anlamlı Tanımlayıcılar

`key` alanı belleğin tanımlayıcısıdır. Anlamlı, kararlı anahtarlar kullanın:

**İyi anahtarlar:**
- `user_name`
- `project_synapse_status`
- `preference_communication_style`
- `mistake_npm_version_bump`

**Kötü anahtarlar:**
- `mem_001` (anlamlı değil)
- `temp` (tanımlayıcı değil)
- `2026-06-27-note` (tarih geri çağırmaya yardımcı olmaz)

### Anahtar adlandırma kuralları

- `snake_case` (alt çizgili küçük harf)
- Kategori ile önekleyin: `preference_*`, `project_*`, `mistake_*`
- Fiil değil, tanımlayıcı isim kullanın
- 50 karakterin altında tutun

## Etiketler: Arama ve Filtreleme İçin

Etiketler hızlı filtreleme ve arama sağlar. Bellek başına 2-5 etiket ekleyin:

```json
{
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed. Next: v1.6.0 with docs system.",
  "tags": ["synapse", "deployment", "status", "v1.5.0"]
}
```

### Etiket desenleri

- **Proje adları**: `synapse`, `synapse-mcp`, `synapse-chat`
- **Konular**: `deployment`, `ci`, `database`, `auth`
- **Durum**: `active`, `completed`, `blocked`
- **Öncelik göstergeleri**: `urgent`, `long-term`

> [!NOTE]
> Etiketler büyük/küçük harf duyarsızdır. Tutarlılık için küçük harf kullanın.

## Öncelikler: Gerçekçi Olun

| Öncelik | Kullanım | Belleklerin %'si |
|----------|---------|---------------|
| `critical` | Kullanıcı kimliği, yasal bilgiler, geri alınamaz kararlar | ~5% |
| `high` | Aktif projeler, önemli tercihler | ~20% |
| `normal` | Çoğu bilgi, not, bağlam | ~65% |
| `low` | Geçici, bilmek güzel | ~10% |

> [!WARNING]
> Her şeyi `critical` olarak işaretlemeyin. Her şey kritikse, hiçbir şey kritik değildir. `critical`'ı unutulursa gerçek zarara yol açacak şeyler için ayırın.

## Ne Zaman Saklama, Ne Zaman Saklamama

### Her zaman sakla

- Kullanıcı kimliği (ad, e-posta, rol)
- Uzun vadeli tercihler
- Proje kararları ve gerekçeler
- Geçmiş hatalar ve alınan dersler
- Kullanıcıya verilen taahütler

### Saklama

- Geçici durum (bunun yerine değişkenler kullanın)
- Birebir sohbet geçmişi (sohbet sistemi bunu ele alır)
- Hassas veriler (parolalar, API anahtarları)
- Kolayca türetilebilir bilgiler (mevcut tarih, dosya içerikleri)
- Geçici bağlam (düşük öncelikli `context` kategorisini kullanın)

## Bellekleri Güncelleme

Aynı `category` + `key` ile `POST /memory` mevcut belleği günceller:

```python
# Initial store
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# Later: update with same key
store("project", "project_synapse_status", "v1.5.0 deployed. CI green.", priority="high")
```

> [!TIP]
> Yinelenen oluşturmadan güncelleyebilmeniz için kararlı anahtarlar kullanın. LLM, bilgiler değiştikçe yeni bellekler oluşturmak yerine aynı anahtarı yeniden POST yapmalıdır.

## Bellek Yaşam Döngüsü

```
Create → Active → Stale → Archive → Delete
```

- **Create**: Tam bağlamla POST /memory
- **Active**: Sık geri çağır, gerektiğinde güncelle
- **Stale**: Hala ilgili ama aktif kullanılmıyor (düşük öncelik?)
- **Archive**: Önceliği `low` yap, tarihsel referans için tut
- **Delete**: Artık ilgili değilse DELETE /memory/:id

### Periyodik temizlik

```python
# Find memories not updated in 90 days
old_memories = requests.get(
    f"{URL}/memory/search?q=*",
    headers={"Authorization": f"Bearer {KEY}"}
)

for mem in old_memories["results"]:
    if is_stale(mem, days=90):
        # Either delete or lower priority
        if is_obsolete(mem):
            delete_memory(mem["id"])
        else:
            update_memory(mem["id"], priority="low")
```

## Desen: Bellek Kalıtımı

Hiyerarşik bağlam için (proje → alt proje → görev):

```python
# Parent project
store("project", "project_synapse", "Main Synapse project", 
      tags=["synapse", "parent"], priority="high")

# Sub-project (tags link to parent)
store("project", "project_synapse_docs", "Docs system for Synapse",
      tags=["synapse", "docs", "synapse-parent"], priority="high")

# Specific task (tags link to sub-project)
store("project", "task_docs_loader", "Implement docs-loader.ts",
      tags=["synapse", "docs", "task"], priority="normal")
```

LLM daha sonra `q=synapse+docs` arayarak tüm ilgili bellekleri bulabilir.

## Desen: Karar Günlüğü

Kararları gerekçeleriyle saklayın, böylece LLM onları yeniden tartışmaz:

```python
store("fact", "decision_postgres_over_sqlite",
      "Chose PostgreSQL over SQLite for production. Reason: concurrent writes, "
      "FTS5 native support, better backup story. Date: 2026-06-15. Decided by: Michael.",
      tags=["decision", "database", "postgres", "sqlite"],
      priority="high")
```

## Desen: Hata Önleme

Hataları özel önleme talimatlarıyla saklayın:

```python
store("mistake", "mistake_forget_version_bump",
      "Forgot to bump package.json version after changes. npm publish failed. "
      "FIX: Always run `npm version patch` before pushing. "
      "CI fails with 'version already exists' if you forget.",
      tags=["npm", "ci", "publish", "version"],
      priority="high")
```

## Kaçınılacak Anti-Desenler

> [!WARNING]
> - **Sohbet günlüklerini saklama** — sohbet sistemi bunu ele alır
> - **Tam dosyaları saklama** — betik deposu veya harici depolama kullanın
> - **Geçici durumu saklama** — değişkenler kullanın
> - **Gizli bilgileri saklama** — ortam değişkenleri kullanın
> - **Bellekleri çoğaltma** — kararlı anahtarlar kullanın
> - **Aşırı etiketleme** — bellek başına 2-5 etiket idealdir
> - **Her şey kritik** — önceliklerde gerçekçi olun

## Sonraki Adımlar

- [Memory API](/docs/api/memory)
- [Kalıcı LLM Ajanı](/docs/guides/persistent-llm-agent)
- [Bellek Etiketleme Stratejisi](/docs/llm-cookbook/memory-tagging-strategy)