Bilgi sistemi

atl kullanan bir projede bilginin nasıl düzenlendiği. İki katman: journal (tarih tabanlı tarihsel kayıt) ve wiki (konu tabanlı güncel doğru). Hepsi bu. İki katman. Üzerine ekleme.

Kanonik kuralın kendisi core/rules/knowledge-system.md dosyasında yaşar. Bu sayfa kullanıcıya yönelik özettir.

Ayrı bir memory katmanı yok. v1'in üçü vardı (agent-memory + journal + wiki); ilk ikisi de tarih tabanlı, yalnızca eklemeli ve pratikte yedekliydi; bu yüzden artık tek bir journal/ altında birleşmiştir. "memory"nin uzandığı şey, ajanın kendi bilgi tabanı (children/ dizini) artı kullanıcı-genel katman tarafından karşılanır.

İki katmana bir bakış

Katman	Konum	Amaç	Güncelleme biçimi
Journal	.atl/journal/{YYYY-MM-DD}.md	Tarih tabanlı tarihsel kayıt: ne oldu, neyin işe yaradığı, neyin yaramadığı ve neden. Gün başına bir dosya.	Yalnızca eklemeli
Wiki	.atl/wiki/{topic}.md	Konu tabanlı güncel doğru. ŞU AN doğru olanı yansıtır; eski doğrular eklenmez, değiştirilir.	Yerine yazma / güncelleme

Farklı paradigmalar, farklı amaçlar:

• Journal "zaman içinde ne oldu?" sorusunu yanıtlar (kronolojik anlatı).
• Wiki "şu an ne doğru?" sorusunu yanıtlar (konu tabanlı anlık görüntü).

İkisini de okuyabilirsin; birbirini dışlamazlar. Ama farklı yazılırlar.

Journal — ekle, asla düzenleme

Dosya adı: {YYYY-MM-DD}.md — gün başına bir dosya, o gün ne çalıştıysa hepsi tarafından paylaşılır (v1'in ajan başına _{agent} eki kaldırıldı).

Buraya şunlar girer:

• Olup biteni tarihleyen anlatı: keşifler, kararlar, hata düzeltmeleri, neyin işe yaradığı, neyin yaramadığı.
• Çapraz kesen notlar ("X'e sıradaki dokunan için: …").
• Her drain'in ne ürettiğinin kaydı (yeni wiki sayfaları, yeni ajan bilgisi).
• Kullanıcı onaylı yapısal değişiklikler (yeni beceri / kural / ajan kararları ve reddedilenleri).

Kurallar:

• Yalnızca eklemeli. Mevcut kayıtlar düzenlenmez; yenileri sona eklenir.
• Asla silinmez (tarihsel kayıt).
• *.local.md dosya adı kalıbı .gitignore kapsamındadır — gerçekten özel olan içerik için kullanılır (seyrek).

Journal katmanı, eskiden .atl/agent-memory/ olan şeyin (ajan başına geçmiş) özgün journal katmanıyla (çapraz kesen sinyaller) birleşmiş halidir. Pratikte ikisinin de biçimi aynıydı (tarih + anlatı) ve sıkça birbirine atıf yapıyorlardı; bu yüzden artık tek bir katmandır.

Wiki — yerine yaz, yalnızca güncel doğru

Dosya adı: {topic}.md (kebab-case, sayfa başına bir kavram).

Projenin yaşayan bilgi tabanıdır. Journal'ın (tarihsel kayıt) aksine, wiki güncel doğruyu yansıtır — bir bilgi değiştiğinde sayfa eklenmez, güncellenir.

Kurallar:

• Konuya göre düzenli, tarihe göre değil (kavram başına bir sayfa).
• İçeri aldığın <!-- learning --> işaretçilerinden /drain tarafından yazılır — konu biçimli güncel doğru buraya iner, tarihli anlatı journal'a gider.
• Sayfalar ŞU AN doğru olanı yansıtır — eski bilgi yerine yenisi yazılır.
• Çapraz başvurulu: ilgili sayfalar birbirine bağ verir.
• İçindekiler tablosu, CLAUDE.md üst kısmındaki <!-- wiki:index --> işaretçi bloğudur; /drain tarafından kendiliğinden derlenir, böylece ajanlar sayfaları sıfır maliyetle keşfeder — ayrıca sürdürülen ayrı bir index.md yoktur.

Bilgi nasıl yazılır: öğrenme döngüsü

Journal'ı ya da wiki'yi elle yazmazsın. Bunlar, CLI/Skill sınırı boyunca temizce bölünmüş v2 öğrenme döngüsüyle beslenir:

1. Yakalama (otomatik, deterministik). Bir konuşma sırasında, öğrenme anı geldiğinde Claude sessiz <!-- learning --> işaretçileri düşürür. Kanonik yakalama kuralı core/rules/learning-capture.md dosyasıdır.
2. Kuyruğa alma (CLI). atl tick — atl setup-hooks tarafından UserPromptSubmit hook'una bağlanır — her işaretçiyi ~/.atl/queue.db konumundaki dayanıklı bir bbolt kuyruğuna tam olarak bir kez aktarır (işaretçi-hash tekilleştirmesi). Bir oturum açıldığında atl session-start bekleyen sayıyı yüzeye çıkarır.
3. Drain (Skill, LLM). /drain kuyruğa alınmış maddeleri atl learnings (status / peek / ack) üzerinden okur, her birini wiki'ye (konu doğrusu), journal'a (geçmiş) ya da bir ajanın bilgi tabanına yönlendirir, ardından ack'ler.

Deterministik yarı (yakalama + kuyruğa alma) CLI'dir; yargı yarısı (bir öğrenmenin nereye ait olduğuna karar vermek) /drain becerisidir — CLI o kısmı yapamaz. ack'lenen bir madde kuyruktan silinir, böylece bir daha asla yeniden raporlanamaz: bu işle-sonra-sil tasarımı, v1'in uzun-oturum yeniden-raporlama hata sınıfını yapısal olarak ortadan kaldırır.

Hook'lar kurulu değilse, işaretçiler zararsızdır (görünmez HTML yorumlarıdır) — bunları işlemek için atl tick ve /drain komutlarını elle çalıştır.

Ajanın açılış rutini

Her konuşmanın başında ajan şunları okur (geçerli olduğu durumda):

1. Kendi ajan dosyası — takımdan, proje-yerel kopya üzerinden. agent.md, children/*.md frontmatter'ından kendiliğinden derlenmiş bir Knowledge Base bölümüyle birlikte gelir (bkz. Children + learnings).
2. CLAUDE.md <!-- wiki:index --> bloğu — kendiliğinden yüklenir; bilgi haritasını sıfır maliyetle verir. Ajanlar .atl/wiki/ dizinini doğrudan taramak yerine ilgili wiki sayfalarını bu listeden keşfeder.
3. Yakın tarihli journal kayıtları — görev önceki çalışmayla örtüşüyorsa .atl/journal/ dizininden (varsayılan olarak son 3–5; görev uzun soluklu bir konuya dokunduğunda kapsamı genişlet).
4. Projeye özgü kurallar — varsa .atl/ altında.

Ajan bütün wiki sayfalarını okumaz. Dizini okur (kendiliğinden yüklenir) ve yalnızca görev o alana dokunduğunda ayrıntı sayfalarına olan bağları izler. Bu, bağlamı sıkı tutarken keşfedilebilirliği korur.

Erişim — her istemde bilgiye danışmak

Wiki dizinini konuşmanın başında bir kez okumak yeterli değildir. Konular kayar ve önündeki istem için önemli olan sayfa, açılış taramasının atladığı bir sayfa olabilir — ya da 60 sayfalık bir dizinde başlığının tek başına ilgisini ele vermediği bir sayfa. Bu yüzden atl bilgi katmanına her istemde de danışır.

Kanca (hook)

UserPromptSubmit kancasına bağlı atl retrieve, projenin bilgi sayfalarını her isteme göre sıralar ve en iyi eşleşmeleri bağlam olarak sunar — yazma tarafı yakalama + /drain olan döngünün okuma tarafı. Sıralama hibrittir:

• Sözcüksel (BM25) tam tanımlayıcıları yakalar — bir fonksiyon adı, bir bayrak, bir atl#140 — ki semantik model bunları bulanıklaştırır.
• Semantik — küçük bir yerel gömme (embedding) modeli — anahtar-kelime aramasının kaçırdığı kavramsal ve eşanlamlı eşleşmeleri yakalar.
• İkisi tek bir top-k'ye RRF ile birleştirilir.

Fail-open'dır: eksik bir dizin, olmayan bir model ya da herhangi bir hata hiçbir şey yazdırmaz ve istemi asla bloklamaz veya geciktirmez.

Yerel model — harici servis yok

Semantik yarı, küçük bir ONNX modelini (paraphrase-multilingual-MiniLM-L12-v2, ~135 MB) tamamen yerelde, saf-Go bir çalışma zamanıyla çalıştırır. İlk kullanımda bir kez indirilir (sha256 doğrulamalı), ~/.atl/models altına konur, ikiliye (binary) gömülmez ve asla harici bir servise çağrı yapmaz — istemleriniz ve bilginiz makineden çıkmaz. Bu, size cevap veren ikinci bir model değil, bir metin→vektör aracıdır; ajan hâlâ Claude'dur. Arka plan dizinlemesini kapatmak için ATL_NO_RETRIEVE_INDEX ayarlayın.

Model bilinçli olarak çok dillidir. Önceki yalnızca-İngilizce model, İngilizce olmayan bir istemde hiç sinyal üretmiyordu — "daha zayıf" değil, sıfır: başka bir dildeki konu-içi bir soru, konu-dışı İngilizce bir sorunun altında puan alıyordu; yani sıralayıcının iki yarısı birden çöküyor ve İngilizce çalışmayan biri için getirme fiilen kapalı oluyordu.

Model değişince bir kerelik yeniden derleme

Bir dizinin vektörleri yalnızca aynı modelden gelen vektörlerle karşılaştırılabilir; bu yüzden gömme modelini değiştirmek saklı bütün dizinleri geçersiz kılar. Böyle bir yükseltmeden sonra her projedeki ilk oturum, o projenin dizinini arka planda sıfırdan yeniden derler — küçük bir korpusta dakikalar, büyükte daha uzun. Başlarken kendini duyurur, çekirdeklerinizin yarısıyla sınırlıdır ve ATL_NO_RETRIEVE_INDEX=1 ile atlanır. Bitene kadar getirme yalnızca sessiz kalır.

İngilizce olmayan istemler, arama öncesi çevrilir

Getirmenin iki yarısı var ve İngilizce dışında farklı biçimde başarısız oluyorlar. Anlamsal yarı çok dillidir ve çalışır. Sözcüksel yarı ise tam kelime eşler, yani bilgi tabanınızın dilinde olmayan bir sorgu hiçbir sayfayla ortak simge taşımaz ve matematiksel olarak sıfır alır — getirme iki yarı yerine tek yarıyla koşar. Sabit bir cevap anahtarına karşı ölçüldü: İngilizce sorularda %75, aynı soruların Türkçesinde %25; anlamsal yarı ise iki dilde birebir aynı puanı alıyor.

Bu yüzden sözcüksel yarı hiçbir şey döndürmediğinde ATL sorguyu İngilizce olarak yeniden yazar ve aramayı tekrarlar. Teknik tanımlayıcılar — dosya adları, komutlar, bayraklar, semboller — olduğu gibi korunur; çünkü sözcüksel yarının en iyi eşlediği şey tam olarak onlardır.

Bunun kendi kimlik bilgisine ihtiyacı var: bir oturumun girişi Claude Code'un kendi sürecinde tutulur ve başlattığı araçlara görünmez; yani token'ın, bir kancanın okuyabileceği bir yerde yeniden oluşturulması gerekir. Akla ilk gelen yerlerin ikisi bunu yapamaz — üstüne zaman harcamadan önce hangileri olduğunu bilmekte fayda var.

Çalışmayan iki yer

• ~/.claude/settings.json içindeki env bloğu. Claude Code bu değişkenleri kendi sürecinde tutar ve küçük bir kümesini başlattığı her araçtan esirger — macOS'ta, ana süreç ile bir araç alt süreci arasındaki değişken adları karşılaştırılarak ölçüldü: tam olarak beşi esirgeniyor ve CLAUDE_CODE_OAUTH_TOKEN bunlardan biri. Ortam değişkeni tanımlamak için belgelenmiş yer, bu değişkeni bir kancaya ulaştırmaktan yapısal olarak aciz.
• ~/.zshrc. zsh bu dosyayı yalnızca etkileşimli kabuklar için okur; bir kanca ise etkileşimli değildir.

İkisi de işe yaramış gibi görünür ve sessizce hiçbir şey yapmaz.

Çalışan iki yer var. claude setup-token çalıştırın, sonra yazdırdığı token'ı şu ikisinden birine koyun:

• ~/.atl/claude-token — yalnızca token'ı tutan, başka hiçbir şey içermeyen düz bir dosya. Yalnızca sahibine açık tutun (chmod 600); daha genişse atl doctor sizin için daraltır ve aynı kontrol her oturum başında da koşar.
• ~/.zshenv içinden dışa aktarılan CLAUDE_CODE_OAUTH_TOKEN — zsh bu dosyayı etkileşimli olsun olmasın her çağrıda okur, böylece değer, esirgemeden sonra alt sürecin içinde yeniden oluşur. (ANTHROPIC_API_KEY de aynı şekilde okunur.)

Önce ortam, sonra dosya okunur; yani açıkça dışa aktardığınız bir değer, dosyada duran değere her zaman baskın gelir.

Kimlik bilgisi olmadan hiçbir şey bozulmaz — oturum başındaki bilgilendirme neyin eksik olduğunu söyler, getirme tek yarıyla çalışmaya devam eder. Yapılandırılmış bir kimlik bilgisi sonradan çalışmaz hale gelirse, oturum başında bu kez farklı bir bilgilendirme çıkar ve gerçekte kullandığınız kaynağı adıyla söyler; yani tahmin etmek yerine ya dosyayı ya da ~/.zshenv'i işaret eder. Çeviri ayrıca uçtan uca hataya-açıktır: eksik kimlik bilgisi, zaman aşımı ya da sorguya benzemeyen bir cevap, hepsi sizin özgün kelimelerinizle aramaya geri döner.

Tetikleyici bir dil denetimi değil, sözcüksel yarının boş dönmesidir. Yani korpusun kapsadığı bir konudaki İngilizce istem çeviriciye hiç uğramaz; kapsamadığı bir konudaki istem uğrar, kendi sözcüklerini geri alır ve bu cevap atılır — boşa giden bir alt süreç, ama asla daha kötü bir arama değil.

Otomatik, artımlı, arka planda

Bir drain bilgi tabanını değiştirdiğinde dizin kendini yeniden kurar. atl session-start korpusun değiştiğini fark eder ve derlemeyi arka planda (ayrık/detached) başlatır, böylece oturumu asla bloklamaz; ve derleme artımlıdır — yalnızca metni gerçekten değişen sayfalar yeniden gömülür, dolayısıyla rutin bir drain saniyeler içinde tazelenir. Bu oturumda drain ettiğiniz, bir sonraki oturumda erişilebilir. (atl work dispatch altında, worktree başına worker'lar yeniden-derleme fırtınasını önlemek için otomatik derlemeyi atlar.)

Araç — soruyu istem değil, durumun kendisi doğurduğunda

Kanca, kullanıcının cümlesini yanıtlar. Oysa bir ajanın kayıttan ihtiyaç duyduğu şeyin çoğunu kendi durumu doğurur; ve bir talimat — "sürümü çıkar", "merge et" — bir sıralayıcının eşleştirebileceği hiçbir soru taşımaz.

/consult bu boşluğu kapatır: arama sorgusunu, yapmak üzere olduğu şeyden yola çıkarak ajanın kendisi yazar. Bir şeyin nasıl çalıştığını iddia etmek üzereyken, bir tasarım önerirken ya da seçenekler arasında seçim yaparken, kurallarını doğrulamadığı bir dosyayı düzenlerken, tanıdık gelen bir hataya çarptığında, veya bir prosedürü olan işi adlandıran bir talimatı uygularken devreye girer.

İki özelliği, kancayı beklemek yerine onu çağırmayı değerli kılar. Sorgu, sürekli-yüklü wiki:index'ten türetilir; yani kullanıcının başka sözcüklerle anlatımı yerine korpusun kendi söz dağarcığıyla yazılır — ve o dizin İngilizce olduğu için, orada doğan bir sorgu İngilizce korpusu hem sözcüksel hem anlamsal kolda arar. Bir de açık bir kapatma anahtarı vardır: bu durumlardan hiçbiri geçerli değilse, danışma. Her turda ateşleyen bir kanal okunmaz hale gelir.

Disiplin

Erişim yargıyı tetikler, onun yerine geçmez. Tek değil, üç alet: kanca yapacağınız işle konusu eşleşen bir sayfa sunduğunda cevaplamadan önce onu okuyun; soruyu kendi durumunuz doğurduğunda /consult kullanın; ve konuşma konu değiştirdiğinde, kancanın sıralamamış olabileceği bir sayfa için sürekli-yüklü wiki:index'i yeniden tarayın — dizin sıfır maliyetle bağlamdadır. Kaynak kural: core/rules/knowledge-system.md.

Elle kontrol

Derleme normalde kendi kendine çalışır, ama elle de sürebilirsiniz:

• atl retrieve index — bu projenin dizinini şimdi (artımlı) yeniden kur.
• atl retrieve index --lexical — yalnızca BM25 dizini kur (model yok, çevrimdışı).
• atl retrieve warm — modeli indir ve boru hattının yüklendiğini kanıtla.

Neden iki katman, üç değil?

v1 üç katman tanımlıyordu: memory (proje başına, ajan başına, yalnızca eklemeli geçmiş), journal (proje başına, ajanlar arası sinyaller, yalnızca eklemeli) ve wiki (proje başına, konu tabanlı, yerine yazma / güncelleme).

İlk ikisi de tarih tabanlı, yalnızca eklemeli ve anlatı biçimliydi. Her çalışma alanında birbirine atıfta bulunarak ya da aynı olayları yedekli olarak yakalayarak son buluyorlardı. "Ajanın kendine özel hafızası vs. başkalarına yayın" ayrımı asla zorlanmadı — herkes iki katmanı da okuyabiliyordu.

Tek bir journal/ katmanında birleştirildiler çünkü:

• Aynı biçim → anlamsal ayrım yok.
• Aynı kitle (tüm ajanlar her ikisini de okur).
• Aynı yazma deseni (tarihe göre eklemeli).
• Bölünme, farklı içerik üretmeden zihinsel yük getiriyordu ("bu benim için mi yoksa başkaları için mi?").

Birleşen katmanın adı yalnızca journal/. Wiki ayrı kalır çünkü paradigması (konu tabanlı güncel doğru) journal'ınkinden (tarih tabanlı geçmiş) gerçekten farklıdır.

Ajan tarafındaki yansıma: iki eksen

Aynı güncel-doğru-vs-geçmiş bölünmesi takım tarafında da vardır; tek bir projeye sıkıştırılmak yerine ajanla birlikte taşınır. Bu iki eksen verir:

• güncel-doğru vs geçmiş — wiki + bir ajanın children/ dizini (güncel) vs journal (geçmiş).
• proje vs ajan — .atl/ (yalnızca bu proje) vs bir ajanın children/ dizini (ajanın kurulu olduğu her proje).

Somut olarak:

• Ajan çocuk dosyaları (ajanın dizinindeki children/{topic}.md) wiki'nin ajan tarafındaki karşılığıdır — konu tabanlı, yerine yazma / güncelleme, ajan için projeler arası alan bilgisi. (Beceriler bilgi deposu değil, yordamdır — böyle bir dizinleri yoktur.)

Her çocuk dosyada bir knowledge-base-summary: frontmatter alanı bulunur ve bu alan agent.md'nin Knowledge Base bölümüne kendiliğinden derlenir. Tüm desen için bkz. Children + learnings.

İlgili

• /drain — öğrenme kuyruğunu journal kayıtlarına ve wiki sayfalarına katlar.
• atl learnings — /drain'in sürdüğü deterministik kuyruk tesisatı (status / peek / ack).
• atl tick — yakalanan işaretçileri kuyruğa aktarır (döngünün yakalama yarısı).
• Children + learnings — journal + wiki'nin ajan tarafındaki yansıması.
• Backlog & tasks — ertelenen işler (backlog.md) + etkin niyet (tasks.md). Bunlar karar durumudur — journal + wiki'nin bir kardeşi, üçüncü bir bilgi katmanı değil.
• Kanonik kural: core/rules/knowledge-system.md.