Claude-Mem Rehberi: Claude Code için Kalıcı Bellek

Birkaç hafta önce, tüm projelerime claude-mem kurdum. O zamandan beri, dizüstü bilgisayarımda 39 MB'lık bir SQLite dosyasında duran on farklı kod tabanını kapsayan 259 oturumda toplam 6.814 gözlem kaydetti.

Bundan önce, her Claude Code oturumu sıfırdan başlıyordu. Yeni bir oturum açar ve ilk on dakikayı proje yapısını yeniden açıklamakla geçirirdim. Bir gün önce birlikte düzelttiğimiz kimlik doğrulama hatası mı? Claude'un bundan haberi yoktu. Zaten analiz ettiği dosyaları yeniden okur, sonra da daha önce düzelttiğimiz aynı yanlış varsayımlara varırdı.

claude-mem, bir oturum sırasında olanları yakalayarak bunları gelecekteki oturumlara sunan bir Claude Code eklentisidir. 

Bu yazıda, kaputun altında gerçekte nasıl çalıştığını, yaygın tuzaklara düşmeden nasıl kuracağınızı, bütçenize göre nasıl ayarlayacağınızı ve üretimde çalıştırmadan önce bilmeniz gerekenleri ele alacağım.

claude-mem nedir?

claude-mem bir Claude Code eklentisidir ve şunları yapar:

• Oturum yaşam döngüsü olaylarına (oturum başlangıcı, her araç çağrısı, oturum sonu) kancalanır
• Ham araç çağrısı çıktılarını yapay zekâ kullanarak yapılandırılmış gözlemlere sıkıştırır
• Her şeyi yerel bir SQLite veritabanında şurada depolar: ~/.claude-mem/claude-mem.db
• Yeni bir oturum başlattığınızda ilgili parçaları geri enjekte eder

Bir MCP sunucusu değil, bir eklenti olarak çalışır. 

Bu ayrım önemlidir: eklentiler, oturum başlangıcı ve her araç çağrısı gibi yaşam döngüsü olaylarında otomatik olarak tetiklenir; MCP sunucuları ise Claude onları çağırmaya karar verene kadar boşta bekler. 

MCP tabanlı bir yaklaşımla, geri getirme yalnızca Claude bunu istemeyi düşünürse gerçekleşir. claude-mem ise Claude'un bunu seçmesine gerek kalmadan yakalar ve enjekte eder.

Her şey makinenizde kalır ve sıkıştırma mevcut Claude Code kimlik doğrulamanızla çalışır; ayrı bir API anahtarı veya hesaba gerek yoktur.

Çalıştırmak için Claude Code oturumu içinde iki komut gerekir:

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

Ardından Claude Code'u yeniden başlatın. 

Yaygın hata, bunun yerine npm install -g claude-mem komutunu çalıştırmaktır; bu yalnızca SDK kitaplığını kurar. Kancalar kaydolmaz, çalışan hiç başlamaz ve hiçbir şey çalışmaz. 

Tam kurulumu sağlayan tek yol eklenti pazarı yoludur. Tek katı önkoşul Node.js 18+ olmasıdır. Diğer her şey (Bun, uv, SQLite) ilk çalıştırmada otomatik kurulur.

Kurulumun gerçekten çalıştığını doğrulamak için üç şeyi kontrol edin. Birincisi, curl http://localhost:37777/api/health komutu {"status":"ok"} döndürmelidir. Başarısız olursa, arka plan çalışanı başlamamıştır. En yaygın neden, 18 altı bir Node.js sürümüdür. 

İkincisi, ~/.claude/hooks.json dosyasının claude-mem girişleri içerdiğini kontrol edin. Dosya PostToolUse ve SessionStart altında claude-mem'i listelemiyorsa, kancalar kaydolmamıştır ve çalışan canlı olsa bile hiçbir yakalama çalışmayacaktır. 

Üçüncüsü, bir tarayıcıda http://localhost:37777 adresini açarak, çalışırken akış halinde gelen gözlemleri gösteren web görüntüleyiciyi görün.

İlk oturumda veritabanı boş olduğundan SessionStart aşamasında enjekte edilen bir bağlam olmaz, ancak gözlemler ilk araç çağrısından itibaren birikmeye başlar. 

İkinci oturuma gelindiğinde, claude-mem enjekte edilecek bir oturum özeti ve bir dizi gözleme sahip olacaktır. 

Önce doğrulama kontrol listesinden geçmek, üç oturum sonra hiçbir şeyin hiç yakalanmadığını fark etmenizi önler. En güvenilir sinyal web görüntüleyicidir: bir araç çağrısından sonra gözlemler görünüyorsa, her şey doğru şekilde bağlanmıştır.

claude-mem Nasıl Çalışır

Kurulduktan sonra, claude-mem beş yaşam döngüsü kancası boyunca arka planda sessizce çalışır. Her birinin ne yaptığını anlamak, aracın neden bu şekilde davrandığını açıklar.

Yakalama ve sıkıştırma

Beş kanca, bir oturumun doğal zaman çizelgesine karşılık gelir:

• SessionStart veritabanını sorgular ve son çalışmanın sıkıştırılmış bir dizinini bağlam pencerinize enjekte eder
• UserPromptSubmit oturumu kaydeder ve isteminizi depolar
• PostToolUse her araç çağrısından sonra tetiklenir ve ham çıktıyı sıkıştırma için bir arka plan çalışana gönderir
• Stop durakladığınızda veya boşta kaldığınızda oturum düzeyinde bir özet üretir
• SessionEnd oturumu tamamlandı olarak işaretler

SessionStart, enjekte edilen o dizini oturum özetlerinden, türe göre gruplanmış gözlem başlıklarından ve zaman damgalarından oluşturur: Claude'un oturum boyunca hiçbir şey yapmanıza gerek kalmadan başvurabileceği, yakın zamandaki çalışmanın aranabilir bir haritası.

PostToolUse her araç çağrısından sonra tetiklenir. Ham çıktıyı engellemeyen bir HTTP POST (ortalama 8 ms) ile arka plan çalışana gönderir ve çalışan bunu Claude Agent SDK kullanarak yapılandırılmış bir gözleme sıkıştırır. 

Bu yapının nasıl göründüğü şöyle:

Araç çağrısı başına yakalama, claude-mem'i oturum sonunda tek bir yapay zekâ çağrısıyla özetleyen araçlardan ayıran şeydir. 

Oturumunuz bir yeniden düzenlemenin ortasında çökerse, bu araçlar son tamamlanan oturumdan beri olan her şeyi kaybeder. claude-mem ise son araç çağrısına kadar olan her gözleme sahiptir.

Stop kancası farklı bir şey üretir: request, investigated, learned, completed ve next_steps gibi alanlara sahip oturum düzeyinde bir özet. Bunlar, Claude'a her bir gözlemi yüklemeden neler olduğuna dair üst düzey bir harita verir.

Geri getirme

Binlerce gözlemi depolamak bir şeydir. Doğru olanları token yakmadan bir bağlam penceresine yüklemek bambaşka bir problemdir.

Saf yaklaşım, geçmiş bağlamı isteme dökmektir. claude-mem'in dokümanları bunun rakamlarını veriyor: tipik bir saf yükleme, bağlam penceresine 35.000 token gönderir; bunun yaklaşık 2.000'i ilgili çıkar. Bu, %6'lık bir sinyal oranıdır. 

Üç katmanlı bir geri getirme sistemi, Claude'un bağlamı claude-mem üzerinden kademeli olarak yüklemesine izin vererek bunu %80'in üzerine çıkarır:

• Katman 1, arama gözlem kimlikleri, başlıklar, tarihler ve türlerden oluşan kompakt bir dizin döndürür. Maliyet: sonuç başına 50-100 token. Yüklemeden neyin mevcut olduğunu görürsünüz.
• Katman 2, zaman çizelgesi belirli bir gözlemin etrafında kronolojik bağlam sağlar, ondan önce ve sonra neler olduğunu gösterir. Maliyet: sonuç başına 100-200 token.
• Katman 3, get_observations tam gözlem kayıtlarını kimliklere göre toplu halde getirir. Maliyet: sonuç başına 500-1.000 token. Yalnızca gerçekten ihtiyacınız olanı çekin.

Bu geri getirme disiplini kendiliğinden uygulanmaz.

claude-mem, tek amacı Claude'a bu üç adımlı deseni takip etmesini hatırlatmak olan __IMPORTANT adlı kelimesi kelimesine bir MCP aracı kaydeder. 

Bu olmazsa, Claude ucuz katmanları atlar ve her şeyi tam ayrıntıda getirir; bu da tüm mimariyi boşa çıkarır. Yalnızca geri getirme disiplinini zorlamak için adlandırılmış bir aracın eklenmesi gerekmesi, sistemin Claude'un gerçek davranışı etrafında nasıl tasarlandığına dair gerçekçi bir resim sunar.

Bu geri getirme araçları yalnızca oturum başında kullanılmaz.

Bir oturum sırasında, Claude'a geçmiş çalışmalar hakkında bir şey sorduğunuzda, bellekte doğrudan arama yapar. 

Oturumlar arasında çalışma kalıplarınızı analiz etmesini, unuttuğunuz ayrıntıları bulmasını ("o API anahtarını nereye kaydetmiştim?", "kimlik doğrulama akışını nasıl uygulamıştık?") veya haftalardır dokunmadığınız bir projede kaldığınız yerden devam etmesini isteyebilirsiniz. 

Birden fazla kod tabanı ve oturum arasında gidip gelirken, ayrıntılar kendi hafızanızdan beklediğinizden daha hızlı sızar. claude-mem bu boşluğu, sizin kişisel olarak unuttuklarınız da dahil olmak üzere olan biten her şeye Claude'un erişmesini sağlayarak doldurur.

Üç hafta sonra, gözlemlerimin %61'i discovery olarak türlenmiş durumda. Claude çoğunlukla yaptığı değişikliklerden ziyade bir kod tabanı hakkında öğrendiklerini yakalıyor. 

259 oturum boyunca, oturum başına ortalama 6-7 olmak üzere 1.729 oturum özetim var. Bu çok oturumlu süreklilik, yalnızca yakalamanın sürekli çalışması sayesinde mümkün; sadece sonunda değil.

Bu, bir oturumu özetlemekle onu gerçekten hatırlamak arasındaki farktır.

claude-mem'i Yapılandırma

claude-mem'in tüm ayarlarına http://localhost:37777 adresindeki web arayüzündeki Settings sekmesinden erişilebilir. Bunları ortam değişkenleri olarak da ayarlayabilir veya doğrudan ~/.claude-mem/settings.json dosyasını düzenleyebilirsiniz.

Bilmeniz gereken ilk ayar CLAUDE_MEM_MODEL olup, sıkıştırmayı hangi modelin yapacağını kontrol eder. Varsayılan haiku olup, zaten Claude'un model dizilimindeki en uygun maliyetli seçenektir.

Sıkıştırma sağlayıcısını tamamen CLAUDE_MEM_PROVIDER ile de değiştirebilirsiniz; claude, gemini veya openrouter kabul eder.

Sıkıştırmayı Gemini Flash Lite veya xiaomi/mimo-v2-flash:free gibi ücretsiz bir OpenRouter modelinde çalıştırmak, mevcut Claude Code aboneliğinizin ötesindeki maliyeti sıfıra düşürür. 

Ben kendi kurulumumu haiku üzerinde ve oturum başına 30 gözlemle çalıştırıyorum. Sıkıştırma çağrısı başına yaklaşık 400 giriş tokenı ve 150 çıkış tokenıyla, bu oturum başına yaklaşık 16.500 token eder. haiku ücretleriyle, yoğun bir kullanım ayı bir doların çok altında tutar.

Üç hafta boyunca on proje genelinde, sıkıştırma kalitesi sorun olmadı.

Oturum başlangıcında ne kadar bağlam yükleneceğini iki ayar kontrol eder:

• CLAUDE_MEM_CONTEXT_OBSERVATIONS: SessionStart aşamasında enjekte edilen toplam gözlem sayısı (varsayılan 50, aralık 1-200)
• CLAUDE_MEM_CONTEXT_FULL_COUNT: bunlardan kaç tanesinin tam narrative alanıyla genişletilmiş ayrıntı göstereceği (varsayılan 5, aralık 0-20)

Geri kalanı yalnızca başlık, tür ve tarih görüntüler. Tüm bağlam enjeksiyonu, üzerinde çalıştığınız proje diziniyle sınırlıdır; böylece diğer projelerden gelen gözlemler bağlamınızı kalabalıklaştırmaz. 

Tam olarak nelerin enjekte edildiğini önizleyebilir ve bu sayıları projeye göre web arayüzü üzerinden ayarlayabilirsiniz.

Beklenmesi gereken bir durum: yeni bir projede ilk hafta, bağlam pencereniz normalden daha hızlı dolabilir. 

Ben o ilk dönemde oturumlar önceye göre daha erken bağlam sınırına takıldığı için claude-mem'i neredeyse kaldırıyordum. 

Olan, claude-mem'in projeyi sıfırdan öğrenmesiydi; oturum başlangıcında enjekte edilen yüksek hacimli yeni gözlemler kaydediliyordu. 

Yaklaşık bir hafta sonra, Claude kod tabanını zaten haritaladığı için yeni keşiflerin hacmi düştü ve oturumlar, eklentiyi kurmadan önceye göre daha uzun sürmeye başladı. 

Bu erken ek yükle karşılaşırsanız, CLAUDE_MEM_CONTEXT_OBSERVATIONS değerini geçici olarak düşürün ve ilk öğrenme dönemi geçtikten sonra tekrar yükseltin.

CLAUDE_MEM_SKIP_TOOLS, belirli araçları yakalamanın dışında bırakmanızı sağlar.

Varsayılanlar zaten TodoWrite, AskUserQuestion ve BashTool gibi yüksek gürültülü araçları atlar. Muhtemelen bunu yalnızca depolanmasını istemediğiniz çıktı üreten özel bir aracınız varsa değiştirmeniz gerekir. Virgülle ayrılmış bir listedir, bu nedenle araç eklemek kolaydır.

API anahtarları veya kimlik bilgileriyle çalışıyorsanız, bunları istemlerinizin içine <private> etiketleriyle sarmalayarak depolamadan hariç tutun.

claude-mem, bir gözlem oluşturmadan önce bu etiketlerin içindeki her şeyi ayıklar. 

Dosya içeriklerini proaktif olarak taramaz; bu nedenle diskten yüklenen ortam değişkenleri risk altında değildir; ancak doğrudan bir isteme yapıştırdığınız her şey risk altındadır. <private> etiketi yaklaşımı, korumanın isteğe bağlı olduğu anlamına gelir: onu kullanmayı hatırlamanız gerekir.

claude-mem vs Yerleşik Bellek ve Alternatifler

Claude Code zaten bellek özellikleriyle birlikte gelir, ancak hiçbirisi bağlamı otomatik olarak yakalamaz. 

CLAUDE.md dosyaları, oturum başında yüklenen statik markdown'lardır; proje kuralları ve tercihler için kullanışlıdır; ancak yaklaşık 200 satırdan sonra uyum azalır. Arama yok, geri getirme yok. Talimatlarınızı bir kez yazarsınız ve Claude'un bunlara uymasını umarsınız.

Otomatik Bellek, Claude Code v2.1.59'da eklendi ve oturumlar arasında neyin kaydedileceğine karar verme sorumluluğunu doğrudan Claude'a verir. Yapılandırılmamış notları ~/.claude/projects/<project>/memory/ altında depolar ve başlangıçta bir MEMORY.md dosyasının ilk 200 satırını yükler. 

Pratikte, kaydedilenler her zaman sizin isteyeceklerinizle örtüşmez ve sonrasında bunları aramanın veya filtrelemenin bir yolu yoktur. Sonunda Claude'un dikkat edip etmeyeceği belli olmayan kararlardan oluşan bir metin dosyasına sahip olursunuz.

Yerleşik seçenekleri tamamlayan /compact komutu ise konuşmanızı özetleyerek bağlam alanını boşaltır. CLAUDE.md dosyaları diskten yeniden okundukları için hayatta kalır; ancak diğer her şey yok olur: konuşma talimatları, oturum ortası bağlamı, bir yerlere yazmadığınız sürece söylediğiniz her şey.

claude-mem, bunların hiçbirinin doldurmadığı boşluğu kapatır: yapılandırılmış sıkıştırma ve token farkındalığı olan geri getirme ile otomatik, sürekli yakalama. Bu işi yapan tek eklenti de değildir.

memsearch, bir veritabanı yerine markdown dosyaları istiyorsanız ve çalışan bir arka plan süreci istemiyorsanız en yakın ücretsiz alternatiftir. Geri getirmeyi izole bir alt ajan içinde çalıştırır; böylece arama sonuçları hiçbir zaman ana bağlam pencerenize karışmaz. Daha basit bir kurulum tercih ediyorsanız ve çağrı başına yakalamaya ihtiyacınız yoksa kullanın. 

supermemory, makineden makineye eşitleme ve paylaşılan takım belleğine ihtiyacınız varsa doğru tercihtir; ancak ücretli bir abonelik gerektirir. 

Self-hosted mem0 yığını ise bambaşka bir yaklaşım benimser: grafik tabanlı varlık takibi için Qdrant ve Neo4j, sıfır ek maliyet; ancak yalnızca zaten bu altyapıyı çalıştırıyorsanız değecek daha ağır bir kurulum.

claude-mem ortada bir yerde durur. Tamamen yerel, ücretsiz, çağrı başına yakalama ve yapılandırılmış sıkıştırma. Taviz ise 37777 portunda bir arka plan çalışanı ve henüz giderilmemiş bazı pürüzlerdir.

claude-mem Sınırlamaları ve Bilinen Sorunlar

En büyük endişe güvenlik tablosudur.

Bir topluluk denetimi Şubat 2026'da riski YÜKSEK olarak değerlendirdi ve sorunlar hâlâ açık. 

37777 portundaki HTTP API'nin kimlik doğrulaması yok: makinenizdeki herhangi bir süreç depolanan tüm gözlemleri okuyabilir, ayarlarınızı (açık metin hâlindeki API anahtarları dahil) görüntüleyebilir ve veritabanına keyfî anılar enjekte edebilir. 

Varsayılan ana bilgisayar bağlaması 0.0.0.0 idi; bu da bulut VM'lerinde veya güvenlik duvarı olmayan makinelerde API'nin ağa açık olduğu anlamına gelir. 

smart_unfold ve smart_outline araçlarında da dizin sınırı kontrolü olmadan yol geçişi açığı vardır.

Bunu yalnızca kişisel bir geliştirme makinesinde çalıştırın.

Güvenilirlik tarafında da bazı keskin köşeler var.

ChromaDB entegrasyonunda bilinen bir alt süreç sızıntısı var: bir kullanıcı 19 saatte 184 yetim süreç ve yaklaşık 16 GB RAM kullanımına kadar izini sürdü. 

Kök neden, sonsuz yeniden deneme döngülerini tetikleyen bozuk bir ONNX modeliydi. Bunun yerine ChromaDB olmadan da çalışan ve benim deneyimimde güvenilir olan FTS5'e (SQLite'ın yerleşik tam metin arama motoru) bağlı kalın.

 Apple Silicon'lı macOS'ta, ChromaDB etkinleştirildiğinde çalışan soğuk başlangıcı, sabit kodlanmış 5 saniyelik zaman aşımını aşabilir ve SessionStart kancasının başarısız olmasına neden olabilir. Bu, yalnızca FTS5 kurulumlarını etkilemez. Ayrıca search ve timeline MCP araçlarının boş parametre şemalarına sahip olduğu, bu nedenle Claude'un onlara sorgu iletemediği etkin bir hata da var. get_observations sorunsuz çalışıyor.

Bunlar kişisel bir makinede yerel geliştirme için caydırıcı değil. Ancak tüm oturum geçmişinize erişimi olan bir şeyi kurmadan önce bilinmeye değer.

Son Düşünceler

Üç hafta sonunda fark ettiğim ana şey, artık yapmadıklarım. Her oturumun başında proje yapısını yeniden açıklamıyorum. Daha önce yürüdüğümüz bir hata ayıklama yolunu yeniden izlemiyorum. Claude bağlamla geliyor ve kaldığımız yerden başlıyoruz.

Mimari, bunu daha basit yaklaşımların yapamadığı şekilde mümkün kılıyor. Yalnızca oturum sonunda yakalamak, bir oturum çökerse her şeyi kaybetmek demektir. Geri getirme katmanları olmadan geçmişi dökmek, gürültüye token harcamak demektir. Buradaki tasarım tercihleri kasıtlıdır ve bunları bilmek, araca sadece güvenmek yerine onu ayarlamanıza yardımcı olur.

Yukarıda ele alınan güvenlik açıkları gerçektir ve hâlâ açıktır. Bu, kişisel bir geliştirme makinesinde çalıştırmaya değer. Bu sorunlar yamalanana kadar bir bulut VM'sinde veya paylaşılan bir makinede çalıştırmaya değmez. Ancak yerel ve tek kişilik geliştirme için tavizler yönetilebilir.

Daha derine inmek isterseniz, DataCamp'in Claude'a Giriş kursu, üzerine eklentiler eklemeden önce Claude Code'un nasıl çalıştığını anlamak için sağlam bir başlangıç noktasıdır.