Cairn

Cairn

AI エージェントでファイルを整理する、ローカルファーストのオープンソースハーネスです。

Claude Code、Codex、Cursor など、あらゆる MCP クライアントからフォルダーを指定すると、エージェントはファイル整理のためのツール一式（一覧表示、読み取り、検索、grep、編集、移動、タグ付け、ドキュメントのインポート、意味検索）を利用できるようになります。アカウントもクラウドも UI も必要ありません。ファイルがマシンの外に出ることはありません。

claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes

あとはエージェントに「このフォルダーを整理して、すべてにタグを付けて」と頼むだけです。エージェントは、手元のファイルに対してローカルで動作するツールを使って処理します。

ケルンとは、道しるべとして積み上げられた石のことです。Cairn はファイルを整理し、そこに至る道筋を示します。

---

クイックスタート（2 分）

Claude Code をお使いの場合、セットアップは 1 つのコマンドで完了します。前提条件は、uvx を提供する uv のみです。

# 1. Install uv if you don't have it (provides uvx)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Add Cairn to Claude Code, pointed at a folder you want organized
claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes

Claude Code を再起動して、次のように頼んでください。

「このフォルダーを整理して、すべてにタグを付けてください。」

Cairn のツールはファイルに対してローカルで動作します。読み取りは自由に行われ、移動、名前変更、編集の前には確認を求めます。初回の実行時にパッケージが自動ダウンロードされます（約 5 秒）。クローン、ビルド、アカウントは必要ありません。

ヒント

初回は --workspace にメモのコピーを指定してください。Cairn はファイルの移動、名前変更、編集を行う場合があります。

Codex をお使いですか？ 同じくコマンド 1 つでセットアップできます（その後、セッションで /mcp を実行して確認してください）。

codex mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes

Cursor や別の MCP クライアントをお使いですか？ 同じパッケージを JSON 設定で利用できます。

{ "mcpServers": { "cairn": { "command": "uvx",
  "args": ["cairn-mcp-server", "--workspace", "~/Documents/notes"] } } }

Cairn は ~ を展開するため、CLI と設定ファイルのどちらでも ~/Documents/notes を使えます。

エージェントなしで、試しに使ってみたい場合

uvx cairn-cli --workspace ~/Documents/notes tree

ハーネスを採用する理由

エージェントハーネスのエコシステムでは、明確なパターンが定着しています。モデルとエージェントのループは、クライアント（Claude Code、Codex、OpenCode）が提供する汎用的な要素です。長期的に価値を持つのは、ツールとローカルデータです。そこで Cairn が提供するのは、エージェントではなくツールです。ループ、承認プロンプト（ツールのアノテーションによって制御）、チャットはクライアントが提供します。Cairn は、すでにお使いのハーネスに組み込める、ローカルで動作するファイル整理ツールセットです。

アーキテクチャ

すべてのインターフェースは、1 つの標準ライブラリコアを薄く包むアダプターです。そのため、互いに食い違うことはありません。

core/          cairn-core — the engine (stdlib only): the .uni document format,
               file operations, tags, retrieval; optional document ingestion
               (docx/pdf/pptx/xlsx/md) and embeddings-based search.
mcp-server/    cairn-mcp-server  — MCP server: 26 tools with read-only/destructive
               annotations, resources, and prompts.        ← the flagship
cli/           cairn-cli  — scriptable CLI, a local HTTP API (`serve`),
               and an `mcp` launcher.
web/           cairn-web  — optional zero-build local web UI
               (browse / edit / view / tag / search).

使い方

Claude Code／Codex／Cursor で使う（主な使い方）：

claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes
# with real-document import: uvx --with "cairn-core[convert]" cairn-mcp-server ...

サーバーは読み取り専用ツール（一覧表示、読み取り、検索、grep、取得）を公開し、クライアントはこれらを自由に実行します。一方、破壊的な操作を伴うツール（移動、削除、編集）は、実行前に確認を求めます。これは MCP ツールのアノテーションによって制御されるため、Cairn 独自の UI がなくても承認プロンプトが表示されます。

CLI として：

uvx cairn-cli --workspace ~/Documents/notes tree
uvx cairn-cli --workspace ~/Documents/notes retrieve "budget planning"

オプションの Web UI と組み合わせて：

pip install cairn-cli cairn-web
cairn --workspace ~/Documents/notes serve   # → http://127.0.0.1:4177/

.uni 形式

.uni ファイルは { uuid, content: "<html>", metadata, tags } という小さな JSON ドキュメントで、タグはファイル内に保存されます。ワークスペースは単なるディレクトリなので、完全にポータブルで、外部データベースも必要ありません。ソースドキュメント（docx/pdf/pptx/…）は、編集可能な .uni ドキュメントにインポートされます。デフォルトでは元のファイルも保持されます。

ローカルファーストとキーの持ち込み

• アカウント、ログイン、クラウド同期は不要です。ファイルシステムが信頼できる唯一の情報源です。
• デフォルトの検索機能は語彙ベースで、追加の設定は不要です。埋め込みはオプトイン方式で、API キーは利用者が用意します（ローカルサーバーの Ollama や LM Studio を含む、OpenAI 互換の任意のエンドポイントを利用できます）。ベクトルはローカルの SQLite インデックス内の <workspace>/.cairn/ に保存され、マシンの外に出ることはありません。

ロードマップ

Cairn はまだ新しいプロジェクトです。大まかな方向性と、特にご協力いただけるとうれしいことをご紹介します。

• ドキュメント形式の拡充 — ネストされたメタデータや日付など、より豊富なフロントマターへの対応と、編集内容をインポート元の形式に書き戻す機能。
• よりスマートなダイジェスト — 設定されている場合は埋め込みモデルを使用する要約と、保存済みビュー（.cairn/views/*.md）。
• 取得バックエンドの拡充 — 差し替え可能なリランキング機能、汎用的な OpenAI 互換方式に加え、ローカルモデル（Ollama、LM Studio）向けの組み込みプリセット。
• エディター／エージェントとの連携 — Cairn を一般的な MCP クライアントやノート作成環境に接続するための簡潔なレシピ。
• パッケージ化 — 署名付きリリースと Homebrew の formula。

当てはまらないユースケースがありますか？イシューを作成するか、ディスカッションを始めてください。

貢献

規模を問わず、あらゆる貢献を歓迎します。プロジェクトの構成、開発環境のセットアップ方法、ツールの追加方法については、CONTRIBUTING.mdをご覧ください。初めての貢献に適したイシューにはgood first issueのラベルが付いています。

開発

make setup      # uv venv (3.11) + editable install of all packages + extras
make test       # run the suite
make serve WORKSPACE=~/Documents/notes   # web UI

ライセンス

MIT — LICENSEをご覧ください。