agentcairn

サポート対象のコーディングエージェント間で共有される永続的なメモリ。
Markdown保管庫が正規データです。DuckDBは交換可能な検索キャッシュです。

ウェブサイト · PyPI · Obsidianコンパニオン · ベンチマーク

ケアン（積石）は、後に続く者のために道標となります。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ツールは、1つのライターロックの下で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。