Yapay zeka kodlama ajanları için ortak hafıza, her ajanın başlarken okuduğu ve çalışırken eklediği proje düzeyinde bir karar, düzeltme ve devir notu deposudur; böylece yeni bir oturum sıfırdan başlamaz. Ortak hafıza yoksa her Claude Code ya da Codex oturumu yalnızca depoda ve talimat dosyalarında yazanı bilir. Varsa sonraki ajan neden JWT seçtiğini, kullanıcının zaten “yeni bağımlılık ekleme” dediğini ve önceki ajanın iade akışını yarım bıraktığını bilir.
Bu yazıda ajanların neden unuttuğunu, ortak hafızada ne olması gerektiğini ve AgentVera’nın Brain özelliğinin bunu proje geçmişinden nasıl kurup ajanlara MCP üzerinden okutup yazdırdığını anlatıyorum.
Kodlama ajanları neden unutur?
Bir kodlama ajanının hafızası bağlam penceresidir. Oturum bittiğinde ya da konuşma sıkıştırıldığında olanların çoğu gider. Sonraki oturum şunları alır:
- Sistem talimatı ve araç tanımları
CLAUDE.mdya daAGENTS.mdgibi talimat dosyaların- Görev sırasında depodan okudukları
Bu kod için yeter, çünkü kod depodadır. Gerekçeler için yetmez. Commit neyin değiştiğini söyler; nedeni çoğu zaman bir PR yorumunda, bir issue’da ya da artık var olmayan bir ajanla yapılan konuşmadadır. Sonuçta ajanlar aynı soruları sorar, geçen hafta reddettiğin yaklaşımı önerir, başka bir ajanın bitirdiği işi yeniden yapar. Birden fazla ajanı paralel çalıştırdığında durum kötüleşir: her biri diğerlerinin hiç görmediği bir şey öğrenir.
Ortak hafızada ne olmalı?
Talimat dosyası ve ortak hafıza farklı işler yapar.
| Talimat dosyası (CLAUDE.md, AGENTS.md) | Ortak hafıza | |
|---|---|---|
| Kim yazar | Sen, elle | Geçmişten kurulur, ajanlar çalışırken ekler |
| İçerik | Kurallar, komutlar, alışkanlıklar | Gerekçeli kararlar, düzeltmeler, devir notları |
| Değişme sıklığı | Nadiren | Her gün |
| Nasıl yüklenir | Dosyanın tamamı, her oturumda | Gerektiğinde aranır, başta kısa bir özet |
| Eskidiğini bilir mi | Hayır | Kararları eskimiş ya da yerine yenisi gelmiş diye işaretleyebilir |
Talimat dosyanı kısa ve sabit tut (nasıl yazılır). Değişen kısımları hafızaya koy. İşe yarayan bir ortak hafıza dört tür şey tutar:
- Kararlar. “Oturumlar mobil uygulamayı bozduğu için API’de JWT kullanıyoruz”, tarihi ve kaynağıyla.
- Düzeltmeler. Kullanıcının bir ajana yanlış yaptığını söylediği şeyler. Kaybedilmesi en pahalı olanlar bunlardır.
- Devir notları. Bir ajanın ne yaptığı ve neyi açık bıraktığı.
- Bilgiler. Koddan kolayca anlaşılmayan küçük proje gerçekleri.
AgentVera’nın Brain’i hafızayı nasıl kurar?
AgentVera’da her projenin Detaylar sayfasında bir Brain sekmesi var. Hafızayı oluştur’a (sonraki seferlerde Hafızayı yenile) tıkladığında projenin geçmişini okur:
- Git’te takip edilen dokümanlar ve karar kayıtları: README, ARCHITECTURE, CONTRIBUTING, CLAUDE, AGENTS, CHANGELOG,
docs/,adr/vedecisions/(en fazla 250 dosya) - Birleştirme olmayan en yeni 1.500 commit
- Proje GitHub’daysa ve giriş yaptıysan en fazla 200 pull request ve 200 issue
- En fazla 120 eski ajan konuşması
Kararları bu malzemeden Claude Haiku çıkarır. Her kararın bir başlığı, gerekçesi, tarihi, kaynakları ve ilgili olduğu kod terimleri olur. Tekrarlar birleştirilir.
Kararlar sonsuza kadar doğru kalmaz; bu yüzden her birinin bir durumu vardır: geçerli, eskimiş ya da yerine yenisi geldi. Kodla karşılaştır, bir kararın kod terimlerini git grep ile depoda arar. Claude ile doğrula daha yakından bakmak için salt okunur bir Sonnet kontrolü çalıştırır. Böylece hafıza ajana “bunu kararlaştırmıştık ama kod başka yöne gitti” diyebilir.
Brain sekmesinde dört görünüm var: Kararlar, Bilgi grafiği, Bağlam paketi ve Hafıza. Bir de Sor kutusu var. “Neden JWT kullanıyoruz?” diye sorarsan Sonnet hafızadan, salt okunur şekilde ve kaynak göstererek yanıtlar.
Ajanlar hafızayı nasıl okur ve yazar?
Hafızayı kurmak işin yarısı. Diğer yarısı ajanların onu kullanması. AgentVera, CLI’ı MCP sunucusu kabul eden her ajana agentvera-brain adlı bir MCP sunucusu ekler. MCP sana yeniyse önce MCP sunucusu nedir yazısına bak.
Sunucunun iki aracı var:
| Araç | Ne yapar |
|---|---|
brain_recall | Kararlarda (durumlarıyla), dokümanlarda, commit, PR ve issue’larda, eski konuşmalarda, devir notlarında ve saklanan bilgilerde arar. En fazla 8 sonuç döner, her biri gösterilebilecek bir [id] taşır. Sorgusuz çağrılırsa saklanan hafızaları ve açık işleri döner. |
brain_remember | Kendi başına anlaşılır tek bir cümleyi fact (bilgi), correction (düzeltme) ya da decision (karar) olarak saklar. İlerleme güncellemesi için değildir. Aynı metin iki kez saklanmaz. |
Sunucu ajana bunları ne zaman kullanacağını da söyler: önceki işe dokunan bir görevden önce brain_recall çağır; kullanıcı seni düzelttiğinde, bir kural ya da tercih söylediğinde veya bir karar alındığında brain_remember çağır; dayandığın öğeleri [id] ile göster.
Bir Claude Code oturumunda tipik bir akış şöyle görünür:
Sen: API'ye refresh token ekle.
Ajan: (brain_recall "auth tokens JWT" çağırır)
[d12] "API'de JWT kullan, oturumlar mobil uygulamayı bozdu" (geçerli)
ve [m4] düzeltmesi "Token'ları asla localStorage'da tutma" bulundu.
JWT'yi koruyacağım ve refresh token'ı httpOnly cookie'ye koyacağım.
Sen: Güzel. Refresh token'lar da 30 günde dolsun.
Ajan: (brain_remember çağırır, kind: decision)Auth’a dokunan sonraki ajan ikisini de bulur; sen kendini tekrarlamazsın.
Devir notları: oturumlar arası hafıza
Brain sekmesindeki Ajanlar hafızayı yazsın anahtarı sen kapatmadıkça açıktır. Açıkken:
- Turlardan sonra (ajan başına en fazla 15 dakikada bir) ve bir ajan konuşmasını sıkıştırdığında her zaman, ajan kısa bir devir notu bırakır. Notu Haiku yazar: bir ile dört cümlelik bir özet ve Açık kalanlar olarak gösterilen en fazla altı açık iş.
- Ajanın
brain_rememberile sakladığı düzeltme ve kararlar aynı hafızaya girer. - Projenin yeni ajanları en yenilerini alır.
- 03:00 ile 06:00 arasında brain yeniden derlenir; ama yalnızca daha önce kurulduysa, o zamandan beri yeni not varsa ve 12 saatte en fazla bir kez.
Notlar ve hafızalar Hafıza görünümünde Bilgi, Düzeltme, Karar ya da Oturum notu etiketiyle listelenir. Unut birini kaldırır.
Yeni bir ajan başladığında talimatlarına en fazla 2.500 karakterlik kısa bir giriş eklenir: saklanan hafızalar (önce düzeltmeler, en fazla 15) ve son yedi günde açık işi kalan en fazla altı başka ajanın en yeni notu. Sıkıştırmayı daha az acı verici yapan budur: Claude Code’un yazdığı özet oturumla gider, devir notu kalır. Sıkıştırmanın neyi tutup neyi attığı için Claude Code bağlam yönetimi yazısına bak.
Bağlam paketi
Ayrıca Bağlam paketi görünümü, projenin en fazla 2.500 karakterlik bir özetini tutar. Yeni ajanlara bağlam paketi ver’i açarsan yeni ajanlar talimatlarında bu paketi ve eskimiş kararların listesini alır. Her yeni ajanın başlangıç bağlamına eklendiği için varsayılan olarak kapalıdır. Ajanların hep aynı arka planı kaçırıyorsa aç.
Beş adımda kurulum
- Projeyi AgentVera’da aç ve Detaylar → Brain’e git.
- Hafızayı oluştur’a tıkla. PR ve issue’ların da girmesini istiyorsan önce GitHub’a giriş yap.
- Kararlar’a göz at. Şüphelendiklerinde Kodla karşılaştır’ı çalıştır.
- Ajanlar hafızayı yazsın açık kalsın; bağlam paketini isteyip istemediğine karar ver.
- Yeni bir Claude Code ya da Codex ajanı başlat ve ona önceki işe dokunan bir görev ver.
brain_recallçağırdığını izle.
Ortak hafıza ve koordinasyon
Hafıza “ne biliyoruz?” sorusunu yanıtlar. Koordinasyon “şu anda kim ne yapıyor?” sorusunu. Canlı iş için AgentVera ajanlara MCP üzerinden bir pano da verir (agentvera-board); ajanlar oraya not, karar, yapılacak iş ve bulgu yazar. İki ajan aynı dosyayı düzenlediğinde de uyarır. İkisi birbirini tamamlar: pano bugün için, Brain gelecek ay için.
Hafıza proje haritası ile de iyi çalışır. Harita ajana kodun nerede olduğunu, Brain ise neden öyle olduğunu söyler.
Bilmen gereken sınırlar
- Brain, MCP sunucusu kabul eden ajanlara eklenir. Düz terminaller ve uzak SSH sunucusundaki ajanlar almaz.
- Oturum notları ve hafızalar ayrı ayrı en fazla 200 kayıt tutar.
- Her şey yerelde, uygulamanın veri klasöründe proje başına bir dosyada saklanır. Karar çıkarma, devir notları ve yanıtlar Claude Code girişin üzerinden Claude kullanır; bu istekler Anthropic’e gider.
- Hafıza sakladığı kadar iyidir. Ara sıra Hafıza görünümüne göz at ve yanlış notları unuttur.
Özet
Yapay zeka kodlama ajanları için ortak hafıza, sabit talimat dosyalarıyla sıfırlanan bağlam penceresi arasındaki boşluğu doldurur. AgentVera’nın Brain’i hafızayı dokümanlarından, commit’lerinden, PR ve issue’larından ve konuşmalarından kurar, hangi kararların hâlâ geçerli olduğunu izler ve MCP kullanabilen her ajanın agentvera-brain ile hatırlamasını ve saklamasını sağlar; turlardan sonra ve sıkıştırmada devir notları bırakılır. Brain ücretsiz plana dahil. Brain özellik sayfasına bak ya da ücretsiz planla başla ve ilk proje hafızanı kur.