agentcairn

Một bộ nhớ bền vững duy nhất cho các tác nhân lập trình được hỗ trợ.
Kho Markdown của bạn là nguồn chính thức. DuckDB là bộ đệm truy xuất có thể thay thế.

Trang web · PyPI · Bổ trợ Obsidian · Điểm chuẩn

Một cairn đánh dấu con đường cho người đi sau. agentcairn làm điều đó cho các tác nhân lập trình: nó thu thập ngữ cảnh bền vững từ các công cụ bạn sử dụng, lưu trữ dưới dạng Markdown có thể kiểm tra với nguồn gốc rõ ràng, và chỉ truy hồi những phần liên quan nhất khi một tác nhân khác cần chúng.

Bằng chứng bạn có thể kiểm tra

Bộ nhớ không bị ẩn sau bảng điều khiển quản trị hay cơ sở dữ liệu lưu trữ. Bổ trợ agentcairn-obsidian riêng biệt đọc cùng các tệp Markdown như các tác nhân và hiển thị nguồn gốc, tính cập nhật, mức độ quan trọng, sự thay thế, và các liên kết related:.

_{Một kho agentcairn thực tế trong Obsidian. Danh sách là một chế độ xem trên các tệp—không phải là một kho lưu trữ bộ nhớ thứ hai.}

Ảnh chụp nhanh dogfood · 2026-07-15. Qua 417 lần truy hồi cục bộ, kho của người duy trì đã trả về ngữ cảnh 262× smaller so với việc tải toàn bộ kho mỗi lần—ước tính 136.6M tokens of full-vault context avoided tổng cộng. Số token sử dụng xấp xỉ bốn ký tự mỗi token. Đây không phải là khoản tiết kiệm token được tính phí, và agentcairn không gửi bất kỳ dữ liệu đo từ xa nào.

Cài đặt

Con đường ngắn nhất là một plugin hạng nhất. Nó gói gọn máy chủ MCP, kỹ năng bộ nhớ, và các móc nối môi trường cụ thể của máy chủ—không cần cài đặt gói agentcairn riêng. Plugin khởi chạy qua uvx, vì vậy hãy cài uv trước nếu uvx --version chưa có sẵn.

Claude Code

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

Claude Code nhận được truy hồi theo phạm vi dự án mỗi lượt, thu thập phiên/nén, và các lệnh /agentcairn:recall, /agentcairn:remember, /agentcairn:memory, /agentcairn:savings, và /agentcairn:ingest.

Codex

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

Codex nhận được các công cụ MCP và kỹ năng bộ nhớ được gói kèm, truy hồi SessionStart được xác minh trực tiếp, và thu thập SessionEnd với cairn sweep làm cơ chế dự phòng ngoài băng tần.

Thiết lập có hỗ trợ của tác nhân

Đã sử dụng skills.sh hoặc quy trình làm việc find-skills? Cài đặt trợ lý thiết lập công khai:

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

Sau đó hỏi tác nhân của bạn: Use $agentcairn-setup to preview, install, and verify AgentCairn for this coding agent.

Điều này chỉ cài đặt hướng dẫn thiết lập—không phải thời gian chạy AgentCairn, máy chủ MCP, plugin, hoặc các móc nối. Trợ lý ủy quyền những thay đổi đó cho trình cài đặt gốc ưu tiên xem trước của AgentCairn và xác minh tích hợp kết quả. Các lệnh plugin Claude Code và Codex ở trên vẫn là con đường ngắn nhất.

Kho mặc định là ~/agentcairn và được tạo khi sử dụng lần đầu. Một kho trống mới chưa có gì hữu ích để truy hồi, vì vậy hãy chứng minh toàn bộ vòng lặp một cách rõ ràng:

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 ghi ghi chú Markdown và mục chỉ mục cùng nhau, vì vậy truy hồi ngay lập tức là một phần của hợp đồng. Lần chạy cục bộ đầu tiên có thể tải xuống và làm ấm các mô hình nhúng/xếp hạng lại đã cấu hình.

Hợp đồng

Cách hoạt động

• Thu thập: các móc nối máy chủ cải thiện tính tức thời; cairn sweep đọc các kho lưu trữ bảng điểm được hỗ trợ ngoài băng tần làm cơ chế dự phòng bền vững. AgentCairn biên tập các thông tin xác thực được nhận diện, khử trùng lặp, lọc theo mức độ quan trọng, và chưng cất trước khi ghi văn bản thuần tự động.
• Đối chiếu: giao dịch đọc đầu tiên đưa chỉ mục phạm vi kho đồng bộ với Markdown. Một lần xây dựng lại thất bại giữ lại bộ đệm tốt cuối cùng và các tệp bền vững không bị ảnh hưởng.
• Truy hồi: BM25 và các vector ngữ nghĩa được kết hợp với Reciprocal Rank Fusion, sau đó tùy chọn xếp hạng lại. Các lỗi mô hình/nhà cung cấp hiển thị rõ ràng quay lại BM25 với chẩn đoán thay vì trả về các vector không tương thích.
• Ghi nhớ: công cụ MCP ghi một ghi chú Markdown và cập nhật chỉ mục một cách nguyên tử dưới một khóa ghi, làm cho một lần lưu thành công có thể truy hồi ngay lập tức.

Được thiết kế cho sự tin cậy

• Cục bộ mặc định. FastEmbed chạy cục bộ, máy chủ MCP sử dụng stdio, không có daemon hoặc cơ sở dữ liệu ngoài bắt buộc, và không có dữ liệu đo từ xa.
• Ranh giới rõ ràng. Kho đồng bộ chứa Markdown; theo mặc định, chỉ mục .duckdb có thể xây dựng lại nằm bên ngoài nó. Các liên kết tượng trưng của kho thoát khỏi thư mục gốc đã cấu hình bị từ chối.
• Hiệu chỉnh nhạy cảm với thời gian. valid_from, valid_until, và superseded_by giữ bằng chứng cũ hiển thị trong khi làm cho các sự kiện hiện tại xếp hạng đầu tiên.
• Đồ thị xác định. [[wikilinks]] và các hàng xóm cairn link tùy chọn tạo một đồ thị gốc Obsidian mà không yêu cầu LLM phát minh ra các thực thể.
• Truy hồi nhạy cảm với dự án. Dự án hiện tại được ưu tiên theo mặc định; các kết quả xuyên dự án vẫn có sẵn và được gắn nhãn. Truy hồi tự động được giới hạn theo dự án trừ khi bạn chọn rõ ràng tất cả các dự án.

Các tác nhân được hỗ trợ

Mọi máy chủ đều giải quyết cùng một kho đã cấu hình. cairn install xem trước các máy chủ được phát hiện mà không ghi. Các ghi cấu hình MCP ưu tiên sao lưu và bảo toàn các máy chủ không liên quan; các cài đặt plugin-máy chủ ủy quyền cho CLI của chính máy chủ đó.

Codex SessionStart đã được xác minh trực tiếp từ đầu đến cuối với agentcairn 0.24.2 / plugin 0.1.2. Việc gửi lệnh SessionEnd đã cài đặt và quét tách rời vượt qua các kiểm tra xử lý chính xác; cairn sweep vẫn là cơ chế dự phòng thu thập ngoài băng tần. Xem tích hợp OpenCode và tích hợp Hermes để biết chi tiết vòng đời gốc của chúng.

Sử dụng trực tiếp

Plugin là con đường dễ nhất, nhưng agentcairn cũng là một CLI độc lập và máy chủ MCP theo yêu cầu. Các cài đặt độc lập yêu cầu 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

Mang bộ nhớ của Claude Code theo bạn

Bộ nhớ tự động của Claude Code có thể gieo hạt cho kho dùng chung mà không thay đổi các tệp nguồn của nó. Lệnh xem trước chỉ kho lưu trữ hiện tại theo mặc định; thêm --apply để ghi các ghi chú đã biên tập và làm mới chỉ mục.

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

Việc nhập một chiều đọc MEMORY.md và các tệp Markdown chủ đề của nó—không bao giờ CLAUDE.md hoặc .claude/rules/. Các ghi chú được nhập giữ lại nguồn gốc Claude Code, dự án, và tệp nguồn. Khi một nguồn thay đổi, phiên bản trước vẫn có thể kiểm tra nhưng bị thay thế; khi một nguồn biến mất, phiên bản được nhập của nó hết hạn. Một sổ đăng ký .agentcairn/native-memory/ nhỏ bảo toàn vòng đời đó mà không lập chỉ mục nội dung nguồn hai lần. Sử dụng --source <dir> cho một thư mục bộ nhớ Claude tùy chỉnh, được quản lý, hoặc ghi đè phiên, hoặc --no-reindex khi xử lý hàng loạt nhập.

Ưu tiên một quy trình tạm thời:

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

Điểm chuẩn đo được

Kho lưu trữ đi kèm một bộ thử nghiệm LongMemEval-S + LoCoMo có thể tái tạo, được khóa theo phiên bản. Mặc định là nomic-embed-text-v1.5 cục bộ cộng với bộ xếp hạng lại cross-encoder.

Ngữ cảnh được trả về ở k=10 mặc định nhỏ hơn nhiều so với toàn bộ lịch sử được lập chỉ mục:

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

• Truy hồi không phải là độ chính xác QA. Các bảng này so sánh các nhánh truy hồi có kiểm soát, không phải chất lượng câu trả lời của người dùng cuối hoặc điểm số bảng xếp hạng của sản phẩm khác.
• Số token sử dụng phép đo heuristic xấp xỉ bốn ký tự mỗi token. Việc giảm so sánh đống rơm được lập chỉ mục với các khối được trả về; nó không phải là khoản tiết kiệm chi phí được tính phí.
• Tăng cường đồ thị không hoạt động trên các kho văn bản trò chuyện này vì chúng không chứa đồ thị [[wikilink]] gốc. Nó được thiết kế cho các kho liên kết chéo thực tế.
• Bộ đánh giá QA tùy chọn sử dụng Anthropic thay vì thiết lập GPT-4o của các bài báo, vì vậy các kết quả QA đó hữu ích cho các phép loại bỏ tương đối—không phải so sánh bảng xếp hạng công bố.

Các chỉ số đầy đủ, quét nhúng, đo độ trễ, giấy phép, lệnh, và các lưu ý nằm trong benchmarks/README.md.

Quyền riêng tư và giới hạn

• Kho dữ liệu được thiết kế dạng plaintext, không phải lưu trữ mã hóa. AgentCairn che dấu các mẫu thông tin xác thực đã nhận diện trước khi tự động ghi nội dung/tiêu đề/thẻ; các mẫu không xác định và chỉnh sửa thủ công vẫn thuộc trách nhiệm của bạn.
• Tệp kho dữ liệu chỉ dành cho chủ sở hữu (0600/0700). Vì kho dữ liệu là plaintext và việc che dấu chỉ mang tính nỗ lực tốt nhất, chế độ tệp thực chất là kiểm soát truy cập duy nhất. Các thiết lập dùng chung GID (ví dụ: hai container Docker trên cùng nhóm nhưng khác UID) cần quyền truy cập nhóm, vì vậy vault_group_writable = true mở rộng các ghi chú và thư mục mới của kho dữ liệu thành 0660/0770. Đây là tùy chọn có chủ đích: trên macOS, nhóm chính của mọi người dùng cục bộ là staff, nên mặc định cho phép đọc theo nhóm sẽ phơi bày ký ức của bạn cho các tài khoản khác trên máy. Nút điều chỉnh không bao giờ mở rộng bất cứ thứ gì bên ngoài kho dữ liệu — chỉ mục, sổ cái, tệp khóa và ~/.agentcairn/config.toml vẫn được giữ riêng tư.
• Các tính năng đám mây là luồng dữ liệu ra ngoài rõ ràng. Mặc định vẫn là cục bộ. Chọn dùng trình nhúng đám mây hoặc trình đánh giá LLM sẽ gửi văn bản đã che dấu còn lại đến nhà cung cấp đó.
• Dự án đang ở giai đoạn beta. Sử dụng độc lập yêu cầu Python 3.11+, và lần tải mô hình cục bộ đầu tiên có thể mất thời gian. Bằng chứng truy xuất đã công bố mạnh nhất cho bộ nhớ hội thoại, không phải tuyên bố tìm kiếm mã phổ quát.
• Hành vi môi trường thay đổi theo máy chủ. Ma trận trên là có chủ đích: Cursor và Antigravity dựa vào thu thập quét; máy chủ MCP chung có thể hiển thị công cụ mà không có hook vòng đời.
• Tự động hóa phụ thuộc nền tảng. Lập lịch quản lý nhắm đến launchd của macOS và crontab người dùng Linux; hãy dùng bộ lập lịch của riêng bạn ở nơi khác.

Phát triển

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

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

Chạy hồi quy điểm chuẩn ngoại tuyến mà không cần khóa API:

uv run pytest benchmarks/tests/

Giấy phép

Giấy phép Apache 2.0 — cho phép, kèm cấp bằng sáng chế rõ ràng. Bản quyền © 2026 Charles C. Figueiredo.