Cairn

重要

Cairn は提供を終了し、このリポジトリはアーカイブ（読み取り専用）になっています。 後継プロジェクトは rill です。Cairn の良かった点も 問題だった点もすべて活かして開発された、Go 製のより高速で軽量な MCP ネイティブのメモリサーバーです。Cairn が最初のプロジェクトであり、今後の開発は rill で続きます。 このリポジトリは読み取り専用アーカイブとして公開されています。自由に調べたり、フォークしたりできますが、新しい開発は rill で行われます。

---

AI エージェントと人間のための、セルフホスト可能な永続メモリプラットフォームです。一度保存すれば、セッションをまたいで、プロジェクトをまたいで、後から見つけられます。4 つのコンテナを起動して、docker compose up を実行すれば完了です。

Cairn はメモリの中枢です。エージェントのランタイムが実行を担い、Cairn は情報を把握します。どのような決定がなされたか、どんな事実が分かっているか、プロジェクトをまたいでどのようなパターンが現れるかを扱います。

システムを扱う人、好奇心旺盛な人、T 字型のスキルを持つ人のために作られています。あらゆるものを、一度に、自分のやり方で扱えるメモリを必要とする人のためのものです。

クイックスタート

1. プルして起動する

curl -O https://raw.githubusercontent.com/jasondostal/cairn-mcp/main/docker-compose.yml
docker compose up -d

4 つのコンテナが起動します。

• cairn（ポート 8000、MCP サーバー＋REST API）
• cairn-ui（ポート 3000、Web ダッシュボード）
• cairn-db（PostgreSQL 16＋pgvector）
• cairn-graph（Neo4j 5、ナレッジグラフ）

初回起動時にマイグレーションが実行されます。約 1 分で準備が整います。

2. IDE を接続する

MCP 設定に以下を追加します。

{
  "mcpServers": {
    "cairn": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

設定ファイルの場所：

IDE	設定ファイル
Claude Code	プロジェクトのルートにある .mcp.json
Cursor	.cursor/mcp.json
Windsurf	.windsurf/mcp.json
Cline	VS Code の MCP 設定パネル
Continue	.continue/config.yaml
PiClaw	.pi/mcp.json

またはセットアップウィザードを実行すると、LLM バックエンド、データベース、埋め込み、認証、IDE の設定まで、すべての手順が案内されます。

git clone https://github.com/jasondostal/cairn-mcp.git && ./cairn-mcp/scripts/setup.sh

ティア（ローカル開発、推奨、エンタープライズ、カスタム）を選ぶと、ウィザードはそのティアに必要な項目だけを収集します。CI 向けに --dry-run と --non-interactive をサポートしています。

3. 使ってみる

エージェントに、次の内容を覚えてもらいます。

「ストレージに PostgreSQL を選んだのは、別途ベクターデータベースを用意せずにハイブリッド検索を処理できるためです。」

後で検索します。

「ストレージ層について、何を決めましたか？」

以上です。11 個のツールを利用できます。よく使うツールは次のとおりです。

ツール	機能
store	自動補強を行いながら記憶を保存します。双時間追跡用の event_at と valid_until に対応しています
search	記憶を検索します（ベクトル＋キーワード＋新しさ＋タグ）。時間フィルター：as_of、event_after、event_before
recall	指定した記憶 ID の全内容を取得します
orient	ルール、最近の活動、信念、未完了の作業を含めてセッションを開始します
rules	行動上のガードレールを読み込みます（グローバルまたはプロジェクトごと）
beliefs	永続的な認識状態です。確信度を追跡しながら、知識を確立、異議申し立て、撤回します
work_items	依存関係とゲートを設定して、タスクを作成、担当、完了します
working_memory	重要度の減衰を伴いながら、仮説、質問、緊張関係といった一時的な思考を記録します
projects	プロジェクトドキュメント（ブリーフ、PRD、計画）を管理します
code_query	構造に関するクエリ：依存先、影響範囲、呼び出し元、呼び出し先、デッドコード、複雑度、ホットスポット
arch_check	インポートに基づいて、アーキテクチャの境界ルールを検証します

その他：modify、insights、think、status、consolidate、ingest。

同梱機能

セッションをまたいで保持されるメモリ。 エージェントが午前2時に判断を下します。翌朝、別のセッションで、その判断を見つけます。これが中核機能です。二時点追跡により、何かが起きた時点（event_at）と、それを知った時点（created_at）を区別します。アクセスされないメモリは自然に減衰し、重要なメモリは保護されます。関連するメモリは自動的に統合され、より高次の知見になります。

信念。 確信度とともに保持される、持続的な認識状態です。仮説を信念として結晶化させ、反証によって検証し、誤りであれば撤回できます。信念はルールやメモリとともにセッション起動時に提示され、組織が何を知っているか、またその確信度をエージェントが明確に把握できるようにします。

複数のシグナルを融合する検索。 ベクトル類似度、鮮度、アクセス頻度、キーワードの一致、タグの重複を、Reciprocal Rank Fusion で組み合わせます。プロジェクト、種類、期間で絞り込めます。as_of を使えば「火曜日時点で何を知っていましたか？」、event_after／event_before を使えば「先週何が起きましたか？」といった時間的なクエリを実行できます。

ナレッジグラフ。 エンティティと事実を抽出して Neo4j グラフに登録し、共通の人物、場所、プロジェクト、概念を通じてメモリをつなぎます。オプションですが、複数の領域にまたがって作業するときに強力です。

思考の連鎖。 構造化された検討プロセスです。目標から始め、思考（観察、仮説、分析、代替案）を追加し、結論を出します。人間とエージェントの両方が参加できます。探索そのものが検索可能なメモリになります。

作業管理。 依存関係の追跡、人間の判断を待つゲート、アクティビティの記録を備えた階層型の作業項目です。実験的な機能であり、何が有効かを学びながら進化しています。

ウェブダッシュボード。 OKLCH 色の切り替え式フィルター、スコアのグラデーションバー、共有可能な URL 状態を使ってメモリを閲覧できます。ナレッジグラフとエンティティ間の関係を探索できます。分析を表示し、作業項目を管理できます。ポート 3000 を使用します。

_{種類別のメモリ増加、トークン使用量の追跡、ナビゲーション全体。}

コードインテリジェンス。 単独で動作するワーカーが tree-sitter（30 言語）でコードベースをインデックス化し、Neo4j にコードグラフを構築します。サーバーはソースファイルに一切触れることなく、グラフをクエリします。「このファイルに依存しているのは何か？」「この関数を呼び出しているのは誰か？」「影響範囲はどこまでか？」といった構造に関する質問をして、コードグラフから回答を得られます。呼び出しグラフの抽出、循環的複雑度、デッドコードの検出に対応しています。YAML ルールでアーキテクチャの境界を適用できます。プロジェクトをまたいで動作します。

対応言語（30）

カテゴリー	言語
システム	C, C++, Rust, Go, Zig
JVM	Java, Scala, Kotlin, Groovy
.NET	C#
スクリプト	Python, Ruby, PHP, Lua, Bash
ウェブ	TypeScript/TSX, HTML, CSS
Apple	Swift, Objective-C
ML／科学技術	OCaml, MATLAB
設定・データ	JSON, YAML, TOML, HCL (Terraform), Dockerfile, Makefile, SQL, Markdown

マルチユーザー認証と RBAC。 デフォルトでは無効で、コマンド 1 つでエンタープライズ向けの構成にできます。./scripts/setup.sh には認証設定が含まれています。または、単独で ./scripts/setup-auth.sh を実行してください。認証モードの選択（none / local JWT / OIDC SSO）、JWT シークレットの生成、OIDC プロバイダーの検証に対応しています。マシンクライアント向けの Personal Access Token、MCP 向けの stdio ID にも対応しています。3 つのロール、プロジェクト単位のスコープ設定、最初のユーザーを管理者にする機能を備えています。OIDC 同期に対応したグループも利用できます。**認証ガイド**を参照してください。

災害復旧。 PostgreSQL ダンプと Neo4j グラフのエクスポートに対応した、cron で実行できるスクリプトを用意しています。保持期間を設定できます。マイグレーションの安全性チェックを含む、テスト済みの復元手順を利用できます。**バックアップガイド**を参照してください。

LLM は必要ですか？

いいえ。保存、検索、想起、ルールは LLM なしで動作します。ただし、自動エンリッチメント（要約、タグ、重要度のスコアリング）、ナレッジ抽出、思考機能は利用できません。

エンリッチメントを利用する場合：

バックエンド	セットアップ
Ollama（デフォルト）	Ollama をインストールし、モデルをプルします。Cairn は host.docker.internal:11434 に接続します。
AWS Bedrock	CAIRN_LLM_BACKEND=bedrock を設定し、AWS 認証情報をエクスポートします。
Google Gemini	CAIRN_LLM_BACKEND=gemini を設定し、CAIRN_GEMINI_API_KEY を追加します。無料枠を利用できます。
OpenAI 互換	CAIRN_LLM_BACKEND=openai を設定し、キーを追加します。OpenAI、Groq、Together、LM Studio、vLLM で動作します。

設定

すべて環境変数で設定します。主な変数は次のとおりです。

変数	デフォルト	機能
CAIRN_PROFILE	(空)	プリセット：vector、enriched、knowledge、enterprise。機能のデフォルト値を設定します。
CAIRN_LLM_BACKEND	ollama	LLM プロバイダー：ollama、bedrock、gemini、openai
CAIRN_DB_PASS	cairn-dev-password	データベースのパスワード。ローカル環境以外では変更してください。
CAIRN_AUTH_ENABLED	false	マルチユーザー認証（JWT、PAT、OIDC/SSO）
CAIRN_AUTH_JWT_SECRET	(空)	JWT 署名シークレット（認証を有効にする場合は必須）
CAIRN_OIDC_ENABLED	false	OIDC/SSO 統合（OIDC 準拠のプロバイダーに対応）
CAIRN_MCP_OAUTH_ENABLED	false	リモート MCP クライアント（Claude.ai、モバイル）向け OAuth2 認可サーバー
CAIRN_GRAPH_BACKEND	(無効)	ナレッジグラフを有効にするには neo4j を設定します
CAIRN_KNOWLEDGE_EXTRACTION	false	保存時のエンティティ／ステートメント抽出
CAIRN_EMBEDDING_BACKEND	local	local（MiniLM、384 次元）または bedrock（Titan V2、1024 次元）
CAIRN_INGEST_DIR	/data/ingest	大きなドキュメントをファイルパスで取り込むためのステージングディレクトリ
CAIRN_CODE_DIR	/data/code	コードインテリジェンスのインデックス作成用ルートディレクトリ（コードベースをここにマウントします）

詳細なリファレンスは docker-compose.yml にあります。すべての変数に適切なデフォルト値が設定されています。

認証

デフォルトでは無効です。最も手軽に有効にする方法は、セットアップウィザードを使うことです。

./scripts/setup.sh          # includes auth as step 2
./scripts/setup-auth.sh     # or run auth setup standalone

認証モードは、認証なし、ローカル JWT、OIDC/SSO の 3 種類です。シークレットを生成し、ID プロバイダーのディスカバリーエンドポイントを検証して、.env を書き込みます。Authentik、Keycloak、Auth0、Okta、Azure AD 向けにプロバイダー固有の URL のヒントが表示されます。どちらのスクリプトも、CI 向けに --dry-run と --non-interactive をサポートしています。

最初に登録したユーザーが管理者になります。ロールベースのアクセス制御により、REST API、MCP HTTP、ウェブ UI 全体の権限が適用されます。マシンクライアント向けのパーソナルアクセストークンや、OIDC 同期に対応したグループも利用できます。

すべての認証モード、OIDC プロバイダーの設定、MCP クライアントの例を含む詳細なリファレンスは、認証ガイド をご覧ください。

セキュリティに関する注意： Cairn の認証システムは機能しており、本番環境でのテストも済んでいますが、第三者による監査は受けていません。ネットワークに公開する環境では、TLS 終端とネットワークレベルのアクセス制御を追加してください。

リモート MCP アクセス（Claude.ai、モバイル）

Cairn を Claude.ai、Claude モバイルアプリ、または OAuth2 対応の MCP クライアントに接続します。Cairn は OAuth2 認可サーバーとして動作し、ユーザー認証を既存の OIDC ID プロバイダーに委任します。

**前提条件：**認証を有効にする（CAIRN_AUTH_ENABLED=true）、OIDC を設定する（CAIRN_OIDC_ENABLED=true）、公開 URL を設定する（CAIRN_PUBLIC_URL）。

有効にする：

CAIRN_MCP_OAUTH_ENABLED=true

Claude.ai から接続する：

1. Claude.ai の［設定］>［インテグレーション］>［カスタム MCP を追加］に移動します
2. Cairn の URL を入力します：https://your-cairn-domain.com/mcp
3. Claude.ai が OAuth2 エンドポイントを自動的に検出します
4. ID プロバイダーにリダイレクトされ、ログインします
5. ログイン後、Claude.ai は Cairn の MCP ツールにフルアクセスできます

OAuth2 フローでは、Dynamic Client Registration（RFC 7591）を使用した Authorization Code + PKCE を使用します。ID プロバイダーが SSO セッションに対応している場合、初回ログイン後は認証リダイレクトが表示されません。

リバースプロキシの設定、セキュリティ強化、トラブルシューティングについては、**リモート MCP ガイド**をご覧ください。

コードインテリジェンス

コードインテリジェンスは、ソースコードをインデックス化して Neo4j に書き込むスタンドアロンワーカーとして実行されます。cairn サーバーはグラフをクエリしますが、ソースファイルには直接アクセスしません。この分離により、インデックス作成がイベントループをブロックせず、コードが存在するマシンでワーカーを実行できます。

**要件：**Neo4j（docker-compose の cairn-graph サービス）が実行されている必要があります。

クイックスタート

# Index a single project (one-shot, no watching)
python -m cairn.code \
  --watch /path/to/your/repo:your-project \
  --neo4j-uri bolt://localhost:7687 \
  --cairn-url http://localhost:8000 \
  --no-watch

# Index and watch for changes (long-running)
python -m cairn.code \
  --watch /home/user/working/myproject:myproject \
  --watch /home/user/working/other:other \
  --neo4j-uri bolt://my-server:7687

環境変数

変数	デフォルト	機能
CAIRN_NEO4J_URI	bolt://localhost:7687	Neo4j の bolt URI
CAIRN_NEO4J_USER	neo4j	Neo4j のユーザー名
CAIRN_NEO4J_PASSWORD	cairn-dev-password	Neo4j のパスワード
CAIRN_API_URL	http://localhost:8000	Cairn サーバーの URL（プロジェクト ID の解決用）
CAIRN_API_KEY	(空)	cairn の認証が有効な場合の API キー
CAIRN_CODE_PROJECTS	(空)	カンマ区切りの project=path ペア（--watch の代替）
CAIRN_CODE_WATCH	true	初回インデックス作成後のファイルシステム監視を有効にする
CAIRN_CODE_FORCE	false	コンテンツハッシュに変更がなくても強制的に再インデックスする

Docker／リモートコードベース

ソースコードを cairn コンテナにマウントし、CAIRN_CODE_DIR を設定します：

# docker-compose.yml
volumes:
  - /path/to/code:/data/code:ro   # read-only mount
environment:
  CAIRN_CODE_DIR: /data/code

または、コードホストでワーカーを実行し、cairn と Neo4j の各インスタンスを指定します：

CAIRN_NEO4J_URI=bolt://cairn-host:7687 \
CAIRN_API_URL=http://cairn-host:8000 \
CAIRN_CODE_PROJECTS="myproject=/home/user/code/myproject" \
python -m cairn.code

インデックス化される内容

• **シンボル：**関数、クラス、メソッド、インターフェース、列挙型、React コンポーネント／フック
• 関係：IMPORTS（ファイルレベル）、CALLS（関数レベル）、CONTAINS（親子関係）
• **メタデータ：**シグネチャ、ドキュメント文字列、循環的複雑度、行番号、コンテンツハッシュ
• **言語：**Python、TypeScript/TSX、その他 28 言語（C、Rust、Go、Java、Ruby など）

クエリの例（code_query MCP ツール経由）

アクション	機能
dependents	対象をインポートするファイル
dependencies	対象がインポートするファイル
callers	対象を呼び出す関数
callees	対象が呼び出す関数
call_chain	2 つの関数間の呼び出し経路を追跡する
dead_code	呼び出し元がない関数
complexity	循環的複雑度で関数を順位付けする
impact	影響範囲 — 推移的な依存先
hotspots	PageRank — 構造上重要なファイル
search	シンボル名とドキュメント文字列の全文検索

アーキテクチャ

MCP clients (Claude Code, Cursor, PiClaw)    REST clients (web UI, scripts)
        |                                            |
        | MCP (stdio or HTTP)                        | REST API
        |                                            |
+-------v--------------------------------------------v--------+
|  cairn.server (MCP tools)     cairn.api (FastAPI endpoints) |
|                                                             |
|  core: memory, search, enrichment, extraction, clustering   |
|        working memory, beliefs, thinking, work items        |
|                                                             |
|  embedding: local (MiniLM) or Bedrock (Titan V2)            |
|  llm: Ollama, Bedrock, Gemini, OpenAI-compatible            |
+------+----------------------------------------------+------++
       |                                              |       |
       v                                              v       |
  PostgreSQL 16 + pgvector                    Neo4j 5 <-------+
                                             (optional)       |
                                                ^             |
  code worker (python -m cairn.code)            |             |
  tree-sitter parsing, call graph      --------+             |
  watches filesystem for changes                             |

ベンチマーク

長期会話のメモリーベンチマークであるLoCoMoを使用してテストしました。5つのカテゴリーにわたる1,986問で構成されています。

システム	スコア	LLM
Cairn	81.6%	Llama-3.3-70B
人間のベースライン	87.9%	—
Letta/MemGPT	74.0%	GPT-4o-mini
Mem0	66.9%	GPT-4o

テスト構成：Titan V2埋め込み（Bedrock、1024-dim）、エピソード取り込み（生のターン＋2パスの事実抽出）、グラフ優先の検索を行うSearch V2、タイプ別ルーティング、クロスエンコーダーによる再ランク付け、LLMを審判とする評価。詳細な結果と手法については、eval/を参照してください。

開発

git clone https://github.com/jasondostal/cairn-mcp.git
cd cairn-mcp
cp .env.example .env
docker compose up -d --build

ステータス

Cairnは現在も活発に開発されています。これは本番環境で毎日使用されている実システムであり、エージェントのメモリに実際に有効なものを学ぶにつれて進化しています。スキーマの変更はマイグレーションで処理されます。問題が発生した場合は、issueを作成してください。

ライセンス

GNU General Public License v3.0