Orta · ~2 dk okuma #memory #claude.md #agents.md

Agent Memory

Ajan hafızası — kısa ve uzun vadeli

Bir ajanın tek bir konuşmanın ötesinde bilgi taşıma yöntemleri: bağlam penceresindeki kısa süreli hafıza ile dosyalarda, hafıza araçlarında ya da vektör veritabanlarında saklanan uzun süreli hafıza.

Tanım

Bir LLM'in kendi başına hafızası yoktur; her istek sıfırdan başlar. "Hatırlıyor" gibi görünmesinin tek sebebi, harness'ın ilgili bilgiyi her turda bağlam penceresine geri koymasıdır. Ajan hafızası, neyin oraya hangi yoldan geri konacağına dair tasarımdır.

Kısa süreli hafıza = mevcut bağlam: konuşma geçmişi, araç çıktıları, okunan dosyalar. Hızlıdır ama sınırlıdır; pencere dolunca sıkıştırılır (compaction) ya da kesilir ve oturum kapanınca kaybolur.

Uzun süreli hafıza oturumlar arasında yaşar. Üç yaygın biçimi var: - Talimat dosyaları: CLAUDE.md, AGENTS.md gibi, her oturum başında otomatik okunan düz Markdown dosyalar. İnsan yazar, git'te yaşar, ekip paylaşır. - Hafıza araçları: Ajanın kendisinin okuyup yazdığı dosyalar. Claude API'deki memory tool, modelin /memories dizininde dosya oluşturup düzenlemesine izin verir; Claude Code'un auto memory özelliği de proje başına bir MEMORY.md dizini tutar. - Vektör veritabanı: Çok sayıda geçmiş not ya da konuşma için; anlamsal arama ile sadece ilgili parçalar bağlama çekilir (RAG ile aynı mekanik).

Asıl zor soru "nasıl saklanır" değil, "ne saklanır"dır. İyi aday: kodda ya da git geçmişinde zaten bulunmayan, tekrar tekrar açıklamak zorunda kaldığın şeyler — derleme komutları, ekip kuralları, alınmış kararlar ve gerekçeleri. Kötü aday: koddan okunabilecek her şey, geçici durum ve doğrulanmamış tahminler.

Benzetme

Bir hastanedeki nöbet devri gibi. Doktorun aklındakiler (kısa süreli hafıza) vardiyası bitince gider. Hastanın dosyası (uzun süreli hafıza) kalır ve yeni nöbetçi ilk iş onu okur. Ama dosyaya "ateşi düştü" yazıp güncellemeyi unutursan, sonraki doktor bayat bilgiyle yanlış karar verir. Hafıza kadar, hafızanın bakımı da önemlidir.

Gerçek dünyadan örnek

Bir ekip Laravel projesinde ajanla çalışıyor. Her yeni oturumda ajana aynı şeyleri anlatmaktan yoruldular: testler php artisan test ile koşar, veritabanı yok, içerik content/ klasöründe YAML dosyaları.

Bunları projenin köküne bir CLAUDE.md (ya da birden fazla ajan kullanılıyorsa AGENTS.md) olarak yazıyorlar. Artık her oturum bu bilgiyle başlıyor. Ayrıca bir geliştirici ajanı bir konuda düzelttiğinde ("hayır, burada Alpine kullanıyoruz"), auto memory bu düzeltmeyi kendi notlarına ekliyor ve bir sonraki oturumda aynı hata tekrarlanmıyor.

Üç ay sonra bir sorun çıkıyor: dosyada hâlâ eski deploy betiği yazıyor ve ajan onu güvenle çalıştırmaya çalışıyor. Ders: hafıza dosyaları da kod gibi gözden geçirilmeli.

Kod örnekleri

                                            CLAUDE.md · proje talimatları
                                            markdown
                                        
# Proje notları

Genel bakış için @README.md dosyasına bak.

## Komutlar
- Testler: `php artisan test`
- Ön yüz derlemesi: `npm run build`

## Kurallar
- Veritabanı yok; içerik `content/` altındaki YAML dosyalarında.
- Etkileşim için Alpine.js kullan, yeni JS framework'ü ekleme.
- Commit mesajları İngilizce yazılır.

                                            Claude API · memory tool
                                            python
                                        
import anthropic

client = anthropic.Anthropic()

# Model /memories altında dosya görüntüleme, oluşturma, düzenleme
# isteklerinde bulunur; bu istekleri senin uygulaman yürütür.
message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=2048,
    tools=[{"type": "memory_20250818", "name": "memory"}],
    messages=[
        {"role": "user", "content": "Dünkü müşteri talebine devam edelim."}
    ],
)

Ne zaman kullan

Ajana her oturumda aynı proje bilgisini tekrar anlatıyorsan (talimat dosyası)
Uzun süren, birden fazla oturuma yayılan işlerde ilerlemeyi taşımak için
Kullanıcı tercihlerini ve geçmiş düzeltmeleri kalıcı hale getirmek için
Geçmiş not ve konuşma hacmi bağlama sığmayacak kadar büyükse (vektör arama)

Ne zaman kullanma

Koddan, testlerden ya da git geçmişinden zaten okunabilen bilgi için — iki doğruluk kaynağı yaratır
Gizli bilgiler (şifre, token) için — hafıza dosyaları bağlama ve çoğu zaman repoya girer
Tek seferlik görevlerde — kısa süreli bağlam yeterlidir

Sık yapılan hatalar

Bayat hafıza

Hafıza otomatik güncellenmez. Değişmiş bir komut ya da terk edilmiş bir karar dosyada kalırsa ajan onu güncel gerçek gibi uygular. Hafıza dosyalarını düzenli gözden geçir, eskiyenleri sil.

Hafızayı çöplüğe çevirmek

Her şeyi kaydetmek, her oturumun başında token harcamak ve önemli kuralı gürültüde boğmak demektir. Claude Code'un auto memory'si bile her oturumda MEMORY.md'nin yalnızca ilk 200 satırını ya da 25 KB'ını yükler. Kısa ve öz tut.

Hafızaya körü körüne güvenmek

Hafıza bir iddiadır, kanıt değil. 'X fonksiyonu Y dosyasında' notu, dosya taşındıysa yanlıştır. Ajan önemli bir eyleme geçmeden önce hafızadaki bilgiyi mevcut durumla doğrulamalı.