agentcairn

지원되는 코딩 에이전트 전반에 걸친 하나의 지속적인 메모리.
여러분의 Markdown 보관소가 표준 데이터입니다. DuckDB는 교체 가능한 검색 캐시입니다.

웹사이트 · PyPI · Obsidian 동반자 · 벤치마크

돌무더기(cairn)는 다음에 올 사람을 위해 길을 표시합니다. agentcairn은 코딩 에이전트를 위해 바로 그 역할을 합니다. 사용하는 도구에서 지속적인 컨텍스트를 캡처하고, 출처가 포함된 검사 가능한 Markdown으로 저장하며, 다른 에이전트가 필요로 할 때 가장 관련성 높은 부분만 회상합니다.

검사 가능한 증거

메모리는 관리자 콘솔이나 호스팅된 데이터베이스 뒤에 숨겨져 있지 않습니다. 별도의 agentcairn-obsidian 동반자는 에이전트와 동일한 Markdown 파일을 읽고 출처, 통용성, 중요도, 대체 여부 및 related: 링크를 노출합니다.

_{Obsidian에 있는 실제 agentcairn 보관소. 이 목록은 파일에 대한 뷰일 뿐, 두 번째 메모리 저장소가 아닙니다.}

도그푸드 스냅샷 · 2026-07-15. 417회의 로컬 회상에서, 유지 관리자의 보관소는 매번 전체 보관소를 로드하는 것보다 262× smaller에 대한 컨텍스트를 반환했으며, 총 136.6M tokens of full-vault context avoided로 추정됩니다. 토큰 수는 토큰당 약 4자를 사용합니다. 이는 청구된 토큰 절감액이 아니며, agentcairn은 어떤 원격 측정도 보내지 않습니다.

설치

가장 빠른 경로는 일급 플러그인입니다. 이 플러그인은 MCP 서버, 메모리 스킬, 그리고 호스트별 환경 훅을 번들로 제공하므로 별도의 agentcairn 패키지 설치가 필요 없습니다. 플러그인은 uvx를 통해 실행되므로, uvx --version을 사용할 수 없는 경우 먼저 uv를 설치하세요.

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 회상, 그리고 cairn sweep를 대역 외 백스톱으로 사용하는 SessionEnd 캡처를 제공받습니다.

에이전트 지원 설정

이미 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 서버, 플러그인 또는 훅은 설치하지 않습니다. 도우미는 이러한 변경 사항을 AgentCairn의 미리보기 우선 네이티브 설치 프로그램에 위임하고 결과 통합을 확인합니다. Claude Code 및 Codex 플러그인 명령은 여전히 가장 빠른 경로입니다.

기본 보관소는 ~/agentcairn이며 처음 사용할 때 생성됩니다. 비어 있는 새 보관소에는 아직 회상할 유용한 정보가 없으므로, 전체 루프를 명시적으로 증명하세요:

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 노트와 색인 항목을 함께 작성하므로, 즉시 회상이 계약의 일부입니다. 처음 로컬에서 실행하면 구성된 임베딩/재순위화 모델을 다운로드하고 준비할 수 있습니다.

계약 사항

작동 방식

• 캡처: 호스트 훅이 즉시성을 향상시킵니다. cairn sweep은 지원되는 트랜스크립트 저장소를 대역 외에서 읽어 지속적인 백스톱 역할을 합니다. AgentCairn은 자동화된 일반 텍스트 쓰기 전에 인식된 자격 증명을 삭제하고, 중복을 제거하며, 중요도에 따라 선별하고, 요약합니다.
• 조정: 첫 번째 읽기는 트랜잭션 방식으로 보관소 범위의 색인을 Markdown과 동기화합니다. 재구축에 실패하면 마지막 양호한 캐시가 보존되고 지속적인 파일은 그대로 유지됩니다.
• 회상: BM25와 시맨틱 벡터가 상호 순위 융합(Reciprocal Rank Fusion)으로 결합된 후 선택적으로 재순위화됩니다. 모델/제공자 실패 시 호환되지 않는 벡터를 반환하는 대신 진단 정보와 함께 BM25로 가시적으로 폴백합니다.
• 기억: MCP 도구는 하나의 쓰기 잠금 하에 Markdown 노트를 원자적으로 작성하고 색인을 업데이트하여, 성공적인 저장을 즉시 회상 가능하게 만듭니다.

신뢰를 위한 설계

• 기본적으로 로컬. FastEmbed는 로컬에서 실행되며, MCP 서버는 stdio를 사용하고, 필수 데몬이나 외부 데이터베이스가 없으며, 원격 측정이 없습니다.
• 명확한 경계. 동기화된 보관소에는 Markdown이 포함됩니다. 기본적으로 재구축 가능한 .duckdb 색인은 그 외부에 유지됩니다. 구성된 루트를 벗어나는 보관소 심볼릭 링크는 거부됩니다.
• 시간 인지 수정. valid_from, valid_until, 그리고 superseded_by는 오래된 증거를 계속 표시하면서 현재 사실이 먼저 순위에 오르도록 합니다.
• 결정적 그래프. [[wikilinks]] 및 선택적 cairn link 이웃은 LLM에 엔티티 생성을 요청하지 않고 Obsidian 네이티브 그래프를 생성합니다.
• 프로젝트 인지 회상. 현재 프로젝트는 기본적으로 부스트됩니다. 프로젝트 간 결과는 계속 사용 가능하며 레이블이 지정됩니다. 명시적으로 모든 프로젝트를 선택하지 않는 한 자동 회상은 프로젝트 범위로 제한됩니다.

지원되는 에이전트

모든 호스트는 동일하게 구성된 보관소를 확인합니다. cairn install는 쓰기 없이 감지된 호스트를 미리 봅니다. MCP 구성 쓰기는 백업 우선이며 관련 없는 서버를 보존합니다. 플러그인 호스트 설치는 호스트 자체 CLI에 위임합니다.

Codex SessionStart는 agentcairn 0.24.2 / 플러그인 0.1.2로 엔드 투 엔드 실시간 검증되었습니다. 설치된 SessionEnd 명령 디스패치 및 분리된 스윕은 정확한 핸들러 프로브를 통과합니다. cairn sweep은 대역 외 캡처 백스톱으로 남아 있습니다. 네이티브 수명 주기 세부 정보는 OpenCode 통합 및 Hermes 통합을 참조하세요.

직접 사용하기

플러그인이 가장 쉬운 방법이지만, agentcairn은 독립형 CLI 및 주문형 MCP 서버로도 사용 가능합니다. 독립형 설치에는 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의 메모리 가져오기

Claude Code의 자동 메모리는 소스 파일을 변경하지 않고 공유 보관소에 시드할 수 있습니다. 이 명령은 기본적으로 현재 리포지토리만 미리 봅니다. --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/ 레지스트리가 소스 콘텐츠를 두 번 색인하지 않고 이 수명 주기를 보존합니다. 사용자 지정, 관리형 또는 세션 재정의된 Claude 메모리 디렉토리에는 --source <dir>를, 일괄 가져오기에는 --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

측정된 벤치마크

리포지토리는 개정 고정되고 재현 가능한 LongMemEval-S + LoCoMo 하네스를 제공합니다. 기본값은 로컬 nomic-embed-text-v1.5과 크로스 인코더 재순위 지정기입니다.

기본 k=10에서 반환된 컨텍스트는 전체 색인된 기록보다 훨씬 작습니다:

숫자를 정직하게 읽으세요:

• 검색 회상률은 QA 정확도가 아닙니다. 이 표는 최종 사용자 답변 품질이나 다른 제품의 리더보드 점수가 아닌, 통제된 검색 방식을 비교합니다.
• 토큰 수는 토큰당 약 4자의 휴리스틱을 사용합니다. 감소율은 색인된 건초 더미와 반환된 청크를 비교한 것이며 청구된 비용 절감액이 아닙니다.
• 그래프 부스트는 네이티브 [[wikilink]] 그래프를 포함하지 않기 때문에 이러한 채팅 말뭉치에서는 비활성 상태입니다. 실제 상호 연결된 보관소를 위해 설계되었습니다.
• 선택적 QA 판단기는 논문의 GPT-4o 설정 대신 Anthropic을 사용하므로, 해당 QA 결과는 게시된 리더보드 비교가 아닌 상대적 제거 연구에 유용합니다.

전체 지표, 임베딩 스윕, 지연 시간 측정, 라이선스, 명령 및 주의 사항은 benchmarks/README.md에 있습니다.

개인정보 보호 및 제한 사항

• 볼트는 암호화된 저장소가 아니라 의도적으로 평문으로 설계되었습니다. AgentCairn은 자동화된 본문/제목/태그 쓰기 전에 인식된 자격 증명 패턴을 편집 처리하며, 알 수 없는 패턴과 수동 편집은 사용자의 책임입니다.
• 클라우드 기능은 명시적인 외부 전송입니다. 기본값은 로컬로 유지됩니다. 클라우드 임베더 또는 LLM 심사위원을 선택하면 편집 처리된 나머지 텍스트가 해당 제공업체로 전송됩니다.
• 이 프로젝트는 베타 버전입니다. 독립형 사용에는 Python 3.11 이상이 필요하며, 첫 로컬 모델 로드에는 시간이 걸릴 수 있습니다. 공개된 검색 증거는 범용 코드 검색이 아닌 대화 메모리에 가장 강력합니다.
• 주변 동작은 호스트에 따라 다릅니다. 위의 매트릭스는 의도된 것입니다. Cursor와 Antigravity는 스윕 캡처에 의존하며, 일반 MCP 호스트는 라이프사이클 훅 없이 도구를 노출할 수 있습니다.
• 자동화는 플랫폼별로 다릅니다. 관리형 스케줄링은 macOS launchd 및 Linux 사용자 crontab을 대상으로 하며, 다른 곳에서는 자체 스케줄러를 사용하십시오.

개발

agentcairn은 의존성 관리 및 도구에 uv를 독점적으로 사용합니다.

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

API 키 없이 오프라인 벤치마크 회귀 테스트를 실행합니다:

uv run pytest benchmarks/tests/

라이선스

Apache License 2.0 — 허용적이며 명시적인 특허 허여를 포함합니다. Copyright © 2026 Charles C. Figueiredo.