LangChain Ajanlarının Uzun Konuşmalarda Yaşadığı Bellek Kaybını Nasıl Düzeltirsiniz

Eğer bir LangChain ajanı uzun bir konuşma sırasında detayları unutuyorsa, model bağlam penceresini artırmadan önce mimariyi düzeltin. Güncel LangChain v1 tarzı ajanlarda, konuşma sürekliliği iki ayrı katmandan oluşturulur: kısa vadeli, iş parçacığı kapsamlı durum için bir checkpointer ve iş parçacıkları arasında hayatta kalması gereken uzun vadeli bilgiler için bir store (depo). Uzun konuşmalar ayrıca üçüncü bir endişe gerektirir: bağlam yönetimi, genellikle eski mesajlar modeli bunaltmadan önce bunların kırpılması veya özetlenmesi.

Bu rehber, 11 Eylül 2026 tarihinde kontrol edilen LangChain'in resmi dokümantasyonunu takip etmektedir. Güncel dokümanlar, yeni ajanlar için langchain.agents.create_agent kullanımını önermekte ve LangGraph kalıcılığını temel bellek sistemi olarak tanımlamaktadır. ConversationChain, ConversationBufferMemory veya initialize_agent tabanlı eski örnekler eski materyallerde hala görünebilir, ancak LangChain'in v1 geçiş rehberi eski zincirleri ve diğer kullanımdan kaldırılmış işlevleri langchain-classic paketine taşımıştır. Resmi LangChain v1 geçiş rehberine bakın.

LangChain'de "Bellek Kaybı" Gerçekte Ne Anlama Gelir?

Kodu değiştirmeden önce, kullanıcı bakış açısından genellikle aynı görünen üç sorunu birbirinden ayırın.

LangChain'in kısa vadeli bellek dokümantasyonu, kısa vadeli belleği tek bir iş parçacığı içindeki durum olarak tanımlar. Uzun vadeli bellek dokümantasyonu ise uzun vadeli belleği, farklı konuşmalar ve oturumlar arasında kalıcı olan bilgi olarak tanımlar.

Başlamadan Önce İhtiyacınız Olanlar

Güncel bir LangChain/LangGraph uygulamasına, bir model entegrasyonuna ve durumu kalıcı hale getirecek bir yere ihtiyacınız var. Yerel bir deney için InMemorySaver yeterlidir. Üretim ortamı için, veritabanı destekli bir checkpointer kullanın. LangChain'in resmi dokümanları, ayrı langgraph-checkpoint-postgres paketi aracılığıyla PostgreSQL kullanımını göstermektedir.

Dört tanımlayıcıyı net tutun:

• Konuşma veya sohbet ID'si: Uygulamanızın kullanıcılara sunduğu tanımlayıcı.
• thread_id: Bir iş parçacığının durumunu sürdürmek için kullanılan LangGraph kalıcılık anahtarı.
• Kullanıcı ID'si: Uzun vadeli bellekleri isimlendirmek (namespace) için kullanılan kalıcı kimlik.
• Bellek anahtarı: Bir store isim alanındaki tek bir kalıcı öğenin anahtarı.

Bunlar otomatik olarak aynı değer olmamalıdır. Bir kullanıcının birçok iş parçacığı olabilir ve bir iş parçacığı birçok bilgi içerebilir.

Adım 1: İki İstekli Bir Testle Hatanın Tekrarlanmasını Sağlayın

Mümkün olan en küçük testle başlayın. Ajandan benzersiz bir detayı hatırlamasını isteyin, ardından onu tekrar çağırın ve o detayı sorun. Kalıcılık bozuk olsa bile modelin tek bir istekteki her şeyi görebileceği için belleği tek bir invoke() çağrısıyla test etmeyin.

config = {"configurable": {"thread_id": "debug-thread-001"}}

agent.invoke(
    {"messages": [{"role": "user", "content": "Proje kod adımın Juniper olduğunu hatırla."}]},
    config,
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Proje kod adım ne?"}]},
    config,
)

İkinci istek "Juniper"i unutursa, istemleri (prompts) değiştirmeden önce checkpointer yapılandırmasını ve gerçek thread_id'yi inceleyin.

Adım 2: Aynı İş Parçacığı Belleği İçin Bir Checkpointer Ekleyin

Bir checkpointer, ajanın grafik durumunun anlık görüntülerini kalıcı hale getirir. LangGraph bunu kısa vadeli bellek, kesinti kurtarma, insan döngüsünde (human-in-the-loop) akışlar ve hata toleransı için kullanır. Güncel kalıcılık rehberi, checkpoint'leri iş parçacığı kapsamlı olarak tanımlar ve uygulamanın bir thread_id geçirerek duruma eriştiğini belirtir. Resmi LangGraph kalıcılık rehberine bakın.

from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver

checkpointer = InMemorySaver()

agent = create_agent(
    model="your-provider:your-model",
    tools=[],
    checkpointer=checkpointer,
)

config = {"configurable": {"thread_id": "customer-42:case-7"}}

InMemorySaver, iş parçacığı bağlantınızın çalıştığını doğrulamak için mükemmeldir, ancak checkpoint'leri RAM'de saklar. LangGraph, MemorySaver/InMemorySaver işlemlerinin süreç yeniden başlatmalarında kalıcı olmadığını açıkça uyarır.

Adım 3: Aynı Konuşma İçin Aynı thread_id'yi Koruyun

En yaygın uygulama düzeyindeki hata, her HTTP isteğinde yeni bir thread_id oluşturmaktır. Veritabanı mükemmel çalışıyor olabilir, ancak her istek farklı bir LangGraph iş parçacığı başlatıyor olabilir.

Örneğin, ön ucunuzda sohbet ID'si chat_8bf4 olsun. Bu değeri LangGraph iş parçacığına deterministik olarak eşleyin ve o sohbetteki her tur için yeniden kullanın. Yeni bir sohbet, yeni bir iş parçacığı ID'si almalıdır.

Aynı kullanıcıya ait tüm sohbetler için kalıcı tek bir thread_id kullanmayın. Bu, ilgisiz konuşmaları tek bir durum akışında birleştirir. PostgreSQL kullanıyorsanız, LangGraph'in güncel sorun giderme rehberi ayrıca thread_id'nin 255 karakterin altında kalması gerektiğini belirtir; bir UUID veya deterministik hash, devasa bir serileştirilmiş nesneden daha güvenlidir.

Adım 4: Üretim Öncesi Bellek İçi Kalıcılığı Değiştirin

İki istekli test başarılı olduktan sonra, bir süreç yeniden başlatmayı test edin. Bir bilgiyi kaydedin, uygulamayı durdurun, tekrar başlatın ve ardından aynı iş parçacığı ID'siyle bilgiyi sorun. Hala InMemorySaver kullanıyorsanız, unutma beklenen bir davranıştır.

Resmi kısa vadeli bellek dokümanları, PostgresSaver kullanan PostgreSQL destekli bir üretim kurulumunu gösterir:

from langchain.agents import create_agent
from langgraph.checkpoint.postgres import PostgresSaver

DB_URI = "postgresql://user:password@db-host/app"

with PostgresSaver.from_conn_string(DB_URI) as checkpointer:
    checkpointer.setup()
    agent = create_agent(
        model="your-provider:your-model",
        tools=[],
        checkpointer=checkpointer,
    )

LangChain tarafından şu anda belgelenen paket kurulumu için Kısa vadeli bellek sayfasına bakın. Gerçek veritabanı kimlik bilgilerini doğrudan kaynak koduna koymayın; normal gizli bilgi yönetim sisteminizi kullanın.

Adım 5: Her Şeyi Sonsuza Dek Göndermek Yerine Uzun Geçmişleri Yönetin

Bir bağlam penceresi, bir modelin tek bir model çağrısında işleyebileceği girdi ve çıktı bağlamı miktarıdır. Checkpointing, depolamada çok uzun bir konuşmayı koruyabilir, ancak bu, her tarihsel mesajın sonsuza dek modele geri gönderilmesi gerektiği anlamına gelmez.

LangChain'in kısa vadeli bellek rehberi, uzun geçmişlerin model bağlam penceresini aşabileceğini ve tam geçmişi kabul edebilen modellerin bile bayat veya konuyla ilgisiz içerikler tarafından dikkat dağıtılabileceğini, bunun da daha yüksek gecikme ve maliyete yol açtığını belirtir. Belgelenen stratejiler, kırpma, silme, özetleme veya özel bir politika uygulamaktır.

Eski detaylar hala önemliyse özetleme kullanın

SummarizationMiddleware, son mesajları korurken eski geçmişi kompakt bir özetle değiştirmek için mevcut yerleşik seçenektir. Tetikleyicisi, token sayısı, mesaj sayısı veya model bağlamının bir kesrine dayandırılabilir.

from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware

agent = create_agent(
    model="your-provider:your-model",
    tools=[],
    checkpointer=checkpointer,
    middleware=[
        SummarizationMiddleware(
            model="your-provider:summary-model",
            trigger=("fraction", 0.8),
            keep=("fraction", 0.3),
        )
    ],
)

Yukarıdaki sayılar evrensel ayarlar değil, örnek bir politikadır. Eşiklerinizi kendi istemlerinizi, araç çıktılarınızı, model bağlam sınırlarınızı, gecikmenizi ve özet kalitenizi ölçtükten sonra seçin. Şu anda desteklenen tetikleyici ve koruma seçenekleri için LangChain'in yerleşik middleware dokümantasyonuna bakın.

Araç mesajlarını körü körüne kırpma

Özel silme veya kırpma uyguluyorsanız, geçerli bir mesaj sırasını koruyun. LangChain, birçok sağlayıcının araç çağrıları içeren bir asistan mesajının, ilgili araç sonucu mesajlarıyla takip edilmesini gerektirdiği konusunda uyarır. Bu çiftin yarısını kaldırmak, sağlayıcı hatalarına veya kafa karıştırıcı model davranışlarına neden olabilir.

Adım 6: Kalıcı Bilgileri Uzun Vadeli Bir Store'a Taşıyın

Bir store, LangGraph'ın tek bir iş parçacığının grafik durumu dışındaki uygulama tanımlı veriler için kalıcılık katmanıdır. Güncel LangChain dokümanları, mağazaları (stores), kullanıcı tercihleri, bilgiler veya paylaşılan uygulama bilgileri gibi konuşmalar arasında kullanılabilir olması gereken bilgiler için kullanır.

Uzun vadeli store öğeleri, bir isim alanı (namespace) ve bir anahtar (key) ile organize edilen JSON belgeleridir. Pratik bir isim alanı genellikle bir kullanıcı veya organizasyon tanımlayıcısı içerir:

namespace = ("users", user_id, "preferences")
store.put(
    namespace,
    "response_style",
    {"value": "concise", "source": "explicit_user_request"},
)

Bu, tüm transkripti kaydetmekten farklıdır. Ürününüzün kasıtlı olarak kalıcı olarak kabul ettiği bilgiyi saklayın. Bir bilgi özel veya düzenlenmişse, "ajan belleğinin" bunlardan muaf olduğunu varsaymak yerine normal saklama, yetkilendirme, şifreleme ve silme politikalarınızı uygulayın.

Üretimde veritabanı destekli bir store kullanın

Resmi uzun vadeli bellek rehberi hem InMemoryStore hem de PostgresStore gösterir ve bellek içi uygulamanın üretim için veritabanı destekli bir store ile değiştirilmesi gerektiğini açıkça belirtir. Ayrıca PostgreSQL dışındaki store entegrasyonlarını da listeler. "Bellek" kelimesi geçtiği için bir vektör veritabanı seçmek yerine, dağıtım ve operasyonel gereksinimlerinize uyan arka ucu kullanın.

Sadece bulanık hatırlama gerektiğinde semantik arama ekleyin

LangGraph store'ları, store.search()'in öğeleri semantik benzerliğe göre alabilmesi için bir indeks ile yapılandırılabilir. Bu, çok fazla belleğiniz olduğunda ve tam anahtarı bilmediğinizde kullanışlıdır. Küçük bir yapılandırılmış tercih kümesi için, doğrudan isim alanı/anahtar araması genellikle daha basit ve deterministiktir.

Adım 7: Bellek Okuma ve Yazma Yollarını Açık Hale Getirin

Uzun vadeli bir öğeyi kalıcı hale getirmek, ajanın onu kullanacağını garanti etmez. Uygulamanın hala bir geri getirme (retrieval) yoluna ihtiyacı vardır. Güncel LangChain ajanları, araçların sağlanan store'a ToolRuntime aracılığıyla erişmesine izin verir.

from dataclasses import dataclass
from langchain.tools import tool, ToolRuntime

@dataclass
class Context:
    user_id: str

@tool
def get_response_style(runtime: ToolRuntime[Context]) -> str:
    store = runtime.store
    if store is None:
        return "No memory store configured"

    namespace = ("users", runtime.context.user_id, "preferences")
    item = store.get(namespace, "response_style")
    return item.value["value"] if item else "default"

Ayrıca, bir model çağrısından önce durumu ve kalıcı belleği okuyan dinamik istemler veya middleware'ler oluşturabilirsiniz. Önemli tasarım kuralı, geri getirme yolunun gözlemlenebilir ve test edilebilir olmasıdır. "Bilgi veritabanında bir yerde mevcut" ifadesi yeterli değildir.

Adım 8: Dört Bellek Sınırını Ayrı Ayrı Test Edin

Güvenilir bir bellek test paketi, "model bir kez adımı hatırladı" ifadesinden daha fazlasını kapsamalıdır. En az şu dört durumu kullanın:

Ardından, özetleme eşiğinizi aşan uzun bir konuşma testi ekleyin. Önemli kalıcı bilgilerin hayatta kaldığını, son araç çağrısı sıralarının geçerli kaldığını ve istem boyutunun hedef bütçeniz içinde kaldığını doğrulayın.

Minimal Bir Üretim Mimarisi

Çoğu ajan uygulaması için sağlam bir tasarım şu şekilde görünür:

1. API, user_id, conversation_id ve yeni kullanıcı mesajını alır.
2. Uygulama, conversation_id'yi kararlı bir LangGraph thread_id'sine eşler.
3. Kalıcı bir checkpointer, iş parçacığı durumunu geri yükler.
4. Uzun vadeli bir store, istek için gereken yalnızca kalıcı kullanıcı veya uygulama bilgilerini geri getirir.
5. Özetleme veya kırpma, modele yönelik geçmişi ölçülmüş bir bağlam bütçesi içinde tutar.
6. Ajan, araçları ve modeli çalıştırır.
7. Checkpointer, güncellenmiş iş parçacığı durumunu taahhüt eder (commit).
8. Yalnızca onaylanan bilgiler uzun vadeli store'a yazılır.

LangGraph Agent Server aracılığıyla dağıtım yapıyorsanız, güncel kalıcılık rehberi, sunucunun kalıcılık altyapısını otomatik olarak ele aldığını belirtir, bu nedenle dağıtım modelini kontrol etmeden o katmanı çoğaltmayın.

Belleği Bozuk Gösteren Yaygın Hatalar

Her istek için yeni bir thread_id oluşturmak

Bu, her turda yeni bir konuşma durumu oluşturur. İş parçacığı ID'sini uygulama sohbet ID'nizin yanına günlüğe kaydedin ve yeniden kullanımı doğrulayın.

Çok işçili veya yeniden başlatılabilir bir hizmette InMemorySaver kullanmak

RAM yerel durumu, süreçle birlikte kaybolur ve işçiler arasında paylaşılmayabilir. Üretim sürekliliği için kalıcı bir arka uç kullanın.

Checkpointer'ın bağlam penceresi sorununu çözdüğünü varsaymak

Bir checkpointer durumu korur; sürekli büyüyen bir transkriptin model için faydalı olacağını garanti etmez. Açık bir bağlam yönetimi politikası ekleyin.

Her tarihsel bilgiyi isteme koymak

Daha fazla bağlam, otomatik olarak daha iyi bağlam değildir. Mevcut turla ilgili bilgiyi geri getirin ve son konuşma sürekliliğini ayrı olarak koruyun.

Özetleri mükemmel bir veritabanı gibi ele almak

Özetler, sıkıştırılmış model tarafından oluşturulan temsillerdir. Bir bilgi kesin olmalıysa (bir hesap tanımlayıcısı, sözleşmesel kısıtlama, kullanıcı onaylı tercih veya iş akışı durumu), tekrarlanan özetlemelerden sağ çıkmasını ummak yerine onu yapılandırılmış veri olarak saklayın.

Kısa vadeli ve uzun vadeli kapsamları karıştırmak

İş parçacığı geçmişi sessizce küresel bir kullanıcı profiline dönüşmemelidir. Tersine, kullanıcıyı sohbetler arasında takip etmesi amaçlanan bir kullanıcı tercihi yalnızca tek bir iş parçacığında yaşamamalıdır.

İçe aktarmaları kontrol etmeden v1 öncesi bellek eğitimlerini kopyalamak

Bir örnek eski zincirlerden veya eski bellek sınıflarından başlıyorsa, yeni bir uygulamada kullanmadan önce onu güncel v1 geçiş ve bellek dokümanlarıyla karşılaştırın.

Hata Ayıklama Kontrol Listesi

• Ajanın bir checkpointer ile oluşturulduğunu doğrulayın.
• Ardışık istekler arasında thread_id'yi günlüğe kaydedin ve karşılaştırın.
• Modeli suçlamadan önce saklanan iş parçacığı durumunu inceleyin.
• Süreci yeniden başlatın ve aynı iş parçacığı testini tekrarlayın.
• Üretim için InMemorySaver'ı kalıcı bir checkpointer ile değiştirin.
• Uzun sohbetlerde mesaj/token büyümesini ölçün.
• Geçmiş aşırı hale gelmeden önce özetleme veya kırpma etkinleştirin.
• Mesajları kaldırırken araç çağrısı/sonuç sıralarını geçerli tutun.
• İş parçacıkları arası bilgileri isimlendirilmiş bir uzun vadeli store'a taşıyın.
• Kasıtlı uzun vadeli hatırlamayı doğrulamak için aynı kullanıcı için yeni bir iş parçacığı test edin.
• Bellek izolasyonunu doğrulamak için farklı bir kullanıcı test edin.
• Her yanıt için hangi bellek öğelerinin geri getirildiğini izleyin.

Sonuç

LangChain ajan bellek kaybı, nadiren tek bir daha büyük bağlam penceresiyle çözülür. Önce bir checkpointer ve kararlı bir thread_id ile iş parçacığı durumunu kalıcı hale getirin. Ardından, uzun geçmişleri kırpma veya SummarizationMiddleware ile kontrol edin. Son olarak, konuşmalar arasında hayatta kalması gereken bilgileri isimlendirilmiş bir uzun vadeli store'a yerleştirin ve onları kasıtlı olarak geri getirin.

Bu ayrım, size "bellek"ten çok daha faydalı bir şey verir: Bir kullanıcı "Ajan neden unuttu?" diye sorduğunda yeniden başlatabileceğiniz, ölçeklendirebileceğiniz, test edebileceğiniz, denetleyebileceğiniz ve hakkında akıl yürütebileceğiniz bir sistem.