AKB - İnsanların ve yapay zekanın birlikte okuyup yazdığı ekip bilgi altyapısı, üstelik yetki yönetimiyle birlikte

Merhaba. İçinde bulunduğum Dnotitia’da, yapay zeka ajanlarının çalışma sırasında doğrudan okuyup yazdığı bir ekip bilgi tabanı olan AKB(Agent Knowledge Base) geliştiriyoruz.

Neden yaptık?

İnsanların kullandığı wikiler (Confluence·Notion) zaten çok. Ajan tarafında da benzer araçlar var. mem0, konuşmalardan çıkardığı içeriği kişisel hafıza olarak biriktiriyor; LLM Wiki ise ajanların okuyup yazabildiği kişisel bir bilgi tabanı oluşturuyor. Ancak bunlar çoğunlukla bireysel kullanımda kalıyor; birden fazla kişinin birlikte okuyup yazabileceği ortak bir temel olarak tasarlandıklarını söylemek zor.

Google’ın Open Knowledge Format(OKF) yaklaşımı da benzer bir soruna işaret ediyor. Bilgi wiki, katalog ve kodun farklı yerlerine dağılmış olduğundan ajanların her seferinde bağlamı yeniden toplaması gerekiyor; yani ihtiyaç duyulan şey kapalı bir başka servis değil, farklı araçların birlikte okuyup yazabileceği ortak bir format. OKF’nin önerdiği format basit: Markdown dosyalarını bir klasörde topluyor, her dosyanın en üstüne birkaç satır YAML ekliyorsunuz. Sonrasında bu formatın kim tarafından nasıl üretileceği, okunacağı ve genişletileceği her uygulamanın tercihine bırakılıyor.

AKB ne yapıyor?

AKB, bu formatı ekiplerin ortak bilgi temeli olarak hayata geçiren bir altyapı. vault, OKF ile uyumlu bir Markdown paketi olsa da sadece arayıp okunabilen bir indeks değil; insanların ve ajanların aynı kaynağı birlikte okuyup yazdığı paylaşımlı bir depo. İnsanlar web UI üzerinden, ajanlar ise MCP üzerinden erişiyor. Ama üzerinde çalışılan asıl kaynak tek. Ajan yazmaya başladığında “neyin nasıl değiştiği” de önem kazanıyor. vault bir Git deposu olduğu için tüm değişiklikler commit ve diff olarak kaydediliyor.

İçerdiği şey de yalnızca belgeler değil. OKF, bilginin Markdown ile yazıldığı bir format sunuyorsa, AKB aynı vault içine sorgulanabilir tablolar ve dosya depolamayı ekliyor; belgeleri de bir bilgi grafiğiyle birbirine bağlıyor. Belgeler, insanların okuyacağı ve ajanların referans alacağı bilgi olarak kalırken; liste, durum ve istatistik gibi yapılandırılmış şekilde ele alınması gereken veriler ayrı tablolarda saklanıp sorgulanabiliyor. Bu sayede yalnızca insanlara yönelik wiki ya da aramayla zor olan işler, örneğin AKB’yi veri ve değişiklik geçmişi katmanı olarak kullanıp bunun üstünde iş uygulamaları geliştirmek ve işletmek de mümkün oluyor.

Ama ekiplerin ortak bilgi tabanı olmak için yalnızca veri ve geçmiş yetmez. OKF gibi formatlar kimin neyi görebileceğini tanımlamaz. AKB’de en çok emek verdiğimiz kısım da bu yetkilendirme. Ajanlar, kendi token’ını veren kişi olarak kimlik doğrular ve o kişinin vault yetkilerini aynen devralır. İnsanlara uygulanan erişim sınırları aynen ajanlara da uygulanır. Bu sınırlar iki katmanda zorunlu kılınır. Belge, dosya ve arama gibi genel erişimler uygulama katmanında yetki kontrolünden geçer. Tablolarda toplama ve analiz SQL’i çalıştıran yol ise veritabanı katmanında bir kez daha engellenir. Sorgular kullanıcının PostgreSQL rolüyle çalıştırılan PG ACL yöntemiyle işlendiği için, yetki dışındaki bir vault’a referans verilirse uygulama değil PostgreSQL bunu doğrudan reddeder.

Ekibimiz, AKB altyapısının üstünde issue tracker olan reef’i çalıştırarak kullanıyor. Bir issue, hem vault içindeki bir Markdown belgesi hem de sorgulanabilir bir tablo satırı. Geliştiriciler Claude Code·Codex gibi kodlama ajanlarıyla, PM’ler ise reef’in özel ajanıyla vault içindeki aynı belgeye bakarak çalışıyor. PM’ler geliştiricilere özel spesifikasyon sözdizimini bilmeden de AKB’de biriken bağlamı temel alarak issue oluşturabiliyor; geliştiriciler ise dağınık arka plan açıklamalarını yeniden kazmak yerine bunları MCP üzerinden alıp geliştirme yapabiliyor. Ekip içinde geliştirici ve PM arasındaki teknik ve dil bariyerlerinin ajanlar aracılığıyla azaldığını doğrudan hissediyoruz.

Hemen göz atın

Kurulum yapmadan hemen incelemek isterseniz herkese açık demoya (akb-demo.agent.seahorse.dnotitia.ai) gidebilirsiniz. (Kayıt gerekiyor ama demo amaçlı olduğu için tüm veriler her hafta sıfırlanıyor.)

Kendiniz çalıştırmak isterseniz aşağıdaki gibi Docker compose ile ayağa kaldırıp localhost:3000 üzerinden erişebilirsiniz. Embedding anahtarı olmasa bile anahtar kelime (BM25) araması çalışır.

git clone https://github.com/dnotitia/akb && cd akb  
cp config/app.yaml.example   config/app.yaml  
cp config/secret.yaml.example config/secret.yaml  
docker compose up -d  

Hâlâ eksik yönleri çok. Bir kez çalıştırıp denerseniz, hata ya da garip bulduğunuz noktaları ve genel izlenimlerinizi yorumlarda rahatça paylaşırsanız memnun oluruz.