OpenClaw Ajanımın Hafızasını Hata Ayıklamak İçin 5 Gün Harcadım. İşte Öğrendiğim Her Şey.

Ajanımın adı Chiti. Telegram üzerinde çalışıyor, iki SaaS ürünü için müşteri desteği sağlıyor, tweet taslakları hazırlıyor, faturaları yönetiyor ve ortağımla farklı zaman dilimlerinde koordinasyonu sağlıyor. Sahip olduğum en yakın kıdemsiz çalışan benzeri şey.

Ve haftalarca bir şeyleri unutmaya devam etti.

İnce bir şekilde değil. Saatlerimi alan bir günlük cron görevi yapılandırır, model değiştirirdim ve bir sonraki oturumda Chiti sanki hiç konuşmamışız gibi davranırdı. İki gün önceki bir karardan bahsederdim ve boş boş bakardı. Bir göreve devam etmesini isterdim ve sıfırdan başlardı.

Bu yüzden özellik geliştirmeyi bıraktım ve zaman buldukça 5 günümü sadece hafızayı düzeltmeye harcadım. Bulduğum, bozduğum ve gerçekten işe yarayan her şey burada.

1. Gün: Ajan Uzun Konuşmalardan Sonra Her Şeyi Unutuyor

İlk sorunu tanımlaması kolay, teşhis etmesi acı vericiydi.

Uzun konuşmalardan sonra Chiti önceki bağlamı kaybetmeye başlıyordu. Yavaş yavaş değil, aniden yok oluyordu. 20 mesaj önce söylediğim şeyler gitmişti. Oturumun başında verdiğimiz kararlar mı? Hiç olmamıştı.

Suçlu, sıkıştırmaydı (compaction). Konuşma bağlam penceresini doldurduğunda, OpenClaw yenilere yer açmak için eski mesajları bir özete sıkıştırır. Özet ana fikri yakalar ancak ayrıntıları atar. İsimler, sayılar, kesin kararlar - gider.

Bu tasarım gereği böyle. Bağlam penceresi sınırlıdır. Ancak varsayılan davranış her şeye eşit davranır, yani 3. mesajdaki özenle hazırlanmış talimatınız, 7. mesajdaki sıradan bir sohbetle aynı muameleyi görür.

Ne yaptım:

Sıkıştırmadan önce hafıza boşaltmayı (memory flush) etkinleştirdim. Bu, ajana sıkıştırıcı çalışmadan önce önemli bağlamı diske yazmasını söyler.

1{
2  "compaction": {
3    "memoryFlush": {
4      "enabled": true,
5      "softThresholdTokens": 4000
6    }
7  }
8}

Oturum bağlam sınırına yaklaştığında, OpenClaw sessiz bir tur tetikler ve ajana sıkıştırma bunları silmeden önce kalıcı gerçekleri memory/YYYY-MM-DD.md dosyasına kaydetmesini hatırlatır. Ajan önemli olanı yazar, sıkıştırma çalışır ve bağlam özeti kaybetse bile önemli şeyler diskte kalır.

Öğrendiklerim:

Sıkıştırma düşmanınız değil. Sıkıştırma sırasında bilgi kaybetmek düşmandır. Çözüm, hatırlamaya değer her şeyin sıkıştırıcı dokunmadan önce bir dosyaya yazıldığından emin olmaktır. Sadece bağlam penceresindeyse geçicidir. Disktekiler kalıcıdır.

2. Gün: Arama Sonuçları Berbat

Günlük kayıtlar birikip MEMORY.md büyüdükçe, ajanın gerçekten bir şeyler bulması gerekiyordu. Yerleşik hafıza araması ilgisiz sonuçlar döndürüyor veya bariz eşleşmeleri kaçırıyordu.

Sorun arama altyapısıydı. OpenClaw'un varsayılan SQLite tabanlı araması, ilgili parçaları bulmak için vektör yerleştirmeleri (anlamsal benzerlik) kullanır. Geniş sorgular için işe yarar ancak tam eşleşmelerde zorlanır. Belirli bir müşteri adını arar ve benzer dil kullanan tamamen farklı bir konu hakkında sonuçlar alırdım.

Ne yaptım:

Hafıza arama altyapısı olarak QMD'ye geçtim. QMD, BM25 (anahtar kelime eşleştirme) ile vektör yerleştirmelerini ve bir yeniden sıralayıcıyı birleştirir. Yani "Charles ödeme hatası"nı aradığımda, bu tam kelimeleri içeren sonuçları VE anlamsal olarak ilgili sonuçları bulur, ardından alaka düzeyine göre yeniden sıralar.

Ayrıca QMD yollarına öğrendiklerim klasörünü de ekledim:

1{
2  "memory": {
3    "qmd": {
4      "paths": [
5        {
6          "path": "/Users/ramya/clawd",
7          "name": "memory-root",
8          "pattern": "MEMORY.md"
9        },
10        {
11          "path": "/Users/ramya/clawd",
12          "name": "memory-alt",
13          "pattern": "memory_alt.md"
14        },
15        {
16          "path": "/Users/ramya/clawd/memory",
17          "name": "memory-dir",
18          "pattern": "**/*.md"
19        },
20        {
21          "path": "/Users/ramya/clawd/learnings",
22          "name": "learnings",
23          "pattern": "**/*.md"
24        }
25      ]
26    }
27  }
28}

Öğrendiklerim:

Saf anlamsal arama teoride kulağa hoş gelir ancak özel isimlerde, belirli sayılarda ve tam ifadelerde başarısız olur. Hibrit arama (anahtar kelimeler + vektörler + yeniden sıralama) gerçek dünya ajan hafızası için önemli ölçüde daha iyidir. Ajanınız dosyalarında olduğunu bildiğiniz bir şeyi bulamıyorsa, darboğaz muhtemelen arama altyapısıdır, dosyaların kendisi değil.

3. Gün: Ajan Buluyor Ama Kullanmıyor

En sinir bozucu gündü. Aramanın çalıştığını doğruladım, manuel olarak sorgulayıp doğru sonuçları alabiliyordum. Ancak gerçek konuşmalar sırasında Chiti, hafızada açıkça var olmasına rağmen ilgili bağlamı getirmiyordu.

Sorun, getirmenin otomatik olmamasıydı. Ajanın aramaya karar vermesi gerekiyor. Ve konuşma doğru ipuçlarını tetiklemezse, bir şeyleri araştırmaz.

Ne yaptım:

Önyükleme sırasına açık getirme talimatları ekledim. Ajanın ihtiyaç duyduğunda arayacağını ummak yerine, ne zaman arayacağını söyledim:

markdown

Herhangi bir göreve başlamadan önce:

• Günlük kayıtları ilgili bağlam için tara
• Bu tür görevlerle ilgili kurallar için LEARNINGS.md'yi kontrol et
• Bir müşteriden bahsediliyorsa, geçmişini ara

Ayrıca bir getirme testi oluşturdum. Günlük kayda belirli bir işaretçi yerleştirirdim — "MARKER: 2026-02-20 — Kodun gönderildiğini iddia etmeden önce git durumunu kontrol etmeyi unutma." gibi bir şey. Sonra bekler, yeni bir oturum başlatır ve sorardım: "Dünkü işaretçi neydi?" Ajan bulursa, getirme çalışıyor demekti. Bulamazsa, bir şey bozuktu.

Öğrendiklerim:

"Bilginin var olması" ile "ajanın bilgiyi kullanması" arasında fark vardır. İkisine de ihtiyacınız var. Arama altyapısı ilk kısmı halleder. Önyükleme talimatları ve getirme alışkanlıkları ikinci kısmı halleder. İkisini ayrı ayrı test edin.

4. Gün: Sıkıştırmaya Karşı Güvenli Hale Getirmek

Artık hafıza boşaltma, hibrit arama ve getirme talimatlarım vardı. Ancak belirli bir senaryoda bağlam kaybetmeye devam ediyordum: sıkıştırmanın birden çok kez çalıştığı çok uzun oturumlar.

Sorun, hafıza boşaltmanın sıkıştırma döngüsü başına yalnızca bir kez tetiklenmesiydi. Oturum iki veya üç sıkıştırma için yeterince uzunsa, yalnızca ilki boşaltma işlemini alıyordu. Sonrası risk altındaydı.

Ne yaptım:

Sıkıştırmayla birlikte çalışması için bağlam budamayı (context pruning) yapılandırdım:

1{
2  "contextPruning": {
3    "mode": "cache-ttl",
4    "ttl": "6h",
5    "keepLastAssistants": 3
6  }
7}

Bu, 6 saat sonra eski bağlamı agresif bir şekilde budarken son 3 asistan yanıtını korur. Hafıza boşaltma ile birleştiğinde, ajan önemli şeyleri erkenden diske yazar ve eski bağlam taşmaya neden olmadan temizlenir.

Ayrıca bir İŞARETÇİ test protokolü ekledim: önemli herhangi bir yapılandırma değişikliğinden sonra, günlük kayda bir işaretçi yerleştirir ve sıkıştırma sınırları boyunca getirmeyi test ederim. İşaretçi hayatta kalırsa, değişiklik işe yaramıştır. Kalmazsa, bir şey bozulmuştur.

Öğrendiklerim:

Hafıza sistemlerinin gerçekten test edildiği yer uzun oturumlardır. Kısa konuşmalar nadiren sıkıştırmayla karşılaşır. Bağlamı kaybettiğiniz ve nedenini anlayamadığınız 2 saatlik derin çalışma oturumlarıdır. Hafıza sisteminizi hızlı sohbetlerde değil, yük altında test edin.

5. Gün: Sistem Komutu %28 Şişkindi

Her şeyin yerine oturduğu gündü. /context detail çalıştırdım ve sayılara baktım.

Ajanım, mesajımı okumadan önce 11.887 tokenlik sistem komutu yüklüyordu. 51 beceri, 20'sini hiç kullanmamıştım. MEMORY.md, her oturumda yüklenen 200 satırlık bir şirket wiki'siydi. Ve biri BOOT.md'de (OpenClaw'un tanımadığı) ve diğeri AGENTS.md'nin 200 satır derinliğinde gömülü olan iki rakip önyükleme sıram vardı.

En kötüsü, her model değiştirdiğimde Chiti her şeyi unutuyordu. Hiçbir devir teslim protokolü yoktu. Mevcut bağlamın geri yazılması yoktu. Sadece gitti.

Kök neden:

OpenClaw her yeni oturumda şu dosyaları otomatik okur: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md, MEMORY.md.

Diğer her şey — LEARNINGS.md, günlük kayıtlar, dokümanlar, referans dosyaları — ajanın bunları araçları kullanarak kendisinin okuması gerekir. Bu dosyaları okuma talimatı otomatik yüklenen dosyalardan birinde (özellikle AGENTS.md) değilse, ajan onları asla görmez.

BOOT.md dosyam tüm önyükleme sırasını içeriyordu. Ancak OpenClaw BOOT.md'yi otomatik yüklemez. Bu yüzden talimatlar orada, okunmamış, hiçbir şey yapmadan duruyordu.

Ne yaptım:

Tam bir denetim ve temizlik yaptım:

1. Önyükleme sırasını AGENTS.md'nin en üstüne taşıdım (başlangıç talimatları için tek güvenilir yer)
2. BOOT.md'yi sildim (OpenClaw tarafından tanınmıyor)
3. BOOTSTRAP.md'yi sildim (bir kerelik katılım dosyası, zaten tamamlanmış, her oturumda 361 token harcıyordu)
4. MEMORY.md'yi 200 satırdan 90 satıra indirdim, referans dokümanları docs/ klasörüne taşıyarak
5. Oturum başına 3.000 token yiyen 20 kullanılmayan pazarlama becerisini kaldırdım
6. Yazma disiplini ekledim: her görev sonucunu kaydeder, her hata bir kural haline gelir
7. Bir devir teslim protokolü ekledim: herhangi bir model değişikliği veya oturum sonundan önce, ajan mevcut bağlamı günlük kayda yazar

Önyükleme sırası artık şöyle görünüyor:

markdown

HERHANGİ BİR ŞEY yapmadan ÖNCE:

1. USER.md'yi oku
2. learnings/LEARNINGS.md'yi oku
3. memory/YYYY-MM-DD.md'yi oku (bugün + dün)
4. MEMORY.md'yi oku (yalnızca ana oturumda, asla gruplarda değil)
5. PROTOCOL_COST_EFFICIENCY.md'yi oku
6. Şunu yazdır: YÜKLENDİ: KULLANICI | ÖĞRENİLENLER | GÜNLÜK | HAFIZA | PROTOKOL

Yazma disiplini:

markdown

Her görevden SONRA:

1. Karar + sonucu kaydet → memory/YYYY-MM-DD.md
2. Hata varsa → learnings/LEARNINGS.md'ye ekle
3. Önemli bağlam varsa → MEMORY.md'yi güncelle (yalnızca kalp atışı incelemeleri sırasında, asla görevler sırasında doğrudan değil)

Devir teslim protokolü:

markdown

Oturum sonu veya model değişikliğinden ÖNCE:

memory/YYYY-MM-DD.md dosyasına DEVRİR TESLİM bölümü yaz:

• Ne konuşuldu
• Ne kararlaştırıldı
• Bekleyen görevler ve tam ayrıntıları
• Kalan sonraki adımlar

Sonuçlar:

• Sistem komutu: 11.887 → 8.529 token
• Beceriler: 51 → 32
• Oturum tokenları: 18.280 → 14.627
• %28 daha hafif. Aynı ajan. Aynı modeller. Sadece daha az gürültü.

Öğrendiklerim:

Gerçek çözüm daha fazla dosya eklemek değildi. Hiçbir şey yapmayanları kaldırmaktı. Sistem komutundaki her token, ajanın her mesajda taşıdığı bir yüktür. Kullanılmayan beceriler, şişmiş hafıza dosyaları, sistemin okumadığı dosyalar - hepsi sessizce birikir.

1. Günde Bilmek İstediğim Kurallar

5 gün boyunca bir şeyleri kırıp düzelttikten sonra, OpenClaw hafızası kuran herkese vereceğim kurallar bunlar:

1. Yalnızca bu dosyalar otomatik yüklenir: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, MEMORY.md.

Diğer her şeyin AGENTS.md'de açık bir okuma talimatına ihtiyacı vardır. Önyükleme sırasında değilse, ajan onu görmez. BOOT.md, OpenClaw'da gerçek bir şey değildir. Haftalarca bende vardı. Hiçbir şey yapmadı.

2. Önyükleme sırası AGENTS.md'nin en üstüne gider.

Ortasına değil. Sonuna değil. En tepesine. Otomatik yüklenen dosyalar sistem komutuna enjekte edilir, bu nedenle önyükleme talimatlarının ajanın işlediği ilk şey olması gerekir.

3. Yazma disiplini, okuma disiplininden daha önemlidir.

Çoğu kişi ajanın okuması için dosyalar kurar ancak geri yazmayı asla zorunlu kılmaz. Ajan kararları, sonuçları ve hataları diske kaydetmezse, bunlar yalnızca bağlam penceresinde bulunur. Ve bağlam penceresi sıkıştırılır. Geri yazma, geçici bağlamın kalıcı hafızaya dönüşme şeklidir.

4. Görevler sırasında asla doğrudan MEMORY.md'ye yazmayın.

Günlük kayıtlar ham ve yalnızca ekleme amaçlıdır. MEMORY.md, düzenlenmiş uzun süreli hafızadır. Ajanın her şeyi MEMORY.md'ye atmasına izin verirseniz, haftalar içinde 200 satırlık bir karmaşaya dönüşür. MEMORY.md'yi periyodik incelemeler sırasında (kalp atışı veya cron) düzenleyin, yakın zamandaki günlük kayıtlardan içgörüler damıtarak. Bunu, ajanının tam olarak bunu yaptığını — MEMORY.md'yi düzenlenmemiş gürültüyle şişirerek işe yaramaz hale getirdiğini — fark eden bir OpenClaw kullanıcısından öğrendim.

5. LEARNINGS.md en hafife alınan dosyadır.

Ajanın yaptığı her hata, tek satırlık bir kural haline gelmelidir. "Git durumunu kontrol etmeden kodun gönderildiğini asla iddia etme." "Grup sohbetlerinde MEMORY.md'nin tamamını okuma." "Planlama yapmadan önce kullanıcının saat dilimini her zaman onayla." Bu kurallar birikir. Birkaç hafta sonra, ajanınızın kendi başarısızlıklarından oluşturulmuş kişisel bir operasyon el kitabı olur.

6. Sadece depolamayı değil, getirmeyi de test edin.

Bilgi depolamak ve onu getirmek farklı sorunlardır. Dosyaların indekslenip aranabilir olduğu ancak ajan onları aramayı bilmediği için asla erişilmediği durumlar yaşadım. İşaretçiler yerleştirin, oturumlar arasında test edin, model değişiklikleri arasında test edin. Ajan dün depoladığınız bir şeyi bulamıyorsa, depolamanın bir önemi yoktur.

7. Devir teslim protokolü, model değiştirme çözümüdür.

OpenClaw ajanları, model değiştirdiğinizde tüm bağlamı kaybeder. Yeni model, boş bir bağlam penceresiyle başlar — yalnızca otomatik yüklenen dosyaları görür. Değişiklikten önce mevcut durumu günlük kayda döken bir devir teslim protokolü olmadan, yeni modelin neler olduğu hakkında hiçbir fikri olmaz. Bu, haftalarca en büyük sorunumdu.

8. /context detail'i düzenli olarak çalıştırın.

Bu komut, tokenlarınızı tam olarak neyin yediğini gösterir. Kurmayı unuttuğunuz beceriler, fark etmeden büyüyen dosyalar, asla kullanmadığınız araçlar. Oturum başına 3.000 token yakan 20 kullanılmayan beceri buldum. Bu, dokunmadığım özellikler için her mesajda 3.000 tokenlik bir yüktü.

9. Hibrit arama, saf anlamsal aramayı yener.

BM25 (anahtar kelimeler) + vektörler (anlam) + yeniden sıralama, yalnızca vektörlerden önemli ölçüde daha iyi sonuçlar verir. Müşteri adları, belirli sayılar, tam ifadeler — anlamsal arama bunları kaçırır. Anahtar kelime araması yakalar. İkisini de kullanın.

10. Sıkıştırma düşman değildir. Yazılmamış bağlam düşmandır.

Günlerimi sıkıştırmayla savaşarak geçirdim, ta ki çözümün daha basit olduğunu fark edene kadar: sıkıştırma çalışmadan önce önemli olan her şeyin bir dosyaya yazıldığından emin olun. Hafıza boşaltma bunu otomatik olarak halleder. Disktekiler sıkıştırmadan kurtulur. Yalnızca konuşmadakiler risk altındadır.

Mevcut Kurulumum

Referans olarak, çalışma alanım artık şöyle görünüyor:

workspace/

├── AGENTS.md (önyükleme sırası + yazma disiplini + devir teslim protokolü)

├── SOUL.md (kişilik ve davranış)

├── IDENTITY.md (isim, rol)

├── USER.md (sahip bilgisi)

├── TOOLS.md (araç kullanım yönergeleri)

├── HEARTBEAT.md (otonom kontrol davranışı)

├── MEMORY.md (düzenlenmiş uzun süreli hafıza, ~90 satır)

├── PROTOCOL_COST_EFFICIENCY.md

├── learnings/

│ └── LEARNINGS.md (hatalardan çıkarılan kurallar)

├── memory/ (günlük kayıtlar: YYYY-MM-DD.md)

├── docs/ (referans dokümanlar MEMORY.md'den taşındı)

│ ├── tweetsmash-arch.md

│ ├── knowledge-transfer.md

│ ├── infrastructure.md

│ └── group-chat-rules.md

└── skills/ (32 beceri, 51'den düşürüldü)

Sistem komutu: 8.529 token. Oturum tokenları: 200.000 bağlam penceresinin 14.627'si (%7,3). Ajan başlatılır, ihtiyacı olanı okur, öğrendiklerini yazar ve model değişikliklerinden önce bağlamı devreder.

Buraya gelmem 5 gün sürdü. Çoğu, daha fazla dosyanın daha iyi hafıza anlamına geldiği varsayımını terk etmekti. Öyle değil. Disiplin öyle. Deneyimim hala devam ediyor.

TweetSmash ve LinkedMash'i kuruyorum — ortağımla sosyal medya yer imi araçları. OpenClaw ajanlarını üretimde çalıştırma hakkında öğrendiklerimi X'te paylaşıyorum: @code_rams