agentcairn

Satu memori tahan lama di seluruh agen pengkodean yang didukung.
Vault Markdown Anda adalah sumber kanonik. DuckDB adalah cache pengambilan yang dapat diganti.

Situs web · PyPI · Pendamping Obsidian · Tolok ukur

Sebuah cairn menandai jejak bagi siapa pun yang datang berikutnya. agentcairn melakukan hal itu untuk agen pengkodean: ia menangkap konteks tahan lama dari alat yang Anda gunakan, menyimpannya sebagai Markdown yang dapat diperiksa dengan provenans, dan hanya mengingat kembali bagian yang paling relevan saat agen lain membutuhkannya.

Bukti yang dapat Anda periksa

Memori tidak disembunyikan di balik konsol admin atau basis data yang dihosting. Pendamping terpisah agentcairn-obsidian membaca file Markdown yang sama dengan agen dan mengekspos provenans, kekinian, kepentingan, supersesi, dan tautan related:.

_{Vault agentcairn nyata di Obsidian. Daftar ini adalah tampilan atas file—bukan penyimpanan memori kedua.}

Cuplikan dogfood · 2026-07-15. Di 417 pengambilan lokal, vault pemelihara mengembalikan konteks tentang 262× smaller daripada memuat seluruh vault setiap kali—perkiraan 136.6M tokens of full-vault context avoided secara agregat. Jumlah token menggunakan sekitar empat karakter per token. Ini bukan penghematan token yang ditagih, dan agentcairn tidak mengirim telemetri.

Instalasi

Jalur terpendek adalah plugin kelas satu. Plugin ini menggabungkan server MCP, keterampilan memori, dan hook ambient khusus host—tanpa instalasi paket agentcairn terpisah. Plugin diluncurkan melalui uvx, jadi instal uv terlebih dahulu jika uvx --version belum tersedia.

Claude Code

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

Claude Code mendapatkan pengambilan cakupan proyek per giliran, penangkapan sesi/kompaksi, dan perintah /agentcairn:recall, /agentcairn:remember, /agentcairn:memory, /agentcairn:savings, dan /agentcairn:ingest.

Codex

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

Codex mendapatkan alat MCP dan keterampilan memori yang digabungkan, pengambilan SessionStart yang terverifikasi langsung, dan penangkapan SessionEnd dengan cairn sweep sebagai cadangan di luar jalur.

Penyiapan berbantuan agen

Sudah menggunakan skills.sh atau alur kerja find-skills? Instal asisten penyiapan publik:

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

Lalu tanyakan agen Anda: Use $agentcairn-setup to preview, install, and verify AgentCairn for this coding agent.

Ini hanya menginstal panduan penyiapan—bukan runtime AgentCairn, server MCP, plugin, atau hook. Asisten mendelegasikan perubahan tersebut ke penginstal asli AgentCairn yang mengutamakan pratinjau dan memverifikasi integrasi yang dihasilkan. Perintah plugin Claude Code dan Codex di atas tetap menjadi jalur terpendek.

Vault default adalah ~/agentcairn dan dibuat pada penggunaan pertama. Vault kosong baru belum memiliki apa pun yang berguna untuk diingat kembali, jadi buktikan seluruh loop secara eksplisit:

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 menulis catatan Markdown dan entri indeks secara bersamaan, sehingga pengambilan langsung menjadi bagian dari kontrak. Proses lokal pertama mungkin mengunduh dan menghangatkan model embedding/reranking yang dikonfigurasi.

Kontrak

Cara kerjanya

• Penangkapan: hook host meningkatkan kecepatan; cairn sweep membaca penyimpanan transkrip yang didukung di luar jalur sebagai cadangan tahan lama. AgentCairn menyunting kredensial yang dikenali, mendeduplikasi, memfilter kepentingan, dan menyuling sebelum penulisan teks biasa otomatis.
• Rekonsiliasi: pembacaan pertama secara transaksional menyinkronkan indeks cakupan vault dengan Markdown. Rebuild yang gagal mempertahankan cache terakhir yang baik dan file tahan lama tetap tidak tersentuh.
• Pengambilan: vektor BM25 dan semantik digabungkan dengan Reciprocal Rank Fusion, lalu opsional di-rerank. Kegagalan model/penyedia terlihat jelas jatuh kembali ke BM25 dengan diagnostik alih-alih mengembalikan vektor yang tidak kompatibel.
• Ingat: alat MCP secara atomik menulis catatan Markdown dan memperbarui indeks di bawah satu kunci penulis, membuat penyimpanan yang berhasil langsung dapat diingat kembali.

Dirancang untuk kepercayaan

• Lokal secara default. FastEmbed berjalan lokal, server MCP menggunakan stdio, tidak ada daemon atau basis data eksternal yang diperlukan, dan tidak ada telemetri.
• Batas yang jelas. Vault yang disinkronkan berisi Markdown; secara default, indeks .duckdb yang dapat dibangun ulang tetap berada di luarnya. Symlink vault yang melarikan diri dari root yang dikonfigurasi ditolak.
• Koreksi sadar waktu. valid_from, valid_until, dan superseded_by menjaga bukti lama tetap terlihat sambil membuat fakta saat ini menempati peringkat pertama.
• Graf deterministik. [[wikilinks]] dan tetangga cairn link opsional membuat graf asli Obsidian tanpa meminta LLM untuk menciptakan entitas.
• Pengambilan sadar proyek. Proyek saat ini ditingkatkan secara default; hasil lintas proyek tetap tersedia dan diberi label. Pengambilan otomatis dicakup proyek kecuali Anda secara eksplisit memilih semua proyek.

Agen yang didukung

Setiap host menyelesaikan vault yang dikonfigurasi yang sama. cairn install mempratinjau host yang terdeteksi tanpa menulis. Penulisan konfigurasi MCP adalah backup-first dan mempertahankan server yang tidak terkait; instalasi host plugin mendelegasikan ke CLI host itu sendiri.

Codex SessionStart diverifikasi langsung end-to-end dengan agentcairn 0.24.2 / plugin 0.1.2. Dispatch perintah SessionEnd yang terinstal dan sapuan terpisah lulus probe handler yang tepat; cairn sweep tetap menjadi cadangan penangkapan di luar jalur. Lihat integrasi OpenCode dan integrasi Hermes untuk detail siklus hidup asli mereka.

Menggunakannya secara langsung

Plugin adalah rute termudah, tetapi agentcairn juga merupakan CLI mandiri dan server MCP sesuai permintaan. Instalasi mandiri memerlukan Python 3.11+.

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

Bawa memori Claude Code bersama Anda

Auto-memori Claude Code dapat mengisi vault bersama tanpa mengubah file sumbernya. Perintah mempratinjau hanya repositori saat ini secara default; tambahkan --apply untuk menulis catatan yang disunting dan menyegarkan indeks.

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

Impor satu arah membaca MEMORY.md dan file Markdown topiknya—tidak pernah CLAUDE.md atau .claude/rules/. Catatan yang diimpor mempertahankan provenans Claude Code, proyek, dan file sumber. Saat sumber berubah, versi sebelumnya tetap dapat diperiksa tetapi disupersesi; saat sumber hilang, versi impornya kedaluwarsa. Registri kecil .agentcairn/native-memory/ mempertahankan siklus hidup itu tanpa mengindeks konten sumber dua kali. Gunakan --source <dir> untuk direktori memori Claude kustom, terkelola, atau yang ditimpa sesi, atau --no-reindex saat mengimpor secara batch.

Lebih suka proses sementara:

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

Tolok ukur yang diukur

Repositori mengirimkan harness LongMemEval-S + LoCoMo yang dapat direproduksi dan dipatok revisi. Defaultnya adalah nomic-embed-text-v1.5 lokal plus reranker cross-encoder.

Konteks yang dikembalikan pada k=10 default jauh lebih kecil daripada riwayat terindeks lengkap:

Baca angka-angka dengan jujur:

• Recall pengambilan bukan akurasi QA. Tabel ini membandingkan lengan pengambilan yang terkontrol, bukan kualitas jawaban pengguna akhir atau skor papan peringkat produk lain.
• Jumlah token menggunakan heuristik sekitar empat karakter per token. Reduksi membandingkan tumpukan jerami terindeks dengan potongan yang dikembalikan; ini bukan penghematan biaya yang ditagih.
• Boost graf tidak aktif pada korpora obrolan ini karena tidak mengandung graf [[wikilink]] asli. Ini dirancang untuk vault interlink nyata.
• Juri QA opsional menggunakan Anthropic alih-alih pengaturan GPT-4o dari makalah, sehingga hasil QA tersebut berguna untuk ablasi relatif—bukan perbandingan papan peringkat yang diterbitkan.

Metrik lengkap, sapuan embedding, pengukuran latensi, lisensi, perintah, dan peringatan ada di benchmarks/README.md.

Privasi dan batasan

• Vault bersifat plaintext secara desain, bukan penyimpanan terenkripsi. AgentCairn menyunting pola kredensial yang dikenali sebelum penulisan otomatis body/title/tag; pola yang tidak dikenal dan edit manual tetap menjadi tanggung jawab Anda.
• File vault hanya dapat diakses oleh pemilik (0600/0700). Karena vault bersifat plaintext dan penyuntingan bersifat best-effort, mode file secara efektif adalah satu-satunya kontrol aksesnya. Pengaturan shared-GID (misalnya dua kontainer Docker pada grup yang sama tetapi UID berbeda) memerlukan akses grup, sehingga vault_group_writable = true memperluas catatan dan direktori vault baru menjadi 0660/0770. Ini bersifat opt-in dengan sengaja: di macOS, grup utama setiap pengguna lokal adalah staff, sehingga default yang dapat dibaca grup akan mengekspos memori Anda ke akun lain di mesin tersebut. Knob ini tidak pernah memperluas apa pun di luar vault — indeks, buku besar, file kunci, dan ~/.agentcairn/config.toml tetap privat.
• Fitur cloud adalah egress eksplisit. Default tetap lokal. Memilih embedder cloud atau LLM judge akan mengirim teks yang telah disunting ke penyedia tersebut.
• Proyek ini masih beta. Penggunaan mandiri memerlukan Python 3.11+, dan pemuatan model lokal pertama dapat memakan waktu. Bukti pengambilan (retrieval) yang dipublikasikan paling kuat untuk memori percakapan, bukan klaim pencarian kode universal.
• Perilaku ambient bervariasi menurut host. Matriks di atas disengaja: Cursor dan Antigravity mengandalkan penangkapan sweep; host MCP generik dapat mengekspos alat tanpa hook siklus hidup.
• Otomatisasi bersifat spesifik platform. Penjadwalan terkelola menargetkan launchd macOS dan crontab pengguna Linux; gunakan penjadwal Anda sendiri di tempat lain.

Pengembangan

agentcairn menggunakan uv secara eksklusif untuk manajemen dependensi dan perkakas.

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

Jalankan regresi benchmark offline tanpa kunci API:

uv run pytest benchmarks/tests/

Lisensi

Apache License 2.0 — permisif, dengan hibah paten eksplisit. Hak cipta © 2026 Charles C. Figueiredo.