agentcairn MCP Server

resmi

Memori agen lokal-utama: vault Obsidian Markdown biasa adalah sumber kebenaran, dengan indeks DuckDB yang dapat dibangun ulang untuk pengingatan hibrida BM25 + vektor + graf.

GitHub
1

Dokumentasi

πŸͺ¨ agentcairn

CI Security PyPI Python License: Apache-2.0

Memori lokal-pertama untuk agen AI β€” yang benar-benar bisa Anda baca, edit, dan miliki.

cairn Β /kΙ›Ι™n/Β  Β· kata benda β€” tumpukan batu yang ditinggikan untuk menandai jejak atau tempat yang layak diingat, ditinggalkan untuk siapa pun yang datang berikutnya.

agentcairn memberikan agen pengkode Anda memori yang tahan lama dan berkualitas tinggi β€” tetapi alih-alih menguncinya dalam basis data buram atau layanan cloud, memori Anda hidup sebagai Markdown biasa di lemari Obsidian yang Anda miliki. Indeks DuckDB yang cepat dan dapat dibangun ulang berada di atasnya untuk pengambilan. Buka lemari Anda, baca apa yang diingat agen, perbaiki fakta yang salah secara manual, atau masukkan catatan Anda sendiri β€” dan agen akan mengambil semuanya.

Mengapa agentcairn berbeda

Sebagian besar sistem memori agen menjadikan basis data atau penyimpanan cloud sebagai sumber kebenaran dan memperlakukan berkas (jika ada) sebagai ekspor satu arah. agentcairn membaliknya:

  • πŸ“‚ Lemari Anda adalah sumber kebenaran β€” bukan ekspor. Memori adalah Markdown yang dapat dibaca manusia dengan frontmatter dan [[wikilinks]]. Edit di Obsidian; indeks menghormati suntingan Anda.
  • ♻️ Indeks dapat dibuang. DuckDB adalah cache yang dapat dibangun ulang (cairn reindex). Memori Anda bertahan dari peningkatan model, indeks yang rusak, perubahan skema, atau penghapusan alat β€” tanpa kehilangan data, karena kebenarannya hanyalah berkas di disk.
  • 🧠 Non-lossy secara konstruksi. Catatan lengkap selalu dipertahankan. Distilasi hanya menambahkan catatan turunan yang menaut kembali ke sumber β€” tidak pernah diam-diam menghilangkan fakta yang tidak terpikirkan untuk diekstrak saat penulisan.
  • πŸ”’ Redaksi sebelum setiap penulisan. Rahasia dibersihkan (regex + entropi + deteksi kredensial URL) sebelum apa pun β€” isi, judul, atau tag β€” mencapai lemari teks biasa. Kami menulis berkas yang dapat Anda baca, jadi kami memperlakukan kredensial yang bocor sebagai mode kegagalan terburuk.
  • πŸ•ΈοΈ Graf pengetahuan deterministik gratis. [[wikilinks]] dan frontmatter Anda adalah grafnya β€” tanpa ekstraksi LLM, tanpa entitas yang dihalusinasi.
  • πŸͺΆ Tanpa daemon, tanpa DB eksternal. Satu berkas DuckDB tertanam melakukan pencarian vektor semantik, teks lengkap BM25, dan penjelajahan graf. Tanpa server yang selalu aktif, tanpa Neo4j/Postgres/Qdrant, tanpa kunci cloud yang diperlukan β€” hanya CLI cairn dan server MCP sesuai permintaan.
  • πŸ” Diukur dengan jujur. Harness LongMemEval-S + LoCoMo yang dapat direproduksi tersedia di benchmarks/ β€” dengan angka nyata, ablasi, dan peringatan eksplisit alih-alih satu judul pilihan (lihat di bawah).

Instal

Cara termudah untuk menggunakan agentcairn adalah plugin untuk Claude Code atau Codex β€” satu instal menghubungkan server MCP, memori sekitar (pengingatan di awal sesi, penangkapan di akhir sesi), keterampilan memori, dan perintah garis miring (Claude Code):

# Claude Code
claude plugin marketplace add ccf/agentcairn
claude plugin install agentcairn@agentcairn

# Codex (from the Codex plugin marketplace)
codex plugin marketplace add ccf/agentcairn
codex plugin add agentcairn@agentcairn

Saat instal, Anda memilih jalur lemari (default ~/agentcairn); itu dibuat otomatis pada sesi pertama β€” tanpa perlu pengaturan Obsidian. Sejak saat itu, agentcairn menampilkan memori yang relevan di awal setiap sesi, menyaring setiap sesi ke dalam lemari Anda, dan memberi Anda /agentcairn:recall, /remember, /memory, /savings, dan /ingest. Tidak perlu pip-install β€” plugin menjalankan paket yang diterbitkan melalui uvx.

Tidak menggunakan Claude Code atau Codex? agentcairn juga merupakan server MCP mandiri + CLI untuk host apa pun β€” lihat Menggunakannya secara langsung.

Cara kerjanya

flowchart LR
    T["Session transcripts<br/>(out-of-band)"]
    H["You Β· Obsidian<br/>(hand edits)"]
    V["πŸ“‚ Obsidian vault<br/>Markdown + frontmatter + wikilinks<br/><b>source of truth</b>"]
    I["♻️ DuckDB index<br/>vector + BM25 + graph<br/><b>rebuildable cache</b>"]
    M["MCP tools<br/>remember Β· recall Β· search Β· build_context Β· recent"]

    T -- "redact β†’ judge β†’ distill β†’ consolidate" --> V
    H -- "edit" --> V
    V -- "parse / reconcile-on-spawn" --> I
    I -- "READ_ONLY hybrid recall" --> M
    M -. "remember (redacted write)" .-> V

    classDef truth fill:#eaf1ff,stroke:#317cff,color:#191919;
    classDef cache fill:#f5f5f3,stroke:#999999,color:#191919;
    class V truth
    class I cache
  • Penangkapan membaca transkrip sesi harness agen Anda (hanya-tambah, sudah ada di disk) di luar jalur β€” kuat secara desain, tanpa kait langsung yang rapuh β€” lalu meredaksi β†’ mendeduplikasi β†’ menilai (ketahanan semantik; distilasi LLM opsional melalui CAIRN_JUDGE=anthropic) β†’ membatasi β†’ menyaring ke dalam lemari, secara non-lossy. cairn sweep mendeteksi otomatis setiap harness yang ada (Claude Code, Codex, Antigravity CLI, dan Cursor semuanya didukung, di balik lapisan HarnessAdapter) sehingga Anda mendapatkan memori terpadu di keempatnya tanpa konfigurasi tambahan. Pada tingkat LLM, ia juga mengkonsolidasi: memori baru yang menduplikasi yang sudah ada dilewati, dan versi lebih baru dari fakta yang berkembang menandai catatan lama superseded_by (disimpan + diturunkan dalam pengingatan, tidak pernah dihapus) β€” aman dari kegagalan, sehingga panggilan yang salah tidak pernah menghilangkan memori yang berbeda (CAIRN_CONSOLIDATE=0 untuk menonaktifkan). Ditambah alat remember yang digerakkan agen untuk memori yang dikurasi dan bernilai tinggi.
  • Pengambilan menggabungkan BM25 + vektor semantik dengan Reciprocal Rank Fusion, menerapkan peningkatan graf opsional, dan menurun secara anggun ke hanya kata kunci ketika tidak ada model embedding yang tersedia β€” sehingga pengingatan tidak pernah mati diam-diam. Peringkat ulang cross-encoder opsional menambah presisi.
  • Kecerdasan hibrida: embedding lokal offline (FastEmbed / nomic-embed-text-v1.5 secara default) langsung tersedia β€” kuat sendiri dan dalam fusi hibrida (dengan nomic, hanya-vektor mengungguli BM25 bahkan pada giliran pendek; lihat tolok ukur). Atur CAIRN_EMBED_MODEL untuk memilih model FastEmbed lain, atau jalankan CAIRN_EMBEDDER=ollama / tingkat cloud untuk melangkah lebih jauh.
  • Memori temporal: catatan dapat membawa frontmatter valid_from/valid_until/superseded_by. Pengingatan sadar validitas β€” ia menurunkan secara lunak fakta yang digantikan dan kedaluwarsa (fakta saat ini menang) tanpa pernah menyembunyikannya (non-lossy), dan menganotasi status setiap hasil (current/superseded/expired/not_yet_valid) ditambah jangkar as_of sehingga agen dapat bernalar sepanjang waktu. Tidak aktif untuk catatan tanpa bidang validitas.
  • Pengingatan sadar asal: catatan membawa asal project/harness, dan pengingatan meningkatkan memori proyek Anda saat ini (non-lossy β€” hasil lintas proyek tetap muncul, ditandai [from: <project>]). Berikan --project <repo> untuk menargetkan repo lain, atau --scope project untuk menyaring keras hanya ke yang saat ini.

Menggunakannya secara langsung

Plugin adalah jalur termudah, tetapi agentcairn hanyalah sebuah paket β€” gunakan tanpa Claude Code melalui server MCP sesuai permintaan (untuk host MCP apa pun) atau CLI cairn:

uvx agentcairn                                       # on-demand MCP server for any MCP host
cairn ingest --vault ~/vault                         # distill recent agent sessions into the vault
cairn sweep  --vault ~/vault                          # ingest + reindex in one pass (cron-friendly)
cairn schedule install --vault ~/vault                # run sweep automatically every 30 min (launchd on macOS, crontab on Linux)
cairn recall "how did we fix the auth bug?"          # hybrid recall from the CLI
cairn savings                                        # how much context recall has saved you
cairn reindex ~/vault                                # rebuild the index from Markdown (always safe)
cairn doctor                                         # health-check the index

Konfigurasi

Semua pengaturan berada dalam satu berkas β€” ~/.agentcairn/config.toml β€” dengan variabel lingkungan sebagai pengganti (prioritas: bendera CLI > variabel lingkungan > berkas konfigurasi > default):

cairn config --init   # scaffold a fully-commented template (chmod 600)
cairn config          # show every setting's effective value and where it came from

Misalnya, mengaktifkan penilai memori LLM adalah dua baris tanpa komentar β€” tidak perlu ekspor shell (sapuan latar belakang plugin membaca berkas secara langsung):

judge = "anthropic"
anthropic_api_key = "sk-ant-..."

Agen yang didukung

agentcairn bekerja pada dua tingkat. Host plugin (Claude Code, Codex, dan Antigravity) mendapatkan plugin kelas satu β€” server MCP yang dibundel (pengingatan/pencarian/remember), keterampilan memori, dan (pada Claude Code dan Codex) kait sesi sekitar; cairn install <host> menginstal plugin dengan memanggil CLI host itu sendiri. Host MCP (yang lainnya) mendapatkan alat pengingatan/pencarian/remember yang sama melalui server MCP portabel; cairn install <host> menulis konfigurasi server MCP secara non-destruktif (server Anda yang lain dipertahankan, yang asli dicadangkan ke <config>.bak). Lemari tetap menjadi ~/agentcairn global tunggal, sehingga memori dibagikan di setiap host.

HostDukunganAtur denganPenangkapan sekitar
Claude Code🟒 Plugincairn install claude-codeβœ… pengingatan-di-awal + penangkapan-di-akhir
Codex🟒 Plugincairn install codex◐ pengingatan/remember langsung; kait sekitar dibundel (memverifikasi) 1
CursorπŸ”Œ Server MCP + keterampilan + serapcairn install cursor◐ cairn sweep mendeteksi otomatis transkrip 2
Claude DesktopπŸ”Œ Server MCPcairn install claude-desktopβ€”
VS Code (Copilot)πŸ”Œ Server MCPcairn install vscodeβ€”
Gemini CLI 3πŸ”Œ Server MCPcairn install geminiβ€”
Antigravity🟒 Plugin + serapcairn install antigravity◐ cairn sweep mendeteksi otomatis transkrip 4
Host MCP lainnyaπŸ”Œ Server MCPuvx agentcairn (tempel cuplikan cairn install … --print)β€”

cairn install merutekan berdasarkan jenis host secara otomatis:

cairn install                 # detect installed hosts + preview (writes nothing)
cairn install codex           # install the Codex plugin (shells to `codex plugin …`; strips any stale MCP block from ~/.codex/config.toml)
cairn install antigravity --source ./plugin  # install the Antigravity plugin from a local checkout (see note)
cairn install cursor          # write MCP config + install the memory skill for Cursor
cairn install --all           # configure every detected host
cairn install codex --source /path/to/agentcairn  # use a local checkout instead of the marketplace

Host MCP menerima entri JSON mcpServers (VS Code menggunakan kunci servers-nya). Host plugin (Claude Code, Codex, Antigravity) menginstal plugin melalui CLI host β€” server MCP dibundel dalam plugin dan tidak memerlukan entri konfigurasi terpisah. Jika Anda sebelumnya menggunakan cairn install antigravity untuk menulis entri MCP ke ~/.gemini/config/mcp_config.json, menjalankan ulang cairn install antigravity menghapus entri usang itu secara otomatis.

Tolok ukur yang diukur

Kami mengukur agentcairn dengan cara yang kami inginkan untuk mengukur sistem memori β€” dapat direproduksi, dengan ablasi, dan tanpa satu angka judul pilihan. Harness (benchmarks/) menjalankan LongMemEval-S dan LoCoMo melalui pengunduh versi yang disematkan (dataset tidak pernah disertakan), menilai pengambilan secara deterministik (recall/nDCG@k, MRR β€” tanpa perlu kunci API, berjalan di CI pada perlengkapan sintetis), dan menawarkan lapisan QA yang dinilai LLM secara opsional.

Pengambilan β€” LoCoMo

Set LoCoMo penuh, tingkat giliran, rata-rata makro, FastEmbed nomic-embed-text-v1.5 (penyemat default):

lenganrecall@5recall@10MRR
Hanya BM250.5270.6040.459
Hanya vektor0.5360.6370.433
hibrida (RRF)0.5620.6480.477
hibrida + peningkatan graf0.5620.6480.477
hibrida + peringkat ulang0.6620.7350.608

Apa yang kami baca dari ini β€” dan katakan dengan lantang:

  • Hibrida mengalahkan lengan mana pun sendiri β€” fusi RRF sepadan.
  • Peringkat ulang cross-encoder adalah pengungkit terbesar (+0.10 recall@5 dibanding hibrida); kekhawatiran "pergeseran domain ms-marco mungkin merugikan" tidak terwujud pada data percakapan.
  • Default penyemat sekarang berfungsi dengan baik β€” dengan nomic, hanya-vektor mengungguli BM25 (0.536 vs 0.527); beralih dari default bge-small lama (yang tertinggal di 0.483) menutup celah. Sapuan FastEmbed 5-model menentukan pilihan β€” nomic (768-d) menang dalam kualitas per dimensi; model 1024-d yang lebih besar tidak mengalahkannya. Tabel lengkap: benchmarks/README.md.
  • peningkatan graf tidak aktif pada korpora ini β€” LoCoMo/LongMemEval tidak memiliki graf [[wikilink]] asli, jadi peningkatan tidak memiliki apa pun untuk dipicu. Ini untuk lemari yang benar-benar saling tertaut, bukan log obrolan, dan kami tidak berpura-pura sebaliknya.

Pengambilan β€” LongMemEval-S

Set lengkap 500 instans β€” tugas yang lebih mudah dengan sesi bukti yang terpisah dengan baik. Tingkat sesi adalah granularitas yang dilaporkan oleh penelitian sebelumnya; tingkat giliran adalah irisan yang lebih halus dan mengungkap korpus:

lengansesi r@5sesi MRRgiliran r@5giliran r@10giliran MRR
Hanya BM250.9200.9180.6800.7910.638
Hanya vektor0.9360.9160.5070.6920.454
Hibrida (RRF)0.9540.9380.6400.7980.544
Hibrida + perangking ulang0.9690.9630.7880.8910.716

Bacalah dengan jujur:

  • Recall@5 sesi kami 0.969 sejajar dengan β‰ˆ0.95 dari penelitian sebelumnya pada set 500 pertanyaan lengkap yang sama β€” dan pada skala penuh, ini mendiskriminasi (0.920 BM25 β†’ 0.969 perangking ulang) alih-alih menjenuhkan seperti yang terjadi pada sampel kecil.
  • Perangking ulang kembali menjadi pengungkit terbesar β€” giliran r@5 0.640 β†’ 0.788, sesi r@5 0.954 β†’ 0.969.
  • Tingkat giliran mengungkap korpus: di sini hanya BM25 (0.680) mengungguli hibrida RRF (0.640) karena hanya vektor lemah pada rentang bukti giliran tunggal ini (0.507); perangking ulanglah yang mendorong default ke depan. (Bandingkan dengan LoCoMo, di mana hanya vektor sedikit mengungguli BM25.)

Efisiensi konteks

Seberapa kecil konteks yang di-recall agentcairn dibandingkan riwayat lengkap yang seharusnya Anda bawa ke model? Konfigurasi default (hibrida + perangking ulang, k=10):

datasetkuerirata-rata tumpukan jeramirata-rata recall (k=10)pengurangan konteks
LoCoMo (3 percakapan)49725.646 token529 token51,1Γ— rata-rata / 50,3Γ— median
LongMemEval-S (500 penuh)470136.552 token2.207 token64,7Γ— rata-rata / 61,6Γ— median

Estimasi (~4 karakter/token), bukan biaya yang ditagih; "tumpukan jerami" = riwayat terindeks lengkap, "recall" = potongan top-k yang dikembalikan. Ini mengukur ukuran konteks, terlepas dari kualitas pengambilan.

Akurasi QA

Angka akurasi QA (dinilai LLM) juga tersedia, tetapi menggunakan penilai Anthropic alih-alih GPT-4o dari makalah, sehingga tidak dapat dibandingkan dengan papan peringkat yang dipublikasikan β€” hanya valid untuk sinyal ablasi relatif. Lihat benchmarks/README.md untuk cara menjalankannya dan membaca angkanya.

Peta jalan

  • v1 β€” selesai. Loop inti: penelanan transkrip β†’ redaksi β†’ Markdown β†’ indeks DuckDB yang dapat dibangun ulang β†’ recall hibrida; server MCP + CLI; redaksi rahasia; embedding lokal; harness tolok ukur yang dapat direproduksi.
  • v1.1 β€” selanjutnya, diprioritaskan berdasarkan tolok ukur di atas:
    • βœ… Perangking ulang aktif secara default β€” pengungkit pengambilan terukur terbesar; CAIRN_RERANK=0 untuk menonaktifkan. (dirilis)
    • Tingkat embedding Ollama β€” βœ… model lokal melalui CAIRN_EMBEDDER=ollama (CAIRN_EMBED_MODEL/OLLAMA_HOST); cloud (OpenAI/Voyage) masih tertunda.
    • βœ… Validitas bi-temporal β€” frontmatter valid_from/valid_until/superseded_by; recall secara lunak menurunkan fakta yang digantikan/kadaluarsa (non-lossy β€” tidak pernah disembunyikan) dan menganotasi kekinian setiap hasil + jangkar as_of, sehingga fakta saat ini menang dan agen dapat bernalar sepanjang waktu. (dirilis)
    • HNSW dalam memori untuk latensi pengambilan vault besar.
  • v2 β€” ◐ Plugin Obsidian (agentcairn-obsidian) β€” tampilan Memori asli vault (daftar + asal-usul + kekinian + grafik) untuk membaca/menavigasi memori Anda di Obsidian; (MVP dirilis; recall semantik tetap di CLI/MCP). Sinkronisasi cloud MotherDuck, ekstraksi entitas LLM opsional masih tertunda.

Pengembangan

agentcairn menggunakan uv secara eksklusif untuk manajemen dependensi dan perkakas.

Jangan gunakan pip, poetry, atau lingkungan virtual global.

# First-time setup
uv sync                         # create .venv and install all deps (including dev)
uv run pre-commit install       # install git hooks (ruff + pytest run on every commit)

# Daily use
uv run pytest                   # run the test suite
uv run cairn --help             # run the CLI
uvx agentcairn                  # run the installed tool ephemerally (as the MCP server does)

# Formatting and linting
uv run ruff format .            # format all Python files
uv run ruff check --fix .       # lint with auto-fix
uv run pre-commit run --all-files

# Benchmarks (offline retrieval metrics need no API key)
uv run pytest benchmarks/tests/                                      # offline synthetic-fixture suite
PYTHONPATH=benchmarks uv run --group bench python -m cairn_bench.run --dataset locomo

Server MCP diluncurkan melalui uvx agentcairn β€” tidak perlu instalasi global.

Lisensi

Lisensi Apache 2.0 β€” permisif, dengan pemberian paten eksplisit. Hak Cipta Β© 2026 Charles C. Figueiredo.

Footnotes

  1. The Plugin Codex terinstal dan server MCP yang dibundel (pengingatan/pencarian/remember) diverifikasi langsung di Codex. Kait sesi sekitar (pengingatan-di-awal, penangkapan-di-akhir) dikirimkan dalam plugin dan menggunakan skema kait Codex yang didokumentasikan, tetapi perilaku mereka di Codex belum dikonfirmasi ujung-ke-ujung; penangkapan juga terjadi di luar jalur melalui cairn sweep terlepas. ↩

  2. Cursor tidak memiliki kait plugin, jadi penangkapan sekitar dilakukan di luar jalur melalui cairn sweep (sumber: basis data SQLite globalStorage/state.vscdb global Cursor, tabel cursorDiskKV, pengguna "bubbles"). Cursor tetap menjadi host MCP untuk keluaran (cairn install cursor β†’ ~/.cursor/mcp.json); tidak ada plugin Cursor. cairn install cursor juga menginstal keterampilan using-agentcairn-memory (panduan pengingatan/ingat) ke ~/.cursor/skills/using-agentcairn-memory/SKILL.md. ↩

  3. Gemini Penyerapan transkrip CLI (konsumen) tidak didukung β€” Google menghentikan Gemini CLI (batas konsumen 2026-06-18) demi Antigravity CLI, yang diserap agentcairn sebagai gantinya. cairn install gemini (pengkabelan server MCP) tetap valid untuk host berbasis Gemini apa pun yang menggunakan MCP. ↩

  4. The Plugin Antigravity membundel server MCP + keterampilan memori; cairn install antigravity --source <dir> menginstalnya melalui agy plugin install dan menghapus entri mcpServers.agentcairn usang dari ~/.gemini/config/mcp_config.json. Catatan: agy plugin install menerima direktori lokal atau pasar terdaftar (bukan repo git), jadi arahkan --source ke direktori plugin/ checkout kloning untuk saat ini. Antigravity tidak memiliki kait plugin yang diakui, jadi penangkapan sekitar dilakukan di luar jalur melalui cairn sweep (jalur: ~/.gemini/antigravity-cli/brain/<uuid>/.system_generated/logs/transcript.jsonl). ↩