Self-Hosted AI Memory: TeamAlpha Honcho ile Kalıcı Agent Hafızası

Son güncelleme: Temmuz 2026

Bir geliştirici ekibinde aynı konuyu tekrar tekrar anlatmak çok tanıdık bir problem: proje hangi portta çalışıyor, deploy akışı nasıl, test komutları ne, müşteri için alınan karar neydi, bu repository'de hangi dosyaya dokunulmamalı... Her yeni AI oturumunda bu bilgileri tekrar yazmak hem zaman hem token tüketiyor.

TeamAlpha tarafında bu problemi çözmek için kendi sunucumuzda çalışan, self-hosted bir Honcho kurulumu kullanıyoruz. Honcho, VS Code Copilot, Claude Code, Codex, Cursor ve benzeri coding agent'lara proje bazlı kalıcı hafıza kazandıran bir MCP servisidir. Amaç agent'ın her oturuma sıfırdan başlamaması; önceki kararları, kullanıcı tercihlerini ve proje bağlamını güvenli şekilde hatırlayabilmesidir.

Bu yazıda Honcho'nun ne işe yaradığını, TeamAlpha'daki mimarisini, workspace/peer modelini, agent'larla nasıl entegre edildiğini ve production kullanımında nelere dikkat ettiğimizi anlatıyoruz.

Hızlı Bakış

Ne anlatıyoruz: Coding agent'lar için self-hosted kalıcı hafıza altyapısı

Kullandığımız servis: Honcho, MCP, REST API, PostgreSQL, Redis, Docker Compose, Nginx

Canlı endpoint: https://memory.example.com/memory-hub

Ana fikir: Her proje ayrı bir workspace, her kullanıcı veya agent ayrı bir peer olarak modelleniyor

Güvenlik modeli: Workspace-scoped JWT token'lar ile proje bazlı izolasyon

Pratik içerik: VS Code, Claude Code, Claude Desktop, Codex ve Cursor için bağlantı örnekleri

Production notu: Servis TeamAlpha'nın kendi sunucusunda çalışıyor; veriler üçüncü taraf bir SaaS hafıza servisinde tutulmuyor

Neden AI Agent Hafızası Önemli?

Modern coding agent'lar güçlü ama çoğu oturum bazlı çalışır. Bugün anlattığınız mimari karar, yarın yeni bir oturum açıldığında modelin bağlamında olmayabilir. Bunu çözmenin klasik yolu uzun prompt dosyaları, README notları veya her seferinde elle bağlam vermektir.

Bu yaklaşımın üç problemi var:

• Her oturumda aynı açıklamalar tekrar edilir • Context window hızlı dolar • Proje kararları ile kişisel çalışma tercihleri birbirine karışır

Honcho burada ayrı bir hafıza katmanı gibi davranır. Agent konuşma sırasında Honcho'ya mesajları kaydeder. Arka planda çalışan deriver süreci bu konuşmalardan kalıcı sonuçlar, özetler ve semantik temsiller çıkarır. Sonraki oturumda agent, "bu kullanıcı ve bu proje hakkında ne bilmeliyim?" diye sorabilir ve ham sohbet geçmişi yerine damıtılmış bir cevap alır.

Honcho Nedir?

Honcho, AI agent'lar için tasarlanmış bir memory service'tir. Bizim kullanımımızda iki ana arayüz sunar:

• MCP endpoint: Agent araçları buradan bağlanır • REST API: Health check, workspace, key ve yönetim işlemleri için kullanılır

TeamAlpha production endpoint'i:

https://memory.example.com/memory-hub

Burada önemli bir ayrıntı var: Tam /memory-hub path'i MCP endpoint'idir. REST çağrıları ise alt path'leri kullanır:

https://memory.example.com/memory-hub/health
https://memory.example.com/memory-hub/v3/...

Agent konfigürasyonunda MCP URL'sinin sonuna ekstra / koymamak gerekir.

Temel Kavramlar

Workspace

Workspace, hafıza izolasyon sınırıdır. Pratikte bir proje veya kullanım alanı demektir.

Örnekler:

• private-user-a • private-user-b • honcho_test • crm-backend • mobile-app

Bir workspace'te oluşan hafıza başka workspace'e karışmaz. Böylece bir müşteri projesinin bağlamı başka bir projede görünmez.

Peer

Peer, workspace içindeki katılımcıdır. Bu bir insan, bir AI assistant veya proje varlığı olabilir.

Örnek peer'ler:

• user-a • Assistant • TEAMALPHA-HONCHO

Bu model sayesinde Honcho sadece "sohbet geçmişi" tutmaz; kimin hakkında hangi bilginin öğrenildiğini de ayırabilir. Kullanıcı tercihleri kullanıcı peer'i altında, proje kararları proje peer'i altında tutulabilir.

Session

Session, belirli bir konuşma veya çalışma oturumudur. Agent oturum başında session oluşturur, ilgili peer'leri session'a ekler ve konuşma boyunca mesajları buraya kaydeder.

Conclusion

Conclusion, ham mesajlardan çıkarılan kalıcı bilgidir. Örneğin:

• "Bu projede Nginx path prefix'i /memory-hub olarak korunmalı" • "Kullanıcı kısa ve uygulanabilir teknik cevapları tercih ediyor" • "Admin UI sadece allowlist edilen Docker Compose servislerinin loglarını göstermeli"

Agent'ın sonraki oturumda ihtiyaç duyduğu şey genellikle ham mesaj değil, bu tür sonuçlardır.

TeamAlpha Honcho Mimarisi

Production kurulum Docker Compose ile çalışır. Nginx dış dünyadan gelen HTTPS trafiğini ilgili container'a yönlendirir.

VS Code / Codex / Claude Code / Cursor
              |
              | MCP over HTTPS + workspace JWT
              v
      Nginx: /memory-hub
              |
              v
       Honcho MCP service :8787
              |
              | internal REST
              v
       Honcho API service :8000
          |              |
          v              v
     PostgreSQL        Redis
          ^
          |
       Deriver
          |
          v
  Primary LLM endpoint / OpenAI fallback

Servisler:

• api: Honcho REST API • mcp: MCP istemcilerinin bağlandığı servis • deriver: Hafıza çıkarımı, özetleme ve temsil üretimi yapan arka plan worker'ı • database: PostgreSQL ve pgvector ile kalıcı veri deposu • redis: Cache ve koordinasyon katmanı • admin-ui: TeamAlpha'ya özel yönetim arayüzü

Güvenlik için uygulama portları host üzerinde 127.0.0.1 adresine bound edilir. Dış erişim yalnızca Nginx üzerinden HTTPS ile yapılır.

Model Akışı: Agent Cevabı Değil, Hafıza İşleme

Honcho, Copilot veya Claude'un yerine geçen bir coding assistant değildir. Kod yazma, dosya düzenleme veya problem çözme işini yine kullandığınız agent yapar. Honcho'nun rolü hafızayı işlemek ve geri çağırmaktır.

TeamAlpha kurulumunda model sorumlulukları şöyle ayrılır:

• Primary LLM endpoint: Normal generative memory işleri için birincil modeldir • OpenAI generation fallback: Primary LLM endpoint isteği başarısız olursa fallback olarak kullanılır • OpenAI text-embedding-3-small: Mesajları ve hafıza kayıtlarını semantik arama için vektörlere dönüştürür • Deriver: Hangi hafıza işinin ne zaman çalışacağını yönetir • PostgreSQL + pgvector: Workspace, peer, session, message, conclusion ve embedding kayıtlarını saklar • Redis: Koordinasyon ve cache için kullanılır

Bu ayrım maliyet takibi açısından önemli. Honcho'nun backend model kullanımı, Copilot/Claude/Codex'in kendi token tüketiminden ayrıdır. Gerçek faydayı ölçerken ikisini birlikte değerlendirmek gerekir.

Agent Entegrasyonu Nasıl Çalışır?

Bir coding agent'ın Honcho'yu verimli kullanması için sadece MCP bağlantısı yetmez. Agent'a ne zaman session açacağını, ne zaman hafıza sorgulayacağını ve konuşmayı nasıl kaydedeceğini söyleyen kısa bir talimat da gerekir.

Tipik akış:

1. Oturum başında benzersiz bir session ID oluştur
2. Kullanıcı, Assistant ve proje peer'lerini oluştur veya getir
3. Peer'leri session'a ekle
4. İlk cevap öncesinde ilgili geçmiş tercihleri ve proje kararlarını Honcho'ya sor
5. Kullanıcı ve assistant mesajlarını konuşma sonunda session'a kaydet
6. Kalıcı bilgi varsa conclusion olarak çıkarılmasına izin ver

Bu akış sayesinde agent her oturumda şu tarz sorulara cevap alabilir:

Bu kullanıcı nasıl çalışmayı tercih ediyor?
Bu repository için daha önce alınmış deployment kararları neler?
Bu projede dokunulmaması gereken production sınırları var mı?
Geçen oturumda hangi test komutunun çalıştığı doğrulanmıştı?

Client Konfigürasyon Örnekleri

Aşağıdaki örneklerde <your-token>, <your-name> ve <your-workspace-id> alanları admin tarafından verilen değerlerle değiştirilir.

VS Code Copilot Chat

Proje kökünde .vscode/mcp.json:

{
  "servers": {
    "honcho": {
      "type": "http",
      "url": "https://memory.example.com/memory-hub",
      "headers": {
        "Authorization": "Bearer <your-token>",
        "X-Honcho-User-Name": "<your-name>",
        "X-Honcho-Workspace-ID": "<your-workspace-id>"
      }
    }
  }
}

Claude Code

claude mcp add honcho \
  --transport http \
  --url "https://memory.example.com/memory-hub" \
  --header "Authorization: Bearer <your-token>" \
  --header "X-Honcho-User-Name: <your-name>" \
  --header "X-Honcho-Workspace-ID: <your-workspace-id>"

Codex CLI

~/.codex/config.toml:

[mcp_servers.honcho]
command = "npx"
args = [
  "mcp-remote",
  "https://memory.example.com/memory-hub",
  "--header", "Authorization:Bearer <your-token>",
  "--header", "X-Honcho-User-Name:<your-name>",
  "--header", "X-Honcho-Workspace-ID:<your-workspace-id>"
]

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "honcho": {
      "url": "https://memory.example.com/memory-hub",
      "headers": {
        "Authorization": "Bearer <your-token>",
        "X-Honcho-User-Name": "<your-name>",
        "X-Honcho-Workspace-ID": "<your-workspace-id>"
      }
    }
  }
}

Admin Web UI

TeamAlpha kurulumunda operasyonu kolaylaştırmak için ayrı bir Admin Web UI da bulunur:

https://memory.example.com/memory-hub-admin/

Bu arayüzün amacı günlük yönetim işlerini SSH ve manuel curl komutlarına bağımlı olmadan yapmak:

• Dashboard üzerinden workspace, token ve kullanım özetlerini görmek • Workspace oluşturmak ve listelemek • Workspace-scoped token üretmek • Token metadata kayıtlarını fingerprint olarak takip etmek • Mesaj token tüketimini incelemek • Honcho Compose servislerinin durumunu, CPU/memory örneklerini ve redacted loglarını görmek

Güvenlik açısından Admin UI raw token saklamaz. Üretilen token'ın sadece metadata'sı ve SHA-256 fingerprint'i tutulur. AUTH_JWT_SECRET browser'a veya loglara yazdırılmaz; sadece server-side token üretimi için kullanılır.

Güvenlik Modeli

Production ortamda AUTH_USE_AUTH=true açıktır ve erişim JWT ile yapılır.

Temel prensipler:

• Her kullanıcıya workspace-scoped token verilir • Admin token sadece operasyonel işlemler için kullanılır • End user hiçbir zaman root secret veya admin token görmez • Token'lar parola gibi saklanır • Workspace izolasyonu proje sınırı olarak kabul edilir • Database ve Redis public interface'e açılmaz

Mevcut upstream Honcho sürümünde per-key revoke endpoint'i olmadığı için offboarding stratejisi operasyonel kayıt, düzenli rotasyon ve gerekirse AUTH_JWT_SECRET rotasyonuna dayanır. Bu yüzden kimin hangi workspace için ne zaman token aldığı ayrıca takip edilmelidir.

Production Tavsiyeleri

1. URL Prefix'i Sabit Tutun

TeamAlpha kurulumunda public prefix /memory-hub olarak belirlenmiştir. Bu değer Nginx, MCP client konfigürasyonları ve dokümantasyonlarda aynı kalmalıdır. Kısmi değişiklikler sessiz entegrasyon hatalarına yol açar.

2. Nginx'te Sadece Kendi Location Bloğunuza Dokunun

memory.example.com paylaşımlı production host'tur. Aynı Nginx config dosyasında başka uygulamalara ait location blokları da bulunur. Honcho operasyonunda yalnızca /memory-hub/ ve Admin UI için ilgili bloklar yönetilmelidir.

3. Docker Komutlarını Compose Scope'unda Tutun

Host üzerinde başka servisler de çalışır. Bu nedenle Docker işlemleri /opt/memory-hub içinden ve sadece bu projenin Compose servislerine yönelik yapılmalıdır. Host-wide prune, toplu container restart veya başka projelerin volume/network işlemleri yapılmamalıdır.

4. Health Check'i Deploy Sonrası Zorunlu Yapın

Her deploy sonrası en basit doğrulama:

curl -i https://memory.example.com/memory-hub/health

Bu endpoint başarılı dönmeden deploy tamamlanmış kabul edilmemelidir.

5. Hafıza Faydasını Ölçün

Kalıcı hafıza sadece teknik olarak çalıştığında değil, agent'ın daha az tekrar soru sormasını ve daha az bağlam tüketmesini sağladığında değerlidir. Bu yüzden TeamAlpha dokümantasyonunda 3 oturumlu A/B test prosedürü bulunur: Honcho açık ve kapalı senaryolarda client-side token tüketimi ile Honcho backend model maliyeti birlikte ölçülür.

Sık Karşılaşılan Sorunlar

MCP araçları görünmüyor

Client tamamen yeniden başlatılmamış olabilir. VS Code için window reload, Claude Desktop için uygulamayı tamamen kapatıp açmak gerekir.

401 veya authorization hatası alıyorum

Token yanlış, eksik veya artık geçerli olmayabilir. Token'ı chat veya ticket içinde paylaşmadan admin'den kontrol istenmelidir.

Hafıza boş görünüyor

Yeni workspace'lerde bu normaldir. Honcho'nun anlamlı sonuçlar çıkarabilmesi için birkaç gerçek çalışma oturumu gerekir.

Başka projenin bilgisi geliyormuş gibi duruyor

Muhtemelen yanlış X-Honcho-Workspace-ID kullanılıyordur. Workspace ID client konfigürasyonunda kontrol edilmelidir.

Codex veya Claude Desktop'ta npx bulunamıyor

Bu istemciler HTTP MCP bağlantısını mcp-remote ile bridge edebilir. Bunun için Node.js ve npx kullanılabilir olmalıdır.

Ne Zaman Kullanılır?

Honcho özellikle şu durumlarda faydalıdır:

• Uzun ömürlü yazılım projeleri • Birden fazla AI coding agent kullanılan ekipler • Deploy, test ve operasyon kuralları sık hatırlatılması gereken repository'ler • Kullanıcı tercihleri ve proje kararları zamanla biriken işler • Context window maliyetinin önemli olduğu yoğun geliştirme akışları • Verinin self-hosted kalmasının istendiği kurum içi kullanım senaryoları

Kısa süreli tek seferlik işler için Honcho zorunlu değildir. Asıl değer, aynı proje üzerinde günler veya haftalar boyunca tekrar eden agent etkileşimlerinde ortaya çıkar.

Önemli Çıkarımlar

Kalıcı hafıza ayrı bir altyapı katmanı olmalı: Prompt dosyaları faydalı ama dinamik hafıza için tek başına yeterli değil.

Workspace izolasyonu kritik: Her proje kendi hafıza sınırına sahip olmalı.

Agent'a kullanım talimatı vermek şart: MCP bağlantısı tek başına agent'ın doğru hafıza akışını izlemesini garanti etmez.

Self-hosted yaklaşım veri kontrolü sağlar: Hafıza kayıtları TeamAlpha'nın kendi sunucusunda tutulur.

Operasyonel disiplin gerekir: Token kayıtları, secret rotasyonu, health check ve yedekleme süreçleri net olmalıdır.

Fayda ölçülmelidir: Honcho'nun amacı sadece "hatırlamak" değil; tekrar açıklamayı, context tüketimini ve agent sürtünmesini azaltmaktır.

Öğrenme ve Uygulama Yol Haritası

Hafta 1: Temel kurulum ve ilk bağlantı

• Workspace ve token oluştur • VS Code veya Claude Code ile MCP bağlantısını test et • Agent instruction dosyasına Honcho kullanım akışını ekle

Hafta 2: Gerçek proje kullanımı

• Günlük çalışma oturumlarında mesajların kaydedildiğini doğrula • Agent'a proje kararlarını ve kullanıcı tercihlerini sordur • Yanlış veya gereksiz hafıza davranışlarını gözlemle

Hafta 3: Ekip ölçeği

• Her geliştirici için private workspace oluştur • Paylaşımlı test workspace'i ile ortak senaryoları dene • Token metadata ve rotasyon kayıtlarını düzenli tut

Hafta 4: Değer testi

• Honcho açık/kapalı A/B oturumları çalıştır • Client token tüketimini karşılaştır • Honcho backend model maliyetini hesaba kat • Net faydayı dokümante et

Kaynaklar

Resmi ve proje içi kaynaklar:

• Honcho upstream repository: https://github.com/plastic-labs/honcho • TeamAlpha Honcho MCP endpoint: https://memory.example.com/memory-hub • TeamAlpha Honcho Admin UI: https://memory.example.com/memory-hub-admin/ • Kullanıcı kılavuzu: docs/honcho-user-manual.md • Admin kılavuzu: docs/honcho-admin-guide.md • Deployment talimatları: docs/honcho-deployment-instructions.md • Değer testi prosedürü: docs/honcho-value-test-procedure.md

Kısa Sonuç

TeamAlpha Honcho kurulumu, coding agent kullanımını tek oturumluk bir deneyim olmaktan çıkarıp proje hafızası olan sürekli bir çalışma akışına dönüştürür. Agent artık her konuşmada aynı deployment kurallarını, kullanıcı tercihlerini veya proje kararlarını yeniden öğrenmek zorunda kalmaz.

Doğru workspace izolasyonu, güvenli token yönetimi ve düzenli değer ölçümüyle Honcho; ekip içi AI kullanımında hem verimlilik hem de kontrol sağlayan pratik bir hafıza katmanıdır.