Claude Code hafıza: AI kod ajanlarına kalıcı proje hafızası

AI kod asistanları neden her oturumda bağlamı unutur?

Unuturlar çünkü model, oturumlar arasında hiçbir şey saklamaz. Bir dil modeli her istekte kendisine verilen metni okur, cevabı üretir ve durumu bırakır. Oturum boyunca konuşmanın devam ediyormuş gibi görünmesinin sebebi, önceki mesajların her istekte yeniden gönderilmesidir. Oturum kapandığında gönderilecek bir şey kalmaz.

İkinci sınır bağlam penceresidir. Pencere, modelin aynı anda görebildiği toplam metin miktarıdır ve sabittir. Uzun bir oturumda pencere dolduğunda araçlar en eski kısmı kırpar ya da özetler. Sabah verdiğin karar, öğleden sonra sessizce düşmüş olabilir.

Üçüncüsü, kodun kendisinin gerekçeyi taşımamasıdır. Ajan kod tabanını dakikalarca tarar, ne yapıldığını görür, neden yapıldığını göremez. Çünkü o bilgi hiçbir dosyada yazılı değildir.

Bağlam penceresini büyütmek neden hafıza değildir?

Daha büyük bir pencere daha uzun bir oturum verir, kalıcılık vermez. Bir milyon token'lık pencere de oturum kapandığında boşalır. Pencere kapasitedir; hafıza ise oturumdan sağ çıkan kayıttır. İkisi farklı problemleri çözer.

Pencereyi doldurmanın üç somut bedeli var. Maliyet: her istekte gönderilen her token ücretlendirilir, bütün proje geçmişini her mesajda göndermek pahalıdır. Gecikme: uzun istekler yavaş cevap verir. Doğruluk: çok uzun bağlamlarda modeller ortada kalan bilgiyi gözden kaçırma eğilimindedir, alakasız metin sinyali seyreltir.

Pratikte işe yarayan hamle tersidir. Pencereye her şeyi değil, o iş için gerekli olanı koyarsın: son kararlar, açık görevler, ilgili dosyalar. Bu seçmeyi yapan şey hafızadır, pencerenin boyutu değil.

Kalıcı hafıza için hangi yaklaşımlar var?

Pratikte üç yaklaşım var ve üçü de aynı soruya cevap veriyor: oturum bittiğinde ne kalacak?

Birincisi oturum-içi özet. Araç konuşmayı özetler, özeti bir sonraki isteğe taşır. Kurulum maliyeti sıfırdır, çoğu araçta hazır gelir.

İkincisi bulut vektör veritabanı. Konuşmalar ve dokümanlar parçalara bölünür, gömme vektörlerine çevrilir ve bir serviste saklanır; ajan soru sorduğunda anlamca yakın parçalar geri getirilir. Büyük hacimde güçlüdür.

Üçüncüsü yerel dosya tabanlı hafıza. Kararlar ve bağlam, projenin içinde düz markdown dosyalarına yazılır, git ile sürümlenir ve her oturum başında okunur.

Doğru cevap genelde tek bir yaklaşım değil, ikisinin birleşimidir. Hangisinin ağır basacağını hacim, gizlilik ve düzeltme ihtiyacı belirler.

Oturum-içi özet ne zaman yeter?

Tek bir uzun oturumu ayakta tutmak için yeter. Araç konuşmayı sıkıştırır; bağlam penceresi dolduğunda özeti tutar, ayrıntıyı atar. Bugün üzerinde çalıştığın tek bir işin akışını korumakta iyidir ve hiçbir kurulum gerektirmez.

Sınırı iki yerde çıkar. Birincisi, özet kayıplıdır ve neyin atıldığını sen seçmezsin. Bir kararın gerekçesi ayrıntı sayılıp düşebilir; sen de düştüğünü ancak ajan yanlış cevap verdiğinde fark edersin. İkincisi, özet araca bağlıdır. Bir araçtaki oturum özeti diğerine geçmez; araç değiştirdiğinde sıfırdan başlarsın.

Bir de görünmezlik problemi var. Özetin içinde ne yazdığını genelde okuyamazsın. Yanlış bir çıkarım özete girdiyse sonraki her oturuma o yanlışla başlarsın ve düzeltecek bir dosyan yoktur.

Bulut vektör veritabanı ne zaman gerekir?

Aranacak malzeme okunamayacak kadar büyüdüğünde gerekir. Binlerce doküman, yılların destek kayıtları, uzun konuşma arşivleri: bu hacimde dosya açıp okumak çalışmaz, anlam bazlı arama çalışır. Vektör araması kelimeler birebir tutmasa da ilgili parçayı bulur; bu gerçek ve önemli bir avantajdır.

Bedeli üç kalemde toplanır. Altyapı: bir servis, bir şema ve bir gömme boru hattı bakarsın. Gizlilik: parçalar gömülmek üzere dışarı çıkar, çoğu kurulumda proje içeriği sağlayıcının sunucusuna gider. Doğrulanabilirlik: geri gelen parçanın neden geldiğini gözle kontrol edemezsin, vektörler okunmaz.

Tek bir projenin karar geçmişi için ise genelde fazla gelir. On beş markdown dosyasını aramak üzere vektör veritabanı kurmak, çözdüğünden fazla bakım yükü getirir.

Yerel dosya tabanlı hafıza ne kazandırır?

Kayıt üzerinde tam kontrol kazandırır. Hafıza projenin içinde bir klasörde durur; dosyaları sen açarsın, sen düzeltirsin, git ile sürümlenir. Ajanın ne bildiğini tahmin etmezsin, bakarsın. Yanlışsa satırı değiştirirsin ve düzeltme anında geçerli olur.

İkinci kazanç taşınabilirliktir. Dosya biçimi araca bağlı değildir; aynı klasörü Claude Code da okur, Codex de, Copilot da. Araç değiştirmek hafıza kaybı olmaktan çıkar.

Sınırları da var. Kayıtları biri yazmalı, bu disiplin ister. Dosya sayısı arttıkça düzen bozulur, bayat kayıtlar birikir ve temizlik iş haline gelir. Çok büyük arşivlerde düz metin araması yetmez, yerel gömme gibi bir katman gerekir. Bu yaklaşım çok veri üzerine değil, doğru veri üzerine kuruludur.

Markdown neden taşınabilir bir hafıza biçimi?

Çünkü markdown, insanın ve makinenin aynı anda okuyabildiği en az ortak paydadır. Düz metindir: herhangi bir editörle açılır, grep ile aranır, kopyalanır, e-postayla gönderilir. Onu okumak için bir ürünün ayakta olmasına gerek yoktur.

Git ile birleştiğinde hafıza sürümlenir. Bir kaydın ne zaman, kim tarafından ve hangi commit ile değiştiği görünür. Tek satırlık bir düzeltme diff'te tek satır olarak okunur. İnceleme, geri alma ve dallanma bedava gelir; bunlar zaten git'in işidir.

Son olarak kilitlenme riski düşer. Kullandığın araç değişse, bir servis kapansa, ekip başka bir yığına geçse de dosyalar aynı yerde durur ve aynı biçimde okunur. Hafızanın değeri yıllar içinde biriktiği için, taşıyıcının uzun vadede erişilebilir olması biçimin zarafetinden daha önemlidir.

Hafıza çürüdüğünde ne olur?

Bayat bir kayıt, boş bir kayıttan daha tehlikelidir. Hafıza boşsa ajan bilmediğini söyler ve sana sorar. Hafızada dört ay önce doğru olan bir cümle varsa, ajan onu bugünkü gerçek sanıp üzerine iş kurar. Yanlış cevap, tam da kaynağı güvenilir göründüğü için fark edilmez.

Çürümenin iki tipik yolu var. Birincisi tarihsizliktir: mimarinin şu an nasıl olduğunu anlatan bir satır, ne zaman yazıldığı belli değilse sonsuza kadar bugünmüş gibi okunur. İkincisi sessiz güncellemedir: yeni karar eskisini geçersiz kılar ama eski kayıt yerinde durur ve arama ikisini birden getirir.

Çözüm iki alışkanlıkta. Güncel gerçeği iddia eden her başlığı tarihle. Bir kayıt geçersiz kaldığında onu silmek yerine geçersiz olarak işaretle ve yeni kayda yönlendir.

Proje bağlamını buluta göndermek ne demek?

Hafıza için buluta gönderilen şey kod parçalarından ibaret değildir. Kararlar, mimari notlar, iç servis isimleri, müşteri adları, çözülmemiş güvenlik açıkları ve neyin neden yapılmadığı da gider. Bir projenin en hassas kısmı çoğu zaman kodun kendisi değil, kodun etrafındaki bilgidir.

Bu bazı ekipler için sorun değildir, bazıları için sözleşme ihlalidir. Sorulacak sorular somut: veri hangi ülkede tutuluyor, ne kadar saklanıyor, model eğitiminde kullanılıyor mu, silme talebi gerçekten siliyor mu, alt işleyiciler kimler.

Yerel işleme bu soruların bir kısmını baştan kaldırır. İndeksleme ve gömme cihazda çalışıyorsa proje içeriği ağa çıkmaz. Borje bu tarafta durur: indeksleme döngüsünde LLM çağrısı yoktur, hafıza kullanıcının diskinde kalır ve sunucuya yalnızca hesap doğrulaması gider.

Kendi hafıza kurulumunu nasıl yaparsın?

Araçtan bağımsız bir düzenle başlayabilirsin. Projenin köküne bir klasör aç, içine üç dosya koy: şu an ne üzerinde çalışıldığını yazan kısa bir durum dosyası, alınan kararları ve gerekçelerini biriktiren bir karar dosyası, açık işleri tutan bir görev dosyası. Ajanına her oturum başında bu üç dosyayı okumasını söyle.

Neyi kaydedeceğin, neyi kaydetmeyeceğinden daha kolaydır. Kaydet: karar ve gerekçesi, denenip vazgeçilen yol ve sebebi, sistemin dışarıdan görünmeyen kısıtları. Kaydetme: kodun kendisinin zaten anlattığı şeyler, geçici hata çıktıları, oturum sohbetinin tamamı.

Durum dosyasını kısa tut; bir ekran boyu iyi bir sınırdır. Uzayan her şey konu dosyalarına iner. Her başlığa tarih yaz. Bir kayıt geçersiz kaldığında düzelt, biriktirme. Hafızanın bakımı, hafızanın kendisi kadar iştir.