Asla unutmayan yapay zeka ajanları oluşturun

İşte İngilizceden Türkçeye (Türkçe) çevrilmiş metin:

Ajan belleği üzerine ilk prensiplerden başlayan bir anlatım: Python listelerinden markdown dosyalarına, vektör aramadan grafik-vektör melezlerine ve son olarak tüm bunlar için temiz, açık kaynaklı bir çözüme.

Bir LLM tasarımı gereği durumsuzdur (stateless). Her API çağrısı sıfırdan başlar. ChatGPT ile sohbet ederken hissettiğiniz "bellek", her istekle birlikte tüm konuşma geçmişinin yeniden gönderilmesiyle oluşturulan bir illüzyondur.

Bu hile, gündelik sohbetler için işe yarar. Ancak gerçek bir ajan oluşturmaya çalıştığınız anda çöker.

Belleği atladığınız anda ortaya çıkan 7 başarısızlık modu:

1. Bağlam unutkanlığı: Ajan, daha önce verdiğiniz bilgileri tekrar sorar.
2. Sıfır kişiselleştirme: Her etkileşim genel ve kişiliksiz gelir.
3. Çok adımlı görev başarısızlığı: Ara durum, görevin ortasında sessizce kaybolur.
4. Tekrarlanan hatalar: Dönemsel (episodic) hatırlama olmadığı için aynı hatalar sonsuza dek tekrarlanır.
5. Bilgi birikimi olmaması: Her oturum sıfırdan başlar.
6. Boşluklardan kaynaklanan halüsinasyon: Bağlam taştığında model uydurmaya başlar.
7. Kimlik çöküşü: Süreklilik olmaz, güven olmaz.

Bariz tepki "daha fazla bağlam eklemek" olur. Bu yüzden 128K ve 200K token pencereleri her şeyi çözecekmiş gibi gelir.

Ama çözmezler.

İlgili bilgi, uzun bir bağlamın ortasında kaldığında doğruluk %30'un üzerinde düşer. Bu, iyi belgelenmiş "ortada kaybolma" (lost in the middle) etkisidir.

Bağlam, ortak bir bütçedir: sistem promptları, getirilen belgeler, konuşma geçmişi ve çıktının tümü aynı tokenlar için savaşır.

100K token'da bile kalıcılık (persistence), önceliklendirme ve belirginlik (salience) olmadan, ham bağlam uzunluğu yetersiz kalır.

Bellek, prompt'a daha fazla metin tıkıştırmakla ilgili değildir. Önemli olan, ajanın neyi hatırladığını, neyin önemli olduğunu bulabileceği şekilde yapılandırmaktır.

Gerçekten yardımcı olan bilişsel bilim çerçevesi

Lilian Weng'in 2023'teki formülasyonu varsayılan çerçeve haline geldi:

Ajan = LLM + Bellek + Planlama + Araç Kullanımı.

Dört eşit temel sütun.

Onun sınıflandırması, insan belleğinin üç sisteme ayrıldığı bilişsel bilimden ödünç alınmıştır:

• Duyusal bellek (Sensory memory) ham algısal girdiyi yakalar ve saniyenin çok küçük bir kısmı kadar tutar. Dikkat ettiğiniz kısımlar bir sonraki aşamaya geçer.
• Çalışma belleği (Working memory) aktif düşünmenin gerçekleştiği yerdir. Bir seferde yaklaşık 7±2 öğe tutar (Miller'ın 1956 bulgusu). Dikkatiniz dağılırsa, içerikler kaybolur.
• Uzun süreli bellek (Long-term memory) pratikte sınırsız kapasiteye sahip kalıcı bir depodur. Darboğaz geri getirmedir (retrieval): milyonlarca şey depolayabilir ama ihtiyacınız olanı hatırlamakta başarısız olabilirsiniz.

Bunların her biri, modern ajan mimarilerindeki bir bileşene doğrudan karşılık gelir:

Uzun süreli belleğin kendisi de daha da ayrılır:

• Dönemsel (Episodic): Belirli geçmiş olaylar ("Salı günü PostgreSQL kümesi çöktü")
• Anlamsal (Semantic): Gerçekler ve kavramlar ("PostgreSQL ilişkisel bir veritabanıdır")
• Prosedürel (Procedural): Beceriler ve iş akışları ("bir kullanıcı geri ödeme talep ettiğinde, önce satın alma tarihini kontrol et")

Dönemsel ve anlamsal bellek arasındaki köprü bellek konsolidasyonudur: tekrarlanan belirli olayların genel bilgiye dönüşmesi. Düzinelerce etkileşim boyunca "kullanıcıların sürekli olarak yönetici özetlerini tercih ettiğini" fark eden bir ajan, bunu yeniden kullanılabilir bir kurala dönüştürmelidir. Konsolidasyon olmadan, ajanınız bireysel olayları yeniden oynatır, onlardan öğrenmez.

Minimum ajan ve ilk neyin bozulduğu

Çerçeveleri bir kenara bırakın ve bir ajan bir döngüdür: algıla, düşün, harekete geç.

1class Agent:
2    """Minimal AI agent: perceive, think, act"""
3    def __init__(self):
4        self.client = anthropic.Anthropic()
5        self.model = "claude-sonnet-4-20250514"
6
7    def run(self, user_input: str) -> str:
8        response = self.client.messages.create(
9            model=self.model,
10            max_tokens=1024,
11            messages=[{"role": "user", "content": user_input}],
12        )
13        return response.content[0].text

"4 elmam var" deyin, sonra "bir tane yedim, kaç tane kaldı?" diye sorun, ne elmalarından bahsettiğiniz hakkında hiçbir fikri olmaz. Her çağrı kendi başına, izole bir şekilde var olur.

Katman 1: Python listesi

Herkesin başvurduğu ilk düzeltme:

1class Agent:
2    def __init__(self):
3        self.client = anthropic.Anthropic()
4        self.messages = []  # Tüm "bellek" bir listedir
5
6    def chat(self, user_input: str) -> str:
7        self.messages.append({"role": "user", "content": user_input})
8        response = self.client.messages.create(
9            model="claude-sonnet-4-20250514",
10            max_tokens=1024,
11            messages=self.messages,  # Tüm geçmiş her seferinde gönderilir
12        )
13        reply = response.content[0].text
14        self.messages.append({"role": "assistant", "content": reply})
15        return reply

Artık çok turlu (multi-turn) çalışıyor. Elmalarla ilgili soru doğru cevaplanır çünkü konuşmanın tamamı her çağrıyla birlikte yeniden gönderilir.

Hızla iki sorun ortaya çıkar:

• Liste sınırsızca büyür. Yaklaşık 200. turda bağlam tavanına ulaşırsınız ve en eski mesajlar sessizce kaybolur. 1. turdaki kullanıcı adı, dünkü önemsiz şakadan çok daha önce yok olur. Hiçbir önceliklendirme yoktur, sadece katı bir kronolojik sıra vardır.
• Her şey RAM'de yaşar. Python süreci sona erdiği anda, ajanınız kim olduğunuzu unutur.

Katman 2: Kalıcılık için Markdown dosyaları

Bir sonraki adım, belleği diske yazmaktır. Markdown doğal bir uyum sağlar: insan tarafından okunabilir, Git dostudur ve ajan bunu düz metin olarak geri okuyabilir. Claude Code, CLAUDE.md ve MEMORY.md dosyalarıyla tam olarak bu kalıbı kullanır.

1class MarkdownMemoryAgent:
2    def __init__(self):
3        self.client = anthropic.Anthropic()
4        self.history_file = Path("memory/conversation_history.md")
5        self.facts_file = Path("memory/known_facts.md")
6
7    def save_to_disk(self, role: str, content: str) -> None:
8        with open(self.history_file, "a") as f:
9            f.write(f"### {role} at {datetime.now().isoformat()}\n{content}\n\n")
10
11    def load_history(self) -> str:
12        if self.history_file.exists():
13            return self.history_file.read_text()
14        return ""
15
16    def chat(self, user_input: str) -> str:
17        self.save_to_disk("user", user_input)
18        history = self.load_history()
19        response = self.client.messages.create(
20            model="claude-sonnet-4-20250514",
21            max_tokens=1024,
22            system=f"Previous conversation:\n{history}",
23            messages=[{"role": "user", "content": user_input}],
24        )
25        reply = response.content[0].text
26        self.save_to_disk("assistant", reply)
27        return reply

Kalıcılık sorunu çözüldü. Betiği yeniden başlatın, konuşma hâlâ diskte duruyor. Ayrıca, ajanın zamanla çıkardığı ayrı bir gerçekler (facts) dosyası da tutabilirsiniz:

1- Kullanıcının adı Sarah
2- Sarah, Acme Corp'da arka uç ekibini yönetiyor
3- Acme Corp bir B2B SaaS şirketidir
4- Şu anda üretim veritabanını yeni bir AWS bölgesine taşıyor

Dosyayı herhangi bir editörde açabilir, ajanın tam olarak ne bildiğini görebilir ve elle düzeltebilirsiniz. Prototip oluşturmak için gerçekten kullanışlıdır.

4 gerçekle bu mükemmel çalışır. Dosyanın tamamını bağlama yükleyin ve LLM, Sarah, şirketi veya sektörü hakkındaki herhangi bir soruyu halleder.

Şimdi üç ay ileri saralım. Ajanınızın 2.000 çıkarılmış gerçeği ve 200 konuşma günlüğü var. Bu, diskte 500K+ token markdown demektir ve bağlam pencereniz 128K'dır.

Artık her şeyi yükleyemezsiniz. Yalnızca mevcut sorguyla ilgili gerçekleri seçici olarak getirmeniz gerekir. Düz dosyalarla tek seçeneğiniz anahtar kelime aramasıdır:

1# Kullanıcı soruyor: "Bulut geçişimizin durumu nedir?"
2grep("cloud migration", facts_file)
3# Çıktı: []
4# Diskteki gerçek şöyle diyor: "üretim veritabanını yeni bir AWS bölgesine taşıyor"
5# "Cloud migration" kelimeleri hiçbir yerde geçmiyor.
6
7# Kullanıcı soruyor: "Veritabanı işini hangi ekip yürütüyor?"
8grep("database team", facts_file)
9# Çıktı: []
10# Bir gerçek Sarah'nın "arka uç ekibini yönettiğini" söylüyor. Bir diğeri ekibin
11# "üretim veritabanını taşıdığını" söylüyor. Ancak hiçbir satırda
12# hem "veritabanı" hem de "ekip" birlikte geçmiyor.

Küçük ölçekte markdown dosyaları işe yarar. Gerçek ölçekte ise anahtar kelime getirmeye zorlarlar ve anahtar kelimeler eşanlamlıları, açımlamaları veya gerçekler arasındaki bağlantıları işleyemez.

Bilgi diskte duruyor. Ancak hepsini yükleyemezsiniz ve anahtar kelime araması doğru parçaları bulmak için çok kırılgandır.

OpenClaw kullandıysanız, bunun nasıl işlediğini görmüşsünüzdür. Belleği markdown kontrol noktası dosyaları olarak saklar ve haftalarca günlük kullanımda, bağlam biriktikçe ve sıkıştıkça önceki gerçekler sessizce kaybolur. Depolama oradadır. Getirme (retrieval) orada değildir.

Akıllı getirme olmadan depolama, kataloğu olmayan bir kütüphanedir.

Katman 3: Vektör arama ve çarptığı duvar

Gömmeleri (embeddings) ekleyin. Markdown'ınızı parçalara ayırın (chunk), parçaları gömün, kosinüs benzerliğine göre arama yapın. Artık "veritabanı", "PostgreSQL" ile eşleşir çünkü vektörleri gömme uzayında birbirine yakın yaşar. Eşanlamlı sorunu çözülür.

Sonra yeni bir duvara çarparsınız. Vektör DB'nizdeki şu üç gerçeği düşünün:

1- "Alice, Atlas Projesi'nin teknoloji lideridir"
2- "Atlas Projesi, birincil veri deposu olarak PostgreSQL kullanır"
3- "PostgreSQL kümesi Salı günü bir kesinti yaşadı"

Kullanıcı soruyor: "Alice'in projesi Salı günkü kesintiden etkilendi mi?"

Sorguda Alice ve Salı günkü kesintiden bahsedildiği için vektör araması ilk ve üçüncü gerçekleri yüksek sıraya koyar. Ancak kritik köprü olan "Atlas Projesi, PostgreSQL kullanır" ne Alice'ten ne de Salı'dan bahseder. Bu, bağlantı parçasıdır ve yüzeye çıkmayacak olandır.

Her gerçek, gömme uzayında izole bir noktadır. Onları birbirine bağlayan bağ dokusu vektörler için görünmezdir.

Bu bir uç durum değildir. Gerçek dünya sorularının normal şeklidir. İş bilgisi doğası gereği ilişkiseldir: insanlar ekiplere aittir, ekipler projelere sahiptir, projeler sistemlere bağımlıdır, sistemlerin olayları vardır. İki veya daha fazla adımı geçen herhangi bir soru, düz vektör getirmenin cevaplayamayacağı bir şeydir.

Yetenek matrisi

Her katman bir önceki acıyı düzeltir ancak daha derin bir tanesini ortaya çıkarır:

Tek bir bellek katmanında kalıcılığa, anlamsal anlayışa ve ilişkisel akıl yürütmeye ihtiyacınız var.

Bunu kendiniz oluşturmak, bir vektör veritabanı, bir grafik veritabanı, bir ilişkisel depo, bir varlık çıkarıcı, bir yineleme giderme (deduplication) hattı ve bir kenar ağırlıklandırma sistemini birbirine yapıştırmak anlamına gelir. Bu, tek bir satır ajan mantığı yazmadan önce haftalarca süren bir altyapı çalışmasıdır.

Bu boşluğu temiz bir şekilde dolduran bir çözüm kullanıyorum. Tamamen açık kaynak kodludur, üç depolama paradigmasını da tek bir çatı altında ele alır ve dakikalar içinde çalışır hale getirebilirsiniz. Cognee'den bahsedelim.

Cognee: üç depo, tek motor, dört çağrı

Cognee, ajan belleği için oluşturulmuş açık kaynaklı bir bilgi motorudur. Vektör aramayı bilgi grafikleri (knowledge graphs) ve ilişkisel bir kaynak (provenance) katmanıyla tek bir sistemde birleştirir.

Tüm API yüzeyi dört asenkron çağrıdan oluşur:

1import cognee
2
3await cognee.add("Belgeniz buraya")   # Herhangi bir şeyi içe aktar
4await cognee.cognify()                    # Bilgi grafiği + gömmeler oluştur
5await cognee.memify()                     # Belleği kendi kendine geliştir
6await cognee.search("Sorgunuz")         # Akıl yürüterek getir

Bu dört çağrının arkasında üç depolu bir mimari bulunur.

Neden üç depo da tek depo değil?

Her depo, diğerlerinin yakalayamadığı bir bilgi boyutunu yakalar:

• İlişkisel depo (Relational store) → kaynak (provenance): verinin nereden geldiği, ne zaman alındığı, kimin erişimi olduğu
• Vektör depo (Vector store) → anlambilim (semantics): içeriğin ne anlama geldiği, neye benzediği
• Grafik depo (Graph store) → ilişkiler (relationships): varlıkların nasıl bağlandığı, neyin neye sebep olduğu, kimin kime rapor verdiği

Bunlardan herhangi birini düzleştirirseniz, getirme doğruluğu için önemli olan bilgiyi kaybedersiniz.

Varsayılan yığın SQLite + LanceDB + Kuzu'dur, tamamen gömülü ve dosya tabanlıdır. pip install cognee artı bir LLM API anahtarı ile çalışır hale gelirsiniz.

Docker yok, harici hizmet yok.

Üretim için SQLite'ı Postgres, LanceDB'yi Qdrant/Pinecone/pgvector ve Kuzu'yu Neo4j/FalkorDB/Neptune ile değiştirin.

Her iki durumda da aynı dört çağrılı API.

cognify aslında ne yapar?

cognee.cognify(), ham metni yapılandırılmış, birbirine bağlı bilgiye dönüştüren çok aşamalı bir işlem hattı (pipeline) çalıştırır:

1. Belge sınıflandırması türüne ve alanına göre
2. İzin kontrolü çok kiracılı (multi-tenant) erişim kontrolü için
3. Parça çıkarma paragraf yapısına saygı duyan (sabit boyutlu kesintiler değil)
4. Varlık ve ilişki çıkarma LLM aracılığıyla, içerik hash'leme yoluyla otomatik yineleme giderme ile
5. Özet oluşturma verimli getirme için
6. Çift dizin oluşturma vektör deposuna (gömmeler) ve grafik deposuna (kenarlar)

Yineleme giderme adımı, göründüğünden daha önemlidir. Aynı varlık 50 belge boyunca görünüyorsa, Cognee onu 50 gelen kenarı olan tek bir grafik düğümünde birleştirir. Ajanınız artık "Alice"i 50 farklı yabancı olarak görmez. Ve işlem hattı varsayılan olarak artımlıdır (incremental): yalnızca yeni veya değiştirilmiş dosyalar yeniden işlenir.

Her grafik düğümünün karşılık gelen bir gömmesi vardır. Bu ikili temsil (dual representation) temel numaradır: vektörlerden girin (anlamsal olarak benzer içerik bulun) ve grafikten çıkın (bağlantılı varlıklara giden ilişkileri takip edin) veya tam tersi. Anlamsal aramadan ödün vermeden çok adımlı sorguları mümkün kılan şey budur.

Memify: öğrenen bellek

memify(), Cognee'yi diğer tüm "içe aktar ve ara" araçlarından ayıran şeydir. Grafik üzerinde RL'den ilham alan bir optimizasyon geçişi çalıştırır:

• Güçlendirme iyi getirmeye yol açan faydalı yolların
• Budama dokunulmayan eski düğümlerin
• Otomatik ayarlama kenar ağırlıklarının gerçek kullanıma göre
• Türetilmiş gerçekler ekleme örtük ilişkileri belirleyerek

Bir müşteri destek ajanının grafiği, doğal olarak ürün belgeleri ve para iade politikaları arasındaki yolları güçlendirirken, nadiren sorgulanan İK kenarlarının zayıflamasına izin verir. Grafik zamanla kendi alaka duygusunu geliştirir.

On dört getirme modu

Cognee, 14 arama moduyla birlikte gelir. Gerçekten kullanacağınız olanlar:

Cognee belleği ile gerçek bir ajan oluşturma

İşte Cognee'yi algıla-düşün-harekete geç döngüsüne bağlayan tam kalıp:

1import cognee
2from cognee import SearchType
3
4class CogneeMemoryAgent:
5    """Grafik-vektör melez kalıcı belleğe sahip ajan."""
6
7    def __init__(self, session_id: str = "default"):
8        self.llm_client = OpenAI()
9        self.session_id = session_id
10
11    async def ingest(self, text: str, dataset: str = "main"):
12        await cognee.add(text, dataset)
13        await cognee.cognify([dataset])
14
15    async def recall(self, query: str) -> str:
16        results = await cognee.search(
17            query_text=query,
18            query_type=SearchType.GRAPH_COMPLETION,
19            session_id=self.session_id,
20        )
21        return results[0] if results else ""
22
23    async def chat(self, user_input: str) -> str:
24        context = await self.recall(user_input)
25        messages = [
26            {"role": "system", "content": "Yardımseversin. Bellek bağlamını kullan."},
27            {"role": "system", "content": f"Bellek bağlamı:\n{context}"},
28            {"role": "user", "content": user_input},
29        ]
30        response = self.llm_client.chat.completions.create(
31            model="gpt-4o-mini", messages=messages
32        )
33        reply = response.choices[0].message.content
34        await cognee.add(
35            f"Kullanıcı: {user_input}\nAsistan: {reply}",
36            "conversations"
37        )
38        await cognee.cognify(["conversations"])
39        return reply

Bellek döngüsü: içe aktar, çıkar, depola, getir, yanıtla, tekrar depola. Her tur bilgi grafiğini zenginleştirir ve artımlı işleme, yalnızca yeni içeriği dizine eklemek için ödeme yapacağınız anlamına gelir.

Oturum belleği, zamir çözümlemesini otomatik olarak halleder:

1await cognee.search(query_text="Alice nerede yaşıyor?", session_id="conv_1")
2await cognee.search(query_text="İş olarak ne yapıyor?", session_id="conv_1")
3# "o" oturum bağlamından Alice'e çözümlenir

Çok kiracılılık (Multi-tenancy), veri kümesi başına izinlerle (okuma, yazma, silme, paylaşma) grafik düzeyinde yerleşiktir. Ad alanı ayrımı değil, gerçek grafik düzeyinde izolasyon.

Pratik ileriye giden yol

Bugün bir ajan oluşturuyorsanız, gerçek başlangıç sorusu şudur: "Ajanımın neyi hatırlaması gerekiyor ve ne tür soruları cevaplayacak?"

Sorgularınız yalnızca benzerlik araması gerektiriyorsa ("bunun gibi konuşmaları bul"), yalnızca vektör belleği işe yarar. Sorgular varlık sınırlarını geçtiği anda ("Alice'in projesi Salı günkü kesintiden etkilendi mi?"), grafik geçişine (graph traversal) ihtiyacınız vardır.

Ayrı vektör, grafik ve ilişkisel depoları kendiniz birbirine bağlayabilirsiniz. Bu yola giden ekipler, genellikle kendi kullanımından öğrenmeyen bir bellek katmanı için altyapıya haftalar harcarlar.

Cognee bunu dört API çağrısına indirger. Gömülü varsayılanlar sizi dakikalar içinde çalışır hale getirir. Değiştirilebilir arka uçlar (Postgres, Qdrant, Neo4j), ajan kodunuzu değiştirmeden sizi üretime taşır.

Zeka, yalnızca depolamayı değil, yapıyı gerektirir. Üç depolama paradigması (ilişkisel, vektör, grafik) rakip seçenekler değildir. Aynı bellek sisteminin tamamlayıcı katmanlarıdır. Onlara bu şekilde davranmak, durumsuz bir LLM sarmalayıcısını gerçekten öğrenen bir şeye dönüştürür.

Ajanınızın yarın hatırlamasını istediğiniz, bugün unuttuğu bir sonraki şey nedir? Oradan başlayın.

👉 Cognee'ye GitHub'da göz atın →, yıldız verin ve bir sonraki ajanınıza bağlamayı deneyin.

Dört asenkron çağrı, bir pip install ve çalışıyorsunuz.

Bu kadar!

Okumaktan keyif aldıysanız:

Beni bulun → @akshay_pachaar ✔️

Her gün, Yapay Zeka, Makine Öğrenimi ve vibe coding en iyi uygulamaları hakkında eğitimler ve içgörüler paylaşıyorum.