agentcairn

Desteklenen kodlama ajanları arasında tek bir kalıcı bellek.
Markdown kasanız kanoniktir. DuckDB değiştirilebilir geri çağırma önbelleğidir.

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

Bir cairn, sonradan gelenler için bir izi işaretler. agentcairn bunu kodlama ajanları için yapar: kullandığınız araçlardan kalıcı bağlamı yakalar, kaynak bilgisiyle denetlenebilir Markdown olarak saklar ve başka bir ajan ihtiyaç duyduğunda yalnızca en ilgili parçaları hatırlar.

Denetleyebileceğiniz kanıt

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

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

Dogfood anlık görüntüsü · 2026-07-15. 417 yerel geri çağırma boyunca, geliştiricinin kasası her seferinde tam kasayı yüklemekten 262× smaller daha az bağlam döndürdü—toplamda tahmini 136.6M tokens of full-vault context avoided. Token sayıları, token başına yaklaşık dört karakter kullanır. Bu, faturalandırılan token tasarrufu değildir ve agentcairn hiçbir 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ı bir araya getirir—ayrı bir agentcairn paketi kurulumu gerektirmez. 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, tur başına proje kapsamlı geri çağırma, oturum/sıkış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ı olarak doğrulanmış SessionStart geri çağırmasını ve bant dışı yedek olarak cairn sweep ile SessionEnd yakalamasını alır.

Ajan destekli kurulum

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

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ğini yükler—AgentCairn çalışma zamanını, MCP sunucusunu, eklentiyi veya kancaları değil. Asistan, bu değişiklikleri AgentCairn'in önce önizleme yapan 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'dir ve ilk kullanımda oluşturulur. Yeni boş bir kasanın henüz hatırlanacak 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 indirebilir ve ısıtabilir.

Sözleşme

Nasıl çalışır

• Yakalama: ana bilgisayar kancaları anındalığı artırır; cairn sweep, kalıcı yedek olarak desteklenen transkript depolarını bant dışı okur. AgentCairn, otomatik düz metin yazımlarından önce tanınan kimlik bilgilerini sansürler, tekilleştirir, önem kapısından geçirir ve damıtır.
• Uzlaştırma: ilk okuma, 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ı dosyalara dokunulmaz.
• 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 teşhislerle birlikte görünür şekilde BM25'e geri döner.
• Hatırlama: MCP aracı, bir yazıcı kilidi altında atomik olarak bir Markdown notu yazar ve dizini günceller, böylece başarılı bir kayıt hemen geri çağrılabilir hale gelir.

Güven için tasarlandı

• Varsayılan olarak yerel. FastEmbed yerel olarak çalışır, MCP sunucusu stdio kullanır, gerekli bir arka plan programı veya harici veritabanı yoktur ve telemetri yoktur.
• Düz sınırlar. Senkronize edilen kasa Markdown içerir; varsayılan olarak, yeniden oluşturulabilir .duckdb dizini bunun dışında kalır. Yapılandırılmış kökün dışına çıkan kasa sembolik bağlantıları reddedilir.
• Zaman farkında düzeltmeler. valid_from, valid_until ve superseded_by, mevcut gerçeklerin ilk sırada yer almasını sağlarken eski kanıtları görünür tutar.
• Deterministik grafik. [[wikilinks]] ve isteğe bağlı cairn link komşuları, bir LLM'den varlıklar icat etmesini istemeden Obsidian'a özgü bir grafik oluşturur.
• Proje farkında geri çağırma. Mevcut proje varsayılan olarak yükseltilir; projeler arası sonuçlar kullanılabilir kalır ve etiketlenir. Otomatik geri çağırma, açıkça tüm projeleri seçmediğiniz sürece proje kapsamlıdır.

Desteklenen ajanlar

Her ana bilgisayar aynı yapılandırılmış kasayı çözümler. cairn install, yazmadan algılanan ana bilgisayarları önizler. MCP yapılandırma yazımları önce yedeklenir ve ilgisiz sunucuları korur; eklenti-ana bilgisayar kurulumları ana bilgisayarın kendi CLI'sına devreder.

Codex SessionStart, agentcairn 0.24.2 / eklenti 0.1.2 ile uçtan uca canlı olarak doğrulandı. Kurulu SessionEnd komut dağıtımı ve ayrık süpürme, tam işleyici sondalarını 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 kullanma

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 taşıyın

Claude Code'un otomatik belleği, kaynak dosyalarını değiştirmeden paylaşılan kasayı besleyebilir. Komut varsayılan olarak yalnızca mevcut depoyu önizler; sansürlenmiş 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/'ı okumaz. İçe aktarılan notlar Claude Code, proje ve kaynak dosya kaynağını korur. Bir kaynak değiştiğinde, önceki sürüm denetlenebilir kalır ancak yerine geçer; bir kaynak kaybolduğunda, içe aktarılan sürümünün süresi dolar. Küçük bir .agentcairn/native-memory/ kaydı, kaynak içeriği iki kez indekslemeden bu yaşam döngüsünü korur. Özel, yönetilen veya oturum tarafından geçersiz kılınan bir Claude bellek dizini için --source <dir> veya toplu içe aktarmalar yaparken --no-reindex kullanın.

Geçici bir süreci 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ş, tekrarlanabilir bir LongMemEval-S + LoCoMo koşum takı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 ile döndürülen bağlam, tam indekslenmiş geçmişten çok daha küçüktür:

Rakamları dürüstçe okuyun:

• Geri çağırma hatırlaması, QA doğruluğu değildir. Bu tablolar, son kullanıcı yanıt kalitesini veya başka bir ürünün liderlik tablosu puanını değil, kontrollü geri çağırma kollarını karşılaştırır.
• Token sayıları, token başına yaklaşık dört karakterlik bir sezgisel yöntem kullanır. Azalma, indekslenmiş samanlığı döndürülen parçalarla karşılaştırır; faturalandırılan maliyet tasarrufu değildir.
• Grafik desteği, yerel [[wikilink]] grafiği içermedikleri için bu sohbet derlemelerinde etkisizdir. 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öreceli ablasyonlar için yararlıdır—yayınlanmış liderlik 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 bulunur.

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ı sansürler; bilinmeyen kalıplar ve elle yapılan düzenlemeler sizin sorumluluğunuzdadır.
• Bulut özellikleri açık çıkış trafiğidir. Varsayılan yerel kalır. Bir bulut gömücü veya LLM değerlendiriciye geçiş yapmak, kalan sansürlenmiş 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 getirme kanıtı, evrensel bir kod arama iddiası değil, konuşma belleği için en güçlüdür.
• Ortam davranışı ana bilgisayara göre değişir. Yukarıdaki matris kasıtlıdır: Cursor ve Antigravity tarama yakalamaya dayanır; genel MCP ana bilgisayarları, yaşam döngüsü kancaları olmadan araçları sunabilir.
• Otomasyon platforma özeldir. 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 gerileme testini çalıştırın:

uv run pytest benchmarks/tests/

Lisans

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