agentcairn

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

Trang web · PyPI · Tiện ích Obsidian · Điểm chuẩn

Một cột mốc đánh dấu lối đi cho người đến 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 kèm nguồn gốc, và chỉ gợi lại những phần liên quan nhất khi một tác nhân khác cần đến.

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ữ. Tiện ích 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 thời sự, tầm 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 góc nhìn qua các tệp—không phải kho lưu trữ bộ nhớ thứ hai.}

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

Cài đặt

Con đường ngắn nhất là một plugin hạng nhất. Nó đóng gói máy chủ MCP, kỹ năng bộ nhớ, và các móc nối môi trường cụ thể cho máy chủ—không cần cài đặt gói agentcairn riêng biệt. Plugin khởi chạy qua uvx, vì vậy hãy cài đặt 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 gợi lại theo lượt trong phạm vi dự án, 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ớ đi kèm, gợi lại SessionStart được xác minh trực tiếp, và thu thập SessionEnd với cairn sweep như một điểm tựa ngoài băng tần.

Thiết lập có trợ lý tác nhân

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

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

Sau đó yêu cầu 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, hay các móc nối. Trợ lý ủy quyền những thay đổi đó cho trình cài đặt gốc xem trước 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 để gợi lạ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 gợi lạ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 nóng các mô hình nhúng/xếp hạng lại đã cấu hình.

Hợp đồng

Cách thức 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ản ghi được hỗ trợ ngoài băng tần như một điểm tựa bền vững. AgentCairn biên tập lại thông tin xác thực được nhận dạng, loại bỏ trùng lặp, lọc theo tầm quan trọng, và tinh lọc trước khi ghi văn bản thuần tự động.
• Đối chiếu: giao dịch đọc đầu tiên đồng bộ chỉ mục phạm vi kho với Markdown. Một lần xây dựng lại thất bại bảo toàn bộ nhớ đệm tốt cuối cùng và các tệp bền vững vẫn không bị ảnh hưởng.
• Gợi lại: BM25 và vector ngữ nghĩa được hợp nhất với Reciprocal Rank Fusion, sau đó tùy chọn xếp hạng lại. Lỗi mô hình/nhà cung cấp hiển thị rõ ràng quay về BM25 với chẩn đoán thay vì trả về vector không tương thích.
• Ghi nhớ: công cụ MCP ghi nguyên tử một ghi chú Markdown và cập nhật chỉ mục dưới một khóa ghi, làm cho một lần lưu thành công có thể gợi lại ngay lập tức.

Thiết kế cho sự tin cậy

• Cục bộ theo mặc định. FastEmbed chạy cục bộ, máy chủ MCP sử dụng stdio, không yêu cầu daemon hay cơ sở dữ liệu ngoài, và không có dữ liệu đo lường 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 ngoài nó. Các liên kết tượng trưng kho thoát ra ngoài thư mục gốc đã cấu hình bị từ chối.
• Sửa chữa nhận biết thời gian. valid_from, valid_until, và superseded_by giữ bằng chứng cũ hiển thị trong khi làm cho sự kiện hiện tại xếp hạng đầu tiên.
• Đồ thị xác định. [[wikilinks]] và các láng giềng cairn link tùy chọn tạo ra một đồ thị gốc Obsidian mà không yêu cầu LLM phát minh thực thể.
• Gợi lại nhận biết dự án. Dự án hiện tại được ưu tiên theo mặc định; kết quả đa dự án vẫn có sẵn và được gắn nhãn. Gợi lại tự động trong phạm vi dự án trừ khi bạn chọn rõ ràng tất cả dự án.

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

Mọi máy chủ 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. 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ài đặt máy chủ plugin ủy quyền cho CLI của chính máy chủ đó.

Codex SessionStart đã được xác minh trực tiếp đầu 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 đầu dò xử lý chính xác; cairn sweep vẫn là điểm tựa 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à cách 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à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ớ Claude Code theo bạn

Bộ nhớ tự động của Claude Code có thể gieo vào kho chia sẻ mà không thay đổi tệp nguồn của nó. Lệnh chỉ xem trước kho lưu trữ hiện tại theo mặc định; thêm --apply để ghi các ghi chú đã biên tập lại 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

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ú đã 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 đã 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 thư mục bộ nhớ Claude tùy chỉnh, được quản lý, hoặc ghi đè phiên, hoặc --no-reindex khi nhập hàng loạt.

Ư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

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

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

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

• Gợi lại truy xuất không phải là độ chính xác QA. Các bảng này so sánh các nhánh truy xuất được kiểm soát, không phải chất lượng câu trả lời người dùng cuối hay điểm số bảng xếp hạng của sản phẩm khác.
• Số lượng token sử dụng heuristic xấp xỉ bốn ký tự mỗi token. Mức giảm so sánh đống cỏ khô đã lập chỉ mục với các đoạn trả về; nó không phải là tiết kiệm chi phí được tính phí.
• Tăng cường đồ thị không có tác dụng trên các kho ngữ liệu 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 thực tế.
• Trình đá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 những kết quả QA đó hữu ích cho các phép cắt bỏ tương đối—không phải so sánh bảng xếp hạng đã công bố.

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

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

• Kho lưu trữ được thiết kế ở dạng văn bản thuần túy, không phải lưu trữ mã hóa. AgentCairn biên tập lại các mẫu thông tin xác thực được nhận dạng 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.
• Các tính năng đám mây là lối ra dữ liệu rõ ràng. Mặc định vẫn là cục bộ. Chọn sử dụng trình nhúng đám mây hoặc giám khảo LLM sẽ gửi văn bản đã biên tập còn lại đến nhà cung cấp đó.
• Dự án đang trong 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 đối với bộ nhớ hội thoại, không phải là tuyên bố tìm kiếm mã nguồn phổ quát.
• Hành vi môi trường thay đổi tùy theo máy chủ. Ma trận trên là có chủ đích: Cursor và Antigravity dựa vào quét thu thập; các máy chủ MCP chung có thể hiển thị công cụ mà không có móc vòng đời.
• Tự động hóa phụ thuộc vào nền tảng. Lập lịch được quản lý nhắm mục tiêu launchd của macOS và crontab người dùng Linux; sử dụng bộ lập lịch riêng của 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, với cấp bằng sáng chế rõ ràng. Bản quyền © 2026 Charles C. Figueiredo.