agentcairn

Satu memori tahan lama di seluruh agen pengkodean yang didukung.
Vault Markdown Anda bersifat kanonis. 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 asal-usul, 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 terhosting. Pendamping agentcairn-obsidian yang terpisah membaca file Markdown yang sama seperti agen dan mengekspos asal-usul, kekinian, kepentingan, penggantian, dan tautan related:.

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

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

Instal

Jalur terpendek adalah plugin kelas satu. Ini menggabungkan server MCP, keterampilan memori, dan kait ambien spesifik 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 pemanggilan per-giliran dengan cakupan proyek, 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 dibundel, pemanggilan SessionStart yang diverifikasi langsung, dan penangkapan SessionEnd dengan cairn sweep sebagai cadangan di luar jalur.

Penyiapan dengan bantuan 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 kepada 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 kait. Asisten mendelegasikan perubahan tersebut ke penginstal asli pratinjau-pertama AgentCairn dan memverifikasi integrasi yang dihasilkan. Perintah plugin Claude Code dan Codex di atas tetap menjadi jalur terpendek.

Vault default adalah ~/agentcairn dan dibuat saat pertama kali digunakan. Vault kosong baru belum memiliki hal berguna untuk diingat, 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 bersamaan, sehingga pemanggilan segera adalah bagian dari kontrak. Proses lokal pertama mungkin mengunduh dan menghangatkan model embedding/reranking yang dikonfigurasi.

Kontrak

Cara kerjanya

• Tangkap: kait host meningkatkan kesegeraan; cairn sweep membaca penyimpanan transkrip yang didukung di luar jalur sebagai cadangan tahan lama. AgentCairn menyunting kredensial yang dikenali, mendeduplikasi, memfilter berdasarkan kepentingan, dan menyaring sebelum penulisan teks biasa otomatisnya.
• Rekonsiliasi: pembacaan pertama secara transaksional menyelaraskan indeks bercakupan vault dengan Markdown. Pembangunan ulang yang gagal mempertahankan cache baik terakhir dan file tahan lama tetap tidak tersentuh.
• Ingat kembali: BM25 dan vektor semantik digabungkan dengan Reciprocal Rank Fusion, lalu secara opsional di-rerank. Kegagalan model/penyedia secara kasat mata 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 segera dapat dipanggil kembali.

Dirancang untuk kepercayaan

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

Agen yang didukung

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

SessionStart Codex diverifikasi langsung ujung-ke-ujung dengan agentcairn 0.24.2 / plugin 0.1.2. Pengiriman 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

Memori otomatis Claude Code dapat mengisi vault bersama tanpa mengubah file sumbernya. Perintah hanya mempratinjau 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 asal-usul Claude Code, proyek, dan file sumber. Ketika sumber berubah, versi sebelumnya tetap dapat diperiksa tetapi digantikan; ketika sumber menghilang, versi impornya kedaluwarsa. Registri .agentcairn/native-memory/ kecil mempertahankan siklus hidup itu tanpa mengindeks konten sumber dua kali. Gunakan --source <dir> untuk direktori memori Claude khusus, 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 ini menyertakan harness LongMemEval-S + LoCoMo yang disematkan revisi dan dapat direproduksi. Defaultnya adalah nomic-embed-text-v1.5 lokal ditambah cross-encoder reranker.

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

Baca angka-angkanya dengan jujur:

• Recall pengambilan bukanlah akurasi QA. Tabel ini membandingkan lengan pengambilan terkontrol, bukan kualitas jawaban pengguna akhir atau skor papan peringkat produk lain.
• Hitungan token menggunakan heuristik sekitar empat karakter per token. Pengurangan membandingkan tumpukan jerami terindeks dengan potongan yang dikembalikan; ini bukan penghematan biaya yang ditagih.
• Dorongan graf tidak aktif pada korpora obrolan ini karena tidak mengandung graf [[wikilink]] asli. Ini dirancang untuk vault yang saling tertaut secara nyata.
• Penilai QA opsional menggunakan Anthropic daripada pengaturan GPT-4o di makalah, sehingga hasil QA tersebut berguna untuk ablasi relatif—bukan perbandingan papan peringkat yang dipublikasikan.

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

Privasi dan batasan

• Vault dirancang sebagai teks biasa, bukan penyimpanan terenkripsi. AgentCairn menyunting pola kredensial yang dikenali sebelum penulisan otomatis isi/judul/tag; pola yang tidak dikenal dan suntingan manual tetap menjadi tanggung jawab Anda.
• Fitur cloud adalah egress eksplisit. Default tetap lokal. Memilih penyemat cloud atau juri LLM akan mengirim teks yang telah disunting ke penyedia tersebut.
• Proyek ini dalam tahap beta. Penggunaan mandiri memerlukan Python 3.11+, dan pemuatan model lokal pertama dapat memakan waktu. Bukti pengambilan 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 tangkapan sapuan; host MCP generik mungkin mengekspos alat tanpa kait siklus hidup.
• Otomatisasi 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 tolok ukur luring tanpa kunci API:

uv run pytest benchmarks/tests/

Lisensi

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