agentcairn

หน่วยความจำถาวรหนึ่งเดียวที่ใช้ร่วมกันได้กับเอเจนต์เขียนโค้ดที่รองรับ
Vault Markdown ของคุณคือแหล่งข้อมูลหลัก DuckDB คือแคชการค้นคืนที่สามารถแทนที่ได้

เว็บไซต์ · PyPI · คอมแพเนียน Obsidian · เกณฑ์วัด

กองหิน (cairn) เป็นเครื่องหมายบอกเส้นทางสำหรับผู้ที่มาทีหลัง agentcairn ทำสิ่งนั้นให้กับเอเจนต์เขียนโค้ด: มันเก็บบริบทที่คงทนจากเครื่องมือที่คุณใช้ จัดเก็บเป็น Markdown ที่ตรวจสอบได้พร้อมที่มาของข้อมูล และเรียกคืนเฉพาะส่วนที่เกี่ยวข้องมากที่สุดเมื่อเอเจนต์อื่นต้องการ

หลักฐานที่คุณตรวจสอบได้

หน่วยความจำไม่ได้ซ่อนอยู่หลังคอนโซลผู้ดูแลหรือฐานข้อมูลที่โฮสต์ไว้ คอมแพเนียนแยกต่างหาก agentcairn-obsidian อ่านไฟล์ Markdown เดียวกับที่เอเจนต์ใช้ และเปิดเผยที่มาของข้อมูล ความเป็นปัจจุบัน ความสำคัญ การแทนที่ และลิงก์ related:

_{Vault agentcairn จริงใน Obsidian รายการนี้คือมุมมองเหนือไฟล์—ไม่ใช่พื้นที่เก็บหน่วยความจำที่สอง}

ภาพรวมการใช้งานจริง · 2026-07-15. จากการเรียกคืนในเครื่อง 417 ครั้ง vault ของผู้ดูแลส่งคืนบริบทเกี่ยวกับ 262× smaller มากกว่าการโหลด vault ทั้งหมดในแต่ละครั้ง—ประมาณ 136.6M tokens of full-vault context avoided โดยรวม การนับโทเค็นใช้ประมาณสี่อักขระต่อโทเค็น นี่ไม่ใช่การประหยัดโทเค็นที่เรียกเก็บเงิน และ agentcairn ไม่ส่งข้อมูล telemetry ใดๆ

การติดตั้ง

เส้นทางที่สั้นที่สุดคือปลั๊กอินระดับเฟิร์สคลาส มันรวม MCP server, ทักษะหน่วยความจำ และฮุคสภาพแวดล้อมเฉพาะโฮสต์—ไม่ต้องติดตั้งแพ็กเกจ agentcairn แยกต่างหาก ปลั๊กอินเปิดใช้งานผ่าน uvx ดังนั้นติดตั้ง uv ก่อนหาก uvx --version ยังไม่พร้อมใช้งาน

Claude Code

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

Claude Code ได้รับการเรียกคืนตามขอบเขตโปรเจกต์ต่อเทิร์น การบันทึกเซสชัน/การบีบอัด และคำสั่ง /agentcairn:recall, /agentcairn:remember, /agentcairn:memory, /agentcairn:savings, และ /agentcairn:ingest

Codex

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

Codex ได้รับเครื่องมือ MCP และทักษะหน่วยความจำที่รวมมา การเรียกคืน SessionStart ที่ตรวจสอบแบบเรียลไทม์ และการบันทึก SessionEnd พร้อม cairn sweep เป็นตัวสำรองนอกช่องทาง

การตั้งค่าที่ใช้เอเจนต์ช่วย

ใช้ skills.sh หรือเวิร์กโฟลว์ find-skills อยู่แล้ว? ติดตั้งผู้ช่วยตั้งค่าสาธารณะ:

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

จากนั้นถามเอเจนต์ของคุณ: Use $agentcairn-setup to preview, install, and verify AgentCairn for this coding agent.

สิ่งนี้ติดตั้งเฉพาะคำแนะนำการตั้งค่า—ไม่ใช่รันไทม์ AgentCairn, MCP server, ปลั๊กอิน หรือฮุค ผู้ช่วยมอบหมายการเปลี่ยนแปลงเหล่านั้นให้กับตัวติดตั้งแบบเนทีฟที่แสดงตัวอย่างก่อนของ AgentCairn และตรวจสอบการผสานรวมที่ได้ คำสั่งปลั๊กอิน Claude Code และ Codex ข้างต้นยังคงเป็นเส้นทางที่สั้นที่สุด

vault เริ่มต้นคือ ~/agentcairn และถูกสร้างขึ้นเมื่อใช้งานครั้งแรก vault ใหม่ที่ว่างเปล่ายังไม่มีอะไรที่เป็นประโยชน์ให้เรียกคืน ดังนั้นพิสูจน์วงจรทั้งหมดอย่างชัดเจน:

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 เขียนโน้ต Markdown และรายการดัชนีพร้อมกัน ดังนั้นการเรียกคืนทันทีจึงเป็นส่วนหนึ่งของสัญญา การรันในเครื่องครั้งแรกอาจดาวน์โหลดและอุ่นโมเดล embedding/reranking ที่กำหนดค่าไว้

สัญญา

วิธีการทำงาน

• การบันทึก: ฮุคโฮสต์ปรับปรุงความทันที; cairn sweep อ่านพื้นที่เก็บ transcript ที่รองรับนอกช่องทางเป็นตัวสำรองที่คงทน AgentCairn ปิดบังข้อมูลรับรองที่รู้จัก, ลดความซ้ำซ้อน, กรองตามความสำคัญ และกลั่นกรองก่อนการเขียนข้อความธรรมดาอัตโนมัติ
• การประสาน: ธุรกรรมการอ่านครั้งแรกทำให้ดัชนีตามขอบเขต vault ซิงค์กับ Markdown การสร้างใหม่ที่ล้มเหลวรักษาแคชที่ดีล่าสุด และไฟล์ที่คงทนยังคงไม่ถูกแตะต้อง
• การเรียกคืน: BM25 และเวกเตอร์เชิงความหมายถูกหลอมรวมด้วย Reciprocal Rank Fusion จากนั้นเลือกจัดอันดับใหม่ตามตัวเลือก ความล้มเหลวของโมเดล/ผู้ให้บริการจะลดระดับเป็น BM25 อย่างเห็นได้ชัดพร้อมการวินิจฉัย แทนการส่งคืนเวกเตอร์ที่เข้ากันไม่ได้
• การจดจำ: เครื่องมือ MCP เขียนโน้ต Markdown และอัปเดตดัชนีภายใต้ล็อกผู้เขียนเดียวแบบอะตอมมิก ทำให้การบันทึกที่สำเร็จสามารถเรียกคืนได้ทันที

ออกแบบมาเพื่อความไว้วางใจ

• ท้องถิ่นโดยค่าเริ่มต้น FastEmbed รันในเครื่อง, MCP server ใช้ stdio, ไม่มี daemon หรือฐานข้อมูลภายนอกที่จำเป็น และไม่มี telemetry
• ขอบเขตที่ชัดเจน vault ที่ซิงค์มี Markdown; โดยค่าเริ่มต้น ดัชนี .duckdb ที่สร้างใหม่ได้จะอยู่ภายนอก vault ลิงก์สัญลักษณ์ vault ที่หลบหนีรากที่กำหนดค่าจะถูกปฏิเสธ
• การแก้ไขที่คำนึงถึงเวลา valid_from, valid_until, และ superseded_by ทำให้หลักฐานเก่ายังมองเห็นได้ในขณะที่ทำให้ข้อเท็จจริงปัจจุบันจัดอันดับแรก
• กราฟที่กำหนดได้ [[wikilinks]] และเพื่อนบ้าน cairn link ที่เป็นตัวเลือกสร้างกราฟแบบเนทีฟ Obsidian โดยไม่ขอให้ LLM สร้างเอนทิตี
• การเรียกคืนที่คำนึงถึงโปรเจกต์ โปรเจกต์ปัจจุบันถูกเพิ่มน้ำหนักโดยค่าเริ่มต้น; ผลลัพธ์ข้ามโปรเจกต์ยังคงพร้อมใช้งานและถูกติดป้ายกำกับ การเรียกคืนอัตโนมัติจำกัดตามโปรเจกต์เว้นแต่คุณเลือกใช้ทุกโปรเจกต์อย่างชัดเจน

เอเจนต์ที่รองรับ

ทุกโฮสต์แก้ไข vault ที่กำหนดค่าเดียวกัน cairn install แสดงตัวอย่างโฮสต์ที่ตรวจพบโดยไม่เขียน การเขียนการกำหนดค่า MCP สำรองไฟล์ก่อนและรักษาเซิร์ฟเวอร์ที่ไม่เกี่ยวข้อง; การติดตั้งปลั๊กอินโฮสต์มอบหมายให้ CLI ของโฮสต์เอง

Codex SessionStart ถูกตรวจสอบแบบเรียลไทม์แบบ end-to-end ด้วย agentcairn 0.24.2 / ปลั๊กอิน 0.1.2 การส่งคำสั่ง SessionEnd ที่ติดตั้งและการกวาดแบบแยกผ่านการตรวจสอบตัวจัดการที่แม่นยำ; cairn sweep ยังคงเป็นตัวสำรองการบันทึกนอกช่องทาง ดู การผสานรวม OpenCode และ การผสานรวม Hermes สำหรับรายละเอียดวงจรชีวิตเนทีฟของพวกเขา

การใช้งานโดยตรง

ปลั๊กอินเป็นเส้นทางที่ง่ายที่สุด แต่ agentcairn ยังเป็น CLI แบบสแตนด์อโลนและ MCP server แบบตามความต้องการ การติดตั้งแบบสแตนด์อโลนต้องใช้ 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

นำหน่วยความจำของ Claude Code ไปด้วย

auto-memory ของ Claude Code สามารถเพาะ vault ที่ใช้ร่วมกันได้โดยไม่เปลี่ยนไฟล์ต้นฉบับ คำสั่งแสดงตัวอย่างเฉพาะ repository ปัจจุบันโดยค่าเริ่มต้น; เพิ่ม --apply เพื่อเขียนโน้ตที่ปิดบังและรีเฟรชดัชนี

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

การนำเข้าทางเดียวอ่าน MEMORY.md และไฟล์ Markdown หัวข้อของมัน—ไม่เคยอ่าน CLAUDE.md หรือ .claude/rules/ โน้ตที่นำเข้ายังคงที่มาของ Claude Code, โปรเจกต์ และไฟล์ต้นฉบับ เมื่อแหล่งที่มาเปลี่ยนแปลง เวอร์ชันก่อนหน้ายังคงตรวจสอบได้แต่ถูกแทนที่; เมื่อแหล่งที่มาหายไป เวอร์ชันที่นำเข้าจะหมดอายุ ทะเบียน .agentcairn/native-memory/ ขนาดเล็กรักษาวงจรชีวิตนั้นโดยไม่จัดทำดัชนีเนื้อหาต้นฉบับสองครั้ง ใช้ --source <dir> สำหรับไดเรกทอรีหน่วยความจำ Claude ที่กำหนดเอง จัดการ หรือแทนที่ด้วยเซสชัน หรือ --no-reindex เมื่อนำเข้าเป็นชุด

ต้องการกระบวนการชั่วคราว:

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

เกณฑ์วัดที่วัดได้

repository จัดส่ง ชุดทดสอบ LongMemEval-S + LoCoMo ที่ปักหมุดรุ่นและทำซ้ำได้ ค่าเริ่มต้นคือ nomic-embed-text-v1.5 ในเครื่องบวกกับ reranker แบบ cross-encoder

บริบทที่ส่งคืนที่ k=10 เริ่มต้นมีขนาดเล็กกว่าประวัติที่จัดทำดัชนีทั้งหมดมาก:

อ่านตัวเลขอย่างตรงไปตรงมา:

• การเรียกคืนการดึงข้อมูลไม่ใช่ความแม่นยำ QA ตารางเหล่านี้เปรียบเทียบแขนการดึงข้อมูลที่ควบคุม ไม่ใช่คุณภาพคำตอบของผู้ใช้ปลายทางหรือคะแนนลีดเดอร์บอร์ดของผลิตภัณฑ์อื่น
• การนับโทเค็นใช้ฮิวริสติกประมาณสี่อักขระต่อโทเค็น การลดลงเปรียบเทียบกองหญ้าที่จัดทำดัชนีกับชิ้นส่วนที่ส่งคืน; ไม่ใช่การประหยัดต้นทุนที่เรียกเก็บเงิน
• การเพิ่มน้ำหนักกราฟไม่ทำงานกับคลังข้อมูลแชทเหล่านี้因为它们ไม่มีกราฟ [[wikilink]] เนทีฟ มันออกแบบมาสำหรับ vault ที่เชื่อมโยงกันจริง
• ผู้ตัดสิน QA ที่เป็นตัวเลือกใช้ Anthropic แทนการตั้งค่า GPT-4o ของเอกสาร ดังนั้นผลลัพธ์ QA เหล่านั้นมีประโยชน์สำหรับการตัดทอนเชิงสัมพัทธ์—ไม่ใช่การเปรียบเทียบลีดเดอร์บอร์ดที่เผยแพร่

เมตริกเต็ม, การสแกน embedding, การวัดความหน่วง, ใบอนุญาต, คำสั่ง และข้อจำกัดอยู่ใน benchmarks/README.md

ความเป็นส่วนตัวและข้อจำกัด

• Vault เป็น plaintext โดยการออกแบบ ไม่ใช่พื้นที่จัดเก็บที่เข้ารหัส AgentCairn จะปกปิดรูปแบบข้อมูลประจำตัวที่รู้จักก่อนการเขียน body/title/tag อัตโนมัติ รูปแบบที่ไม่รู้จักและการแก้ไขด้วยมือยังคงเป็นความรับผิดชอบของคุณ
• ไฟล์ Vault เป็นแบบเจ้าของเท่านั้น (0600/0700) เนื่องจาก vault เป็น plaintext และการปกปิดเป็นแบบ best-effort โหมดไฟล์จึงเป็นเพียงการควบคุมการเข้าถึงเท่านั้น การตั้งค่า Shared-GID (เช่น Docker containers สองตัวบน group เดียวกันแต่ UID ต่างกัน) จำเป็นต้องมีการเข้าถึงแบบ group ดังนั้น vault_group_writable = true จะขยายโน้ตและไดเรกทอรี vault ใหม่ เป็น 0660/0770 โดยตั้งใจให้เป็น opt-in: บน macOS กลุ่มหลักของผู้ใช้ท้องถิ่นทุกคนคือ staff ดังนั้นค่าเริ่มต้นที่ group อ่านได้จะเปิดเผยความทรงจำของคุณต่อบัญชีอื่นบนเครื่อง ปุ่มนี้ไม่เคยขยายสิ่งใดนอก vault — index, ledgers, lock files และ ~/.agentcairn/config.toml ยังคงเป็นส่วนตัว
• ฟีเจอร์คลาวด์เป็นการส่งออกข้อมูลอย่างชัดเจน ค่าเริ่มต้นยังคงเป็นแบบ local การเลือกใช้ cloud embedder หรือ LLM judge จะส่งข้อความที่ปกปิดแล้วไปยังผู้ให้บริการนั้น
• โปรเจกต์อยู่ในช่วง beta การใช้งานแบบ standalone ต้องใช้ Python 3.11+ และการโหลดโมเดล local ครั้งแรกอาจใช้เวลา หลักฐานการดึงข้อมูลที่เผยแพร่แข็งแกร่งที่สุดสำหรับความทรงจำเชิงสนทนา ไม่ใช่การอ้างสิทธิ์การค้นหาโค้ดแบบสากล
• พฤติกรรมโดยรอบแตกต่างกันตามโฮสต์ เมทริกซ์ด้านบนตั้งใจ: Cursor และ Antigravity อาศัยการจับภาพแบบ sweep; MCP hosts ทั่วไปอาจเปิดเผยเครื่องมือโดยไม่มี lifecycle hooks
• ระบบอัตโนมัติขึ้นอยู่กับแพลตฟอร์ม การจัดตารางเวลาที่จัดการกำหนดเป้าหมาย macOS launchd และ Linux user crontab; ใช้ตัวจัดตารางเวลาของคุณเองที่อื่น

การพัฒนา

agentcairn ใช้ uv สำหรับการจัดการ dependencies และเครื่องมือเท่านั้น

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

รันการทดสอบ regression แบบ offline โดยไม่ต้องใช้ API keys:

uv run pytest benchmarks/tests/

สัญญาอนุญาต

Apache License 2.0 — แบบ permissive พร้อมการอนุญาตสิทธิบัตรอย่างชัดเจน ลิขสิทธิ์ © 2026 Charles C. Figueiredo