agentcairn MCP Server

chính thức

Bộ nhớ agent ưu tiên cục bộ: kho Obsidian dạng Markdown thuần là nguồn dữ liệu chính xác, với chỉ mục DuckDB có thể xây dựng lại để truy xuất kết hợp BM25 + vector + đồ thị.

GitHub
1

Tài liệu

🪨 agentcairn

CI Security PyPI Python License: Apache-2.0

Bộ nhớ cục bộ ưu tiên cho tác nhân AI — mà bạn thực sự có thể đọc, chỉnh sửa và sở hữu.

cairn  /kɛən/  · danh từ — một chồng đá được dựng lên để đánh dấu đường mòn hoặc một nơi đáng ghi nhớ, để lại cho người đến sau.

agentcairn cung cấp cho tác nhân lập trình của bạn bộ nhớ bền vững, chất lượng cao — nhưng thay vì khóa nó trong cơ sở dữ liệu mờ đục hoặc dịch vụ đám mây, ký ức của bạn tồn tại dưới dạng Markdown thuần túy trong kho Obsidian mà bạn sở hữu. Một chỉ mục DuckDB nhanh, có thể xây dựng lại nằm trên cùng để truy xuất. Mở kho của bạn, đọc những gì tác nhân đã ghi nhớ, sửa một sự kiện sai bằng tay, hoặc thêm ghi chú của riêng bạn — và tác nhân sẽ tiếp nhận tất cả.

Tại sao agentcairn khác biệt

Hầu hết các hệ thống bộ nhớ tác nhân biến cơ sở dữ liệu hoặc kho lưu trữ đám mây thành nguồn sự thật và coi tệp (nếu có) là xuất một chiều. agentcairn đảo ngược điều đó:

  • 📂 Kho của bạn là nguồn sự thật — không phải bản xuất. Bộ nhớ là Markdown con người có thể đọc được với frontmatter và [[wikilinks]]. Chỉnh sửa nó trong Obsidian; chỉ mục tôn trọng các chỉnh sửa của bạn.
  • ♻️ Chỉ mục có thể dùng một lần. DuckDB là bộ nhớ đệm có thể xây dựng lại (cairn reindex). Bộ nhớ của bạn tồn tại qua nâng cấp mô hình, chỉ mục hỏng, thay đổi lược đồ, hoặc gỡ cài đặt công cụ — không mất dữ liệu, vì sự thật chỉ là các tệp trên đĩa.
  • 🧠 Không mất mát theo thiết kế. Ghi chú đầy đủ luôn được giữ lại. Tinh chế chỉ thêm các ghi chú dẫn xuất liên kết trở lại nguồn — nó không bao giờ âm thầm loại bỏ các sự kiện mà nó không nghĩ đến việc trích xuất tại thời điểm ghi.
  • 🔒 Biên tập lại trước mỗi lần ghi. Bí mật được lọc sạch (regex + entropy + phát hiện thông tin xác thực URL) trước khi bất cứ thứ gì — nội dung, tiêu đề, hoặc thẻ — đến được kho văn bản thuần túy. Chúng tôi ghi các tệp bạn có thể đọc, vì vậy chúng tôi coi rò rỉ thông tin xác thực là chế độ thất bại tồi tệ nhất.
  • 🕸️ Đồ thị tri thức miễn phí, xác định. [[wikilinks]] và frontmatter của bạn chính là đồ thị — không cần trích xuất LLM, không có thực thể ảo giác.
  • 🪶 Không daemon, không cơ sở dữ liệu ngoài. Một tệp DuckDB nhúng duy nhất thực hiện tìm kiếm vector ngữ nghĩa, toàn văn BM25, và duyệt đồ thị. Không có máy chủ luôn bật, không cần Neo4j/Postgres/Qdrant, không yêu cầu khóa đám mây — chỉ cần CLI cairn và máy chủ MCP theo yêu cầu.
  • 🔍 Đo lường trung thực. Một bộ kiểm tra LongMemEval-S + LoCoMo có thể tái tạo được đóng gói trong benchmarks/ — với các con số thực, cắt bỏ, và các cảnh báo rõ ràng thay vì một tiêu đề được chọn lọc (xem bên dưới).

Cài đặt

Cách dễ nhất để sử dụng agentcairn là plugin cho Claude Code hoặc Codex — một lần cài đặt kết nối máy chủ MCP, bộ nhớ nền (nhớ lại khi bắt đầu phiên, ghi lại khi kết thúc phiên), kỹ năng bộ nhớ, và lệnh slash (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

Khi cài đặt, bạn chọn đường dẫn kho (mặc định ~/agentcairn); nó được tự động tạo trong phiên đầu tiên — không cần thiết lập Obsidian. Từ đó trở đi, agentcairn hiển thị bộ nhớ liên quan khi bắt đầu mỗi phiên, chắt lọc mỗi phiên vào kho của bạn, và cung cấp cho bạn /agentcairn:recall, /remember, /memory, /savings, và /ingest. Không cần cài đặt pip — plugin chạy gói đã xuất bản qua uvx.

Không dùng Claude Code hoặc Codex? agentcairn cũng là một máy chủ MCP + CLI độc lập cho bất kỳ máy chủ nào — xem Sử dụng trực tiếp.

Cách thức hoạt động

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
  • Ghi lại đọc bản ghi phiên của bộ khai thác tác nhân của bạn (chỉ thêm vào, đã có trên đĩa) ngoài băng tần — mạnh mẽ theo thiết kế, không có hook trực tiếp mong manh — sau đó biên tập lại → loại bỏ trùng lặp → đánh giá (độ bền ngữ nghĩa; tùy chọn chắt lọc LLM qua CAIRN_JUDGE=anthropic) → kiểm soát → chắt lọc vào kho, không mất mát. cairn sweep tự động phát hiện mọi bộ khai thác hiện có (Claude Code, Codex, Antigravity CLI, và Cursor đều được hỗ trợ, đằng sau một đường nối HarnessAdapter) để bạn có bộ nhớ thống nhất trên cả bốn mà không cần cấu hình thêm. Ở cấp LLM, nó cũng hợp nhất: một bộ nhớ mới trùng lặp với bộ nhớ hiện có sẽ bị bỏ qua, và phiên bản mới hơn của một sự kiện đang phát triển đánh dấu ghi chú cũ hơn superseded_by (được giữ + giảm cấp trong nhớ lại, không bao giờ xóa) — an toàn, để một lệnh gọi sai không bao giờ làm mất một bộ nhớ riêng biệt (CAIRN_CONSOLIDATE=0 để vô hiệu hóa). Cộng với công cụ remember do tác nhân điều khiển cho các ký ức được tuyển chọn, giá trị cao.
  • Truy xuất kết hợp BM25 + vector ngữ nghĩa với Reciprocal Rank Fusion, áp dụng tăng cường đồ thị tùy chọn, và suy giảm nhẹ nhàng xuống chỉ từ khóa khi không có mô hình nhúng — vì vậy nhớ lại không bao giờ âm thầm chết. Một bộ xếp hạng lại cross-encoder tùy chọn thêm độ chính xác.
  • Trí tuệ lai: nhúng cục bộ ngoại tuyến (FastEmbed / nomic-embed-text-v1.5 theo mặc định) ngay khi mở hộp — mạnh mẽ một mình và trong kết hợp lai (với nomic, chỉ vector vượt trội BM25 ngay cả trên các lượt ngắn; xem điểm chuẩn). Đặt CAIRN_EMBED_MODEL để chọn mô hình FastEmbed khác, hoặc chạy CAIRN_EMBEDDER=ollama / cấp đám mây để tiến xa hơn.
  • Bộ nhớ thời gian: ghi chú có thể mang frontmatter valid_from/valid_until/superseded_by. Nhớ lại nhận biết tính hợp lệ — nó giảm cấp nhẹ các sự kiện bị thay thế và hết hạn (sự kiện hiện tại thắng) mà không bao giờ ẩn chúng (không mất mát), và chú thích trạng thái của mỗi kết quả (current/superseded/expired/not_yet_valid) cộng với neo as_of để tác nhân có thể suy luận theo thời gian. Trơ đối với các ghi chú không có trường hợp lệ.
  • Nhớ lại nhận biết nguồn gốc: ghi chú mang nguồn gốc project/harness, và nhớ lại tăng cường ký ức của dự án hiện tại của bạn (không mất mát — các kết quả liên dự án vẫn xuất hiện, được đánh dấu [from: <project>]). Truyền --project <repo> để nhắm mục tiêu kho lưu trữ khác, hoặc --scope project để lọc cứng chỉ cho dự án hiện tại.

Sử dụng trực tiếp

Plugin là con đường dễ nhất, nhưng agentcairn chỉ là một gói — sử dụng nó không cần Claude Code qua máy chủ MCP theo yêu cầu (cho bất kỳ máy chủ MCP nào) hoặc 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

Cấu hình

Tất cả cài đặt nằm trong một tệp — ~/.agentcairn/config.toml — với biến môi trường làm ghi đè (ưu tiên: cờ CLI > biến môi trường > tệp cấu hình > mặc định):

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

Ví dụ, kích hoạt trình đánh giá bộ nhớ LLM là hai dòng không chú thích — không cần xuất shell (quét nền của plugin đọc trực tiếp tệp):

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

Tác nhân được hỗ trợ

agentcairn hoạt động ở hai cấp độ. Máy chủ plugin (Claude Code, Codex, và Antigravity) nhận được plugin hạng nhất — máy chủ MCP đi kèm (nhớ lại/tìm kiếm/remember), kỹ năng bộ nhớ, và (trên Claude Code và Codex) hook phiên nền; cairn install <host> cài đặt plugin bằng cách gọi CLI của chính máy chủ. Máy chủ MCP (mọi thứ khác) nhận được cùng các công cụ nhớ lại/tìm kiếm/remember qua máy chủ MCP di động; cairn install <host> ghi cấu hình máy chủ MCP không phá hủy (các máy chủ khác của bạn được giữ nguyên, bản gốc được sao lưu vào <config>.bak). Kho vẫn là một ~/agentcairn toàn cục duy nhất, vì vậy bộ nhớ được chia sẻ trên mọi máy chủ.

Máy chủHỗ trợThiết lập vớiGhi lại nền
Claude Code🟢 Plugincairn install claude-code✅ nhớ lại-khi-bắt-đầu + ghi lại-khi-kết-thúc
Codex🟢 Plugincairn install codex◐ nhớ lại/remember trực tiếp; hook nền đi kèm (đang xác minh) 1
Cursor🔌 Máy chủ MCP + kỹ năng + nhậpcairn install cursor◐ cairn sweep tự động phát hiện bản ghi 2
Claude Desktop🔌 Máy chủ MCPcairn install claude-desktop—
VS Code (Copilot)🔌 Máy chủ MCPcairn install vscode—
Gemini CLI 3🔌 Máy chủ MCPcairn install gemini—
Antigravity🟢 Plugin + nhậpcairn install antigravity◐ cairn sweep tự động phát hiện bản ghi 4
Bất kỳ máy chủ MCP nào khác🔌 Máy chủ MCPuvx agentcairn (dán đoạn cairn install … --print)—

cairn install định tuyến theo loại máy chủ tự động:

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

Máy chủ MCP nhận mục JSON mcpServers (VS Code sử dụng khóa servers của nó). Máy chủ plugin (Claude Code, Codex, Antigravity) cài đặt plugin qua CLI máy chủ — máy chủ MCP được đóng gói trong plugin và không cần mục cấu hình riêng. Nếu trước đây bạn đã sử dụng cairn install antigravity để ghi mục MCP vào ~/.gemini/config/mcp_config.json, chạy lại cairn install antigravity sẽ tự động xóa mục cũ đó.

Điểm chuẩn đã đo

Chúng tôi đánh giá điểm chuẩn agentcairn theo cách chúng tôi muốn một hệ thống bộ nhớ được đo lường — có thể tái tạo, với cắt bỏ, và không có một con số tiêu đề được chọn lọc. Bộ khai thác (benchmarks/) chạy LongMemEval-S và LoCoMo qua trình tải xuống được ghim phiên bản (bộ dữ liệu không bao giờ được cung cấp), chấm điểm truy xuất xác định (recall/nDCG@k, MRR — không cần khóa API, chạy trong CI trên vật cố tổng hợp), và cung cấp lớp QA do LLM đánh giá tùy chọn.

Truy xuất — LoCoMo

Bộ LoCoMo đầy đủ, cấp lượt, trung bình vĩ mô, FastEmbed nomic-embed-text-v1.5 (trình nhúng mặc định):

nhánhrecall@5recall@10MRR
Chỉ BM250.5270.6040.459
chỉ vector0.5360.6370.433
lai (RRF)0.5620.6480.477
lai + tăng cường đồ thị0.5620.6480.477
lai + xếp hạng lại0.6620.7350.608

Những gì chúng tôi đọc được từ điều này — và nói to:

  • Lai đánh bại từng nhánh riêng lẻ — RRF fusion đáng giá.
  • Bộ xếp hạng lại cross-encoder là đòn bẩy lớn nhất (+0.10 recall@5 so với lai); lo lắng "dịch chuyển miền ms-marco có thể gây hại" đã không thành hiện thực trên dữ liệu hội thoại.
  • Trình nhúng mặc định hiện đã phát huy tác dụng — với nomic, chỉ vector vượt trội BM25 (0.536 so với 0.527); chuyển từ mặc định bge-small cũ (tụt lại ở 0.483) đã thu hẹp khoảng cách. Một đợt quét 5 mô hình FastEmbed đã quyết định lựa chọn — nomic (768-d) thắng về chất lượng trên mỗi chiều; các mô hình 1024-d lớn hơn không đánh bại nó. Bảng đầy đủ: benchmarks/README.md.
  • tăng cường đồ thị trơ trên các kho ngữ liệu này — LoCoMo/LongMemEval không có đồ thị [[wikilink]] gốc, vì vậy tăng cường không có gì để kích hoạt. Nó dành cho các kho liên kết thực, không phải nhật ký trò chuyện, và chúng tôi không giả vờ khác đi.

Truy xuất — LongMemEval-S

Bộ 500 phiên bản đầy đủ — một tác vụ dễ hơn với các phiên bằng chứng được tách biệt rõ ràng. Cấp độ phiên là độ chi tiết mà các nghiên cứu trước đây báo cáo; cấp độ lượt là lát cắt mịn hơn, bộc lộ đặc tính của kho ngữ liệu:

nhánhphiên r@5phiên MRRlượt r@5lượt r@10lượt MRR
Chỉ BM250.9200.9180.6800.7910.638
Chỉ vector0.9360.9160.5070.6920.454
Kết hợp (RRF)0.9540.9380.6400.7980.544
Kết hợp + xếp hạng lại0.9690.9630.7880.8910.716

Đọc một cách trung thực:

  • Điểm recall@5 phiên 0.969 của chúng tôi nằm ngay cạnh mức ≈0.95 của nghiên cứu trước trên cùng bộ 500 câu hỏi đầy đủ — và ở quy mô đầy đủ, nó phân biệt (0.920 BM25 → 0.969 xếp hạng lại) thay vì bão hòa như cách một mẫu nhỏ thể hiện.
  • Bộ xếp hạng lại một lần nữa là đòn bẩy lớn nhất — lượt r@5 0.640 → 0.788, phiên r@5 0.954 → 0.969.
  • Cấp độ lượt bộc lộ đặc tính kho ngữ liệu: ở đây, chỉ BM25 (0.680) đánh bại kết hợp RRF (0.640) vì chỉ vector yếu trên các đoạn bằng chứng đơn lượt này (0.507); bộ xếp hạng lại là thứ kéo mặc định lên trước. (Trái ngược với LoCoMo, nơi chỉ vector nhỉnh hơn BM25.)

Hiệu quả ngữ cảnh

Ngữ cảnh mà agentcairn gợi nhắc nhỏ hơn bao nhiêu so với toàn bộ lịch sử mà bạn thường mang vào mô hình? Cấu hình mặc định (kết hợp + xếp hạng lại, k=10):

tập dữ liệutruy vấnđống cỏ khô trung bìnhgợi nhắc trung bình (k=10)giảm ngữ cảnh
LoCoMo (3 hội thoại)49725,646 tok529 tok51.1× trung bình / 50.3× trung vị
LongMemEval-S (đầy đủ 500)470136,552 tok2,207 tok64.7× trung bình / 61.6× trung vị

Ước tính (~4 ký tự/tok), không phải chi phí được tính hóa đơn; "đống cỏ khô" = toàn bộ lịch sử đã lập chỉ mục, "gợi nhắc" = các đoạn top-k được trả về. Nó đo kích thước ngữ cảnh, độc lập với chất lượng truy xuất.

Độ chính xác QA

Các con số độ chính xác QA (do LLM đánh giá) cũng có sẵn, nhưng sử dụng một giám khảo Anthropic thay vì GPT-4o của các bài báo, vì vậy chúng không thể so sánh với các bảng xếp hạng đã công bố — chỉ có giá trị cho tín hiệu cắt bỏ tương đối. Xem benchmarks/README.md để biết cách chạy và cách đọc các con số.

Lộ trình

  • v1 — đã hoàn thành. Vòng lặp cốt lõi: nhập bản ghi → biên tập lại → Markdown → chỉ mục DuckDB có thể xây dựng lại → gợi nhắc kết hợp; máy chủ MCP + CLI; biên tập bí mật; embedding cục bộ; bộ kiểm tra điểm chuẩn có thể tái tạo.
  • v1.1 — tiếp theo, ưu tiên theo điểm chuẩn trên:
    • ✅ Bật xếp hạng lại theo mặc định — đòn bẩy truy xuất đo được lớn nhất; CAIRN_RERANK=0 để tắt. (đã xuất xưởng)
    • Bậc embedding Ollama — ✅ mô hình cục bộ qua CAIRN_EMBEDDER=ollama (CAIRN_EMBED_MODEL/OLLAMA_HOST); đám mây (OpenAI/Voyage) vẫn đang chờ.
    • ✅ Hiệu lực hai thời điểm — frontmatter valid_from/valid_until/superseded_by; gợi nhắc giảm nhẹ ưu tiên các sự kiện đã thay thế/hết hạn (không mất mát — không bao giờ ẩn) và chú thích tính thời sự của mỗi kết quả + một neo as_of, để sự kiện hiện tại thắng và tác nhân có thể suy luận theo thời gian. (đã xuất xưởng)
    • HNSW trong bộ nhớ cho độ trễ truy xuất kho lưu trữ lớn.
  • v2 — ◐ Plugin Obsidian (agentcairn-obsidian) — một khung nhìn Bộ nhớ gốc kho lưu trữ (danh sách + nguồn gốc + tính thời sự + đồ thị) để đọc/điều hướng bộ nhớ của bạn trong Obsidian; (MVP đã xuất xưởng; gợi nhắc ngữ nghĩa vẫn ở CLI/MCP). Đồng bộ đám mây MotherDuck, trích xuất thực thể LLM tùy chọn vẫn đang chờ.

Phát triển

agentcairn sử dụng uv độc quyền cho quản lý phụ thuộc và công cụ.

Không sử dụng pip, poetry, hoặc môi trường ảo toàn cục.

# 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

Máy chủ MCP được khởi chạy qua uvx agentcairn — không cần cài đặt toàn cục.

Giấy phép

Giấy phép Apache 2.0 — cấp phép rộng rãi, với một cấp bằng sáng chế rõ ràng. Bản quyền © 2026 Charles C. Figueiredo.

Footnotes

  1. The Cài đặt plugin Codex và máy chủ MCP đi kèm của nó (nhớ lại/tìm kiếm/remember) được xác minh trực tiếp trong Codex. Các hook phiên nền (nhớ lại-khi-bắt-đầu, ghi lại-khi-kết-thúc) được đóng gói trong plugin và sử dụng lược đồ hook được ghi lại của Codex, nhưng hành vi trên Codex của chúng chưa được xác nhận đầu cuối; ghi lại cũng xảy ra ngoài băng tần qua cairn sweep bất kể. ↩

  2. Cursor không có hook plugin, vì vậy ghi lại nền là ngoài băng tần qua cairn sweep (nguồn: cơ sở dữ liệu SQLite globalStorage/state.vscdb toàn cục của Cursor, bảng cursorDiskKV, người dùng "bubbles"). Cursor vẫn là máy chủ MCP cho đầu ra (cairn install cursor → ~/.cursor/mcp.json); không có plugin Cursor. cairn install cursor cũng cài đặt kỹ năng using-agentcairn-memory (hướng dẫn nhớ lại/ghi nhớ) vào ~/.cursor/skills/using-agentcairn-memory/SKILL.md. ↩

  3. Gemini Nhập bản ghi CLI (người tiêu dùng) không được hỗ trợ — Google đang ngừng Gemini CLI (người tiêu dùng cắt 2026-06-18) để chuyển sang Antigravity CLI, mà agentcairn nhập thay thế. cairn install gemini (kết nối máy chủ MCP) vẫn hợp lệ cho bất kỳ máy chủ dựa trên Gemini nào nói MCP. ↩

  4. The Plugin Antigravity đi kèm máy chủ MCP + kỹ năng bộ nhớ; cairn install antigravity --source <dir> cài đặt nó qua agy plugin install và xóa mọi mục mcpServers.agentcairn cũ khỏi ~/.gemini/config/mcp_config.json. Lưu ý: agy plugin install nhận thư mục cục bộ hoặc marketplace đã đăng ký (không phải kho git), vì vậy hiện tại hãy trỏ --source vào thư mục plugin/ của bản sao đã clone. Antigravity không có hook plugin được công nhận, vì vậy ghi lại nền là ngoài băng tần qua cairn sweep (đường dẫn: ~/.gemini/antigravity-cli/brain/<uuid>/.system_generated/logs/transcript.jsonl). ↩