agentcairn

지원되는 코딩 에이전트 전반에 걸친 하나의 영구 메모리.
당신의 Markdown 볼트가 표준입니다. DuckDB는 교체 가능한 검색 캐시입니다.

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

돌무더기(cairn)는 다음에 오는 사람을 위해 길을 표시합니다. agentcairn은 코딩 에이전트를 위해 그렇게 합니다: 사용하는 도구에서 지속적인 맥락을 포착하고, 출처가 있는 검사 가능한 Markdown으로 저장하며, 다른 에이전트가 필요할 때 가장 관련성 높은 조각만 회상합니다.

검사할 수 있는 증거

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

_{Obsidian에서의 실제 agentcairn 볼트. 목록은 파일에 대한 뷰일 뿐입니다—두 번째 메모리 저장소가 아닙니다.}

자체 사용 스냅샷 · 2026-07-15. 417회의 로컬 회상에서, 관리자의 볼트는 매번 전체 볼트를 로드하는 것보다 262× smaller 맥락을 반환했습니다—총 136.6M tokens of full-vault context avoided 절감으로 추정됩니다. 토큰 수는 토큰당 약 4자를 사용합니다. 이는 청구된 토큰 절감이 아니며, agentcairn은 원격 측정(telemetry)을 보내지 않습니다.

설치

가장 짧은 경로는 일급(first-class) 플러그인입니다. 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은 자동화된 본문/제목/태그 쓰기 전에 인식된 자격 증명 패턴을 삭제합니다. 알 수 없는 패턴과 수동 편집은 사용자의 책임입니다.
• 볼트 파일은 소유자 전용입니다 (0600/0700). 볼트가 일반 텍스트이고 삭제가 최선의 노력이므로, 파일 모드는 사실상 유일한 접근 제어입니다. 공유 GID 설정(예: 같은 그룹이지만 다른 UID를 가진 두 Docker 컨테이너)은 그룹 액세스가 필요하므로, vault_group_writable = true은 새 볼트 노트와 디렉터리를 0660/0770로 확장합니다. 이는 의도적으로 옵트인 방식입니다. macOS에서는 모든 로컬 사용자의 기본 그룹이 staff이므로, 그룹 읽기 가능 기본값은 다른 계정에 메모리를 노출할 수 있습니다. 이 설정은 볼트 외부의 어떤 것도 확장하지 않습니다 — 인덱스, 원장, 잠금 파일 및 ~/.agentcairn/config.toml은 비공개로 유지됩니다.
• 클라우드 기능은 명시적 이그레스입니다. 기본값은 로컬로 유지됩니다. 클라우드 임베더 또는 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 — 명시적 특허 허여가 포함된 허용적 라이선스. 저작권 © 2026 Charles C. Figueiredo.