AI Genel Çalışma Rehberi

Blog / Rehber

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

16 dk okumaHonchoMCPSelf-HostedAgent MemoryJWT

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:

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:

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:

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:

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:

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.

flowchart TB A["Coding agent<br/>VS Code · Codex · Claude Code · Cursor"] N["Nginx<br/>/memory-hub"] M["Honcho MCP service<br/>:8787"] API["Honcho API service<br/>:8000"] PG[("PostgreSQL")] R[("Redis")] D["Deriver<br/>arka plan işleyici"] L["Primary LLM endpoint<br/>OpenAI fallback"] A -- "MCP over HTTPS + workspace JWT" --> N N --> M M -- "internal REST" --> API API --> PG API --> R D --> PG D --> L

Servisler:

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:

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:

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:

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:

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ı

Hafta 2: Gerçek proje kullanımı

Hafta 3: Ekip ölçeği

Hafta 4: Değer testi

Kaynaklar

Resmi ve proje içi kaynaklar:

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.