agentcairn

Desteklenen kodlama ajanları arasında tek kalıcı bellek.
Markdown kasalarınız birincil kaynaktır. DuckDB, değiştirilebilir bir geri çağırma önbelleğidir.

Web sitesi · PyPI · Obsidian eşlikçisi · Kıyaslamalar

Bir cairn, sonra gelenler için yolu işaretler. agentcairn kodlama ajanları için bunu yapar: kullandığınız araçlardan kalıcı bağlamı yakalar, kaynakça ile incelenebilir Markdown olarak saklar ve başka bir ajan ihtiyaç duyduğunda yalnızca en alakalı parçaları geri çağırır.

İnceleyebileceğiniz kanıt

Bellek, bir yönetici konsolunun veya barındırılan bir veritabanının arkasında gizli değildir. Ayrı agentcairn-obsidian eşlikçisi, ajanlarla aynı Markdown dosyalarını okur ve kaynakça, güncellik, önem, yerine geçme ve related: bağlantılarını ortaya çıkarır.

_{Obsidian'da gerçek bir agentcairn kasası. Liste, dosyalar üzerinde bir görünümdür—ikinci bir bellek deposu değildir.}

Köpek maması anlık görüntüsü · 2026-07-15. 417 yerel geri çağırma boyunca, bakıcının kasası, her seferinde tüm kasayı yüklemekten 262× smaller bağlam döndürdü—toplamda tahmini 136.6M tokens of full-vault context avoided tasarruf. Token sayıları yaklaşık olarak token başına dört karakter kullanır. Bu, faturalanan token tasarrufu değildir ve agentcairn telemetri göndermez.

Kurulum

En kısa yol, birinci sınıf bir eklentidir. MCP sunucusunu, bellek becerisini ve ana bilgisayara özgü ortam kancalarını paketler—ayrı bir agentcairn paketi kurulumu gerekmez. Eklenti uvx aracılığıyla başlatılır, bu nedenle uvx --version zaten mevcut değilse önce uv kurun.

Claude Code

claude plugin marketplace add ccf/agentcairn
claude plugin install agentcairn@agentcairn

Claude Code, her turda proje kapsamlı geri çağırma, oturum/kompaktlaştırma yakalama ve /agentcairn:recall, /agentcairn:remember, /agentcairn:memory, /agentcairn:savings ve /agentcairn:ingest komutlarını alır.

Codex

codex plugin marketplace add ccf/agentcairn
codex plugin add agentcairn@agentcairn

Codex, paketlenmiş MCP araçlarını ve bellek becerisini, canlı doğrulanmış SessionStart geri çağırmasını ve cairn sweep bant dışı yedek olarak kullanılan SessionEnd yakalamasını alır.

Ajan destekli kurulum

Zaten skills.sh veya bir find-skills iş akışı mı kullanıyorsunuz? Genel kurulum asistanını kurun:

npx skills add ccf/agentcairn --skill agentcairn-setup -g

Ardından ajanınıza sorun: Use $agentcairn-setup to preview, install, and verify AgentCairn for this coding agent.

Bu yalnızca kurulum rehberliği kurar—AgentCairn çalışma zamanı, MCP sunucusu, eklenti veya kancalar değil. Asistan, bu değişiklikleri AgentCairn'in önizleme öncelikli yerel yükleyicisine devreder ve ortaya çıkan entegrasyonu doğrular. Yukarıdaki Claude Code ve Codex eklenti komutları en kısa yol olmaya devam eder.

Varsayılan kasa ~/agentcairn konumundadır ve ilk kullanımda oluşturulur. Yeni boş bir kasanın henüz geri çağrılacak yararlı bir şeyi yoktur, bu nedenle tüm döngüyü açıkça kanıtlayın:

You   → Remember this durable fact: staging deploys use blue-green.
Agent → written and indexed
You   → Recall the staging deploy strategy.
Agent → staging deploys use blue-green.  ↳ <memory permalink>

remember, Markdown notunu ve dizin girişini birlikte yazar, böylece anında geri çağırma sözleşmenin bir parçasıdır. İlk yerel çalıştırma, yapılandırılmış gömme/yeniden sıralama modellerini indirip ısıtabilir.

Sözleşme

Nasıl çalışır

• Yakalama: ana bilgisayar kancaları anlıklığı artırır; cairn sweep, desteklenen işlem kayıtlarını bant dışı kalıcı yedek olarak okur. AgentCairn, otomatik düz metin yazımlarından önce tanınan kimlik bilgilerini karartır, yinelenenleri kaldırır, önem kapısı uygular ve damıtır.
• Mutabakat: ilk okuma işlemi, kasa kapsamlı dizini Markdown ile işlemsel olarak senkronize eder. Başarısız bir yeniden oluşturma, son iyi önbelleği korur ve kalıcı dosyalar dokunulmaz kalır.
• Geri çağırma: BM25 ve anlamsal vektörler, Karşılıklı Sıra Füzyonu ile birleştirilir, ardından isteğe bağlı olarak yeniden sıralanır. Model/sağlayıcı hataları, uyumsuz vektörler döndürmek yerine tanılama ile görünür şekilde BM25'e düşer.
• Hatırlama: MCP aracı, tek bir yazıcı kilidi altında atomik olarak bir Markdown notu yazar ve dizini günceller, böylece başarılı bir kayıt anında geri çağrılabilir olur.

Güven için tasarlandı

• Varsayılan olarak yerel. FastEmbed yerel olarak çalışır, MCP sunucusu stdio kullanır, gerekli bir arka plan hizmeti veya harici veritabanı yoktur ve telemetri yoktur.
• Net sınırlar. Senkronize kasa Markdown içerir; varsayılan olarak, yeniden oluşturulabilir .duckdb dizini onun dışında kalır. Yapılandırılmış kökü aşan kasa sembolik bağlantıları reddedilir.
• Zaman farkındalıklı düzeltmeler. valid_from, valid_until ve superseded_by, eski kanıtları görünür tutarken mevcut gerçeklerin ilk sırada yer almasını sağlar.
• Belirleyici grafik. [[wikilinks]] ve isteğe bağlı cairn link komşuları, bir LLM'den varlık icat etmesini istemeden Obsidian yerel bir grafik oluşturur.
• Proje farkındalıklı geri çağırma. Mevcut proje varsayılan olarak güçlendirilir; projeler arası sonuçlar mevcut kalır ve etiketlenir. Otomatik geri çağırma, açıkça tüm projelere katılmadıkça proje kapsamlıdır.

Desteklenen ajanlar

Her ana bilgisayar aynı yapılandırılmış kasayı çözer. cairn install, yazmadan algılanan ana bilgisayarları önizler. MCP yapılandırma yazımları yedek önceliklidir ve ilgisiz sunucuları korur; eklenti ana bilgisayar kurulumları, ana bilgisayarın kendi CLI'sine devreder.

Codex SessionStart, agentcairn 0.24.2 / eklenti 0.1.2 ile uçtan uca canlı doğrulandı. Kurulu SessionEnd komut dağıtımı ve ayrılmış süpürme, tam işleyici testlerini geçer; cairn sweep bant dışı yakalama yedeği olarak kalır. Yerel yaşam döngüsü ayrıntıları için OpenCode entegrasyonuna ve Hermes entegrasyonuna bakın.

Doğrudan kullanım

Eklenti en kolay yoldur, ancak agentcairn aynı zamanda bağımsız bir CLI ve isteğe bağlı MCP sunucusudur. Bağımsız kurulumlar Python 3.11+ gerektirir.

uv tool install agentcairn

cairn init ~/agentcairn
cairn sweep --vault ~/agentcairn
cairn recall "how did we fix the auth bug?" --vault ~/agentcairn
cairn doctor --vault ~/agentcairn

Claude Code'un belleğini yanınızda getirin

Claude Code'un otomatik belleği, kaynak dosyalarını değiştirmeden paylaşılan kasayı tohumlayabilir. Komut varsayılan olarak yalnızca mevcut depoyu önizler; karartılmış notları yazmak ve dizini yenilemek için --apply ekleyin.

cairn import claude-memory                         # preview; writes nothing
cairn import claude-memory --apply                 # import this repository
cairn import claude-memory --project ../other --apply

Tek yönlü içe aktarma, MEMORY.md ve konu Markdown dosyalarını okur—asla CLAUDE.md veya .claude/rules/. İçe aktarılan notlar Claude Code, proje ve kaynak dosya kaynakçasını korur. Bir kaynak değiştiğinde, önceki sürüm incelenebilir kalır ancak yerine geçer; bir kaynak kaybolduğunda, içe aktarılan sürümü süresi dolar. Küçük bir .agentcairn/native-memory/ kayıt defteri, kaynak içeriğini iki kez dizinlemeden bu yaşam döngüsünü korur. Özel, yönetilen veya oturum geçersiz kılınmış bir Claude bellek dizini için --source <dir> kullanın veya toplu içe aktarmalar yaparken --no-reindex kullanın.

Geçici bir süreç tercih edin:

uvx agentcairn                             # MCP server
uvx --from agentcairn cairn recall "..."  # CLI; plain `uvx cairn` is a different package

cairn schedule install --vault ~/agentcairn  # launchd on macOS / user crontab on Linux
cairn schedule status
cairn link --vault ~/agentcairn              # write deterministic related: neighbors
cairn reindex ~/agentcairn                   # rebuild the disposable cache
cairn savings                                # local context-efficiency estimate
cairn index-status --vault ~/agentcairn

cairn config --init
cairn config

auto_recall = true
auto_recall_k = 3
auto_recall_scope = "project"  # use "all" only as an explicit cross-project opt-in

Ölçülen kıyaslamalar

Depo, revizyon sabitlenmiş, yeniden üretilebilir bir LongMemEval-S + LoCoMo donanımı ile birlikte gelir. Varsayılan, yerel nomic-embed-text-v1.5 artı çapraz kodlayıcı yeniden sıralayıcıdır.

Varsayılan k=10 değerinde döndürülen bağlam, tam dizinlenmiş geçmişten çok daha küçüktür:

Rakamları dürüstçe okuyun:

• Geri çağırma, QA doğruluğu değildir. Bu tablolar, kontrollü geri çağırma kollarını karşılaştırır, son kullanıcı yanıt kalitesini veya başka bir ürünün lider tablosu puanını değil.
• Token sayıları, token başına yaklaşık dört karakterlik bir buluşsal yöntem kullanır. Azaltma, dizinlenmiş samanlığı döndürülen parçalarla karşılaştırır; faturalanan maliyet tasarrufu değildir.
• Grafik güçlendirme, bu sohbet külliyatlarında etkisizdir çünkü yerel [[wikilink]] grafiği içermezler. Gerçek birbirine bağlı kasalar için tasarlanmıştır.
• İsteğe bağlı QA yargıcı, makalelerin GPT-4o kurulumu yerine Anthropic kullanır, bu nedenle bu QA sonuçları göreli ablasyonlar için yararlıdır—yayınlanmış lider tablosu karşılaştırmaları için değil.

Tam metrikler, gömme taramaları, gecikme ölçümleri, lisanslar, komutlar ve uyarılar benchmarks/README.md içinde yaşar.

Gizlilik ve sınırlar

• Kasa tasarım gereği düz metindir, şifreli depolama değildir. AgentCairn, otomatik gövde/başlık/etiket yazımlarından önce tanınan kimlik bilgisi kalıplarını karartır; bilinmeyen kalıplar ve elle yapılan düzenlemeler sizin sorumluluğunuzdadır.
• Kasa dosyaları yalnızca sahibine aittir (0600/0700). Kasa düz metin olduğundan ve karartma en iyi çaba olduğundan, dosya modu etkin olarak tek erişim kontrolüdür. Paylaşılan GID kurulumları (ör. aynı grupta ancak farklı UID'lerde iki Docker konteyneri) grup erişimi gerektirir, bu nedenle vault_group_writable = true yeni kasa notlarını ve dizinlerini 0660/0770 değerine genişletir. Bu bilinçli olarak tercihe bağlıdır: macOS'ta her yerel kullanıcının birincil grubu staff olduğundan, grup tarafından okunabilir bir varsayılan, anılarınızı makinedeki diğer hesaplara açığa çıkarır. Bu ayar kasa dışındaki hiçbir şeyi genişletmez — dizin, defterler, kilit dosyaları ve ~/.agentcairn/config.toml özel kalır.
• Bulut özellikleri açık dışa aktarımdır. Varsayılan yerel kalır. Bulut tabanlı bir gömücü veya LLM değerlendiricisini tercih etmek, kalan karartılmış metni o sağlayıcıya gönderir.
• Proje beta aşamasındadır. Bağımsız kullanım Python 3.11+ gerektirir ve ilk yerel model yüklemesi zaman alabilir. Yayınlanan geri alma kanıtı, evrensel bir kod arama iddiasından ziyade konuşma belleği için en güçlüdür.
• Ortam davranışı ana bilgisayara göre değişir. Yukarıdaki matris bilinçlidir: Cursor ve Antigravity süpürme yakalamasına dayanır; genel MCP ana bilgisayarları, yaşam döngüsü kancaları olmadan araçları açığa çıkarabilir.
• Otomasyon platforma özgüdür. Yönetilen zamanlama, macOS launchd ve Linux kullanıcı crontab'ını hedefler; başka yerlerde kendi zamanlayıcınızı kullanın.

Geliştirme

agentcairn, bağımlılık yönetimi ve araçlar için yalnızca uv kullanır.

uv sync
uv run pre-commit install

uv run pytest
uv run ruff format .
uv run ruff check --fix .
uv run pre-commit run --all-files

API anahtarları olmadan çevrimdışı kıyaslama regresyonunu çalıştırın:

uv run pytest benchmarks/tests/

Lisans

Apache Lisansı 2.0 — açık patent hükmüyle izin verici. Telif Hakkı © 2026 Charles C. Figueiredo.