Kagura Memory Cloud

English · 日本語

AI エージェントとチームのための適応型メモリ — セルフホスト可能、RAG を超えて。
検索するたびに賢くなる MCP サーバー：
ハイブリッド検索と、どのメモリ同士が関連するかを学習するニューラルメモリグラフ。

Claude、ChatGPT、Gemini、およびMCP互換のあらゆるクライアントで動作します。
Python SDK（KaguraClient、REST クライアント、FileIngestor）

Claude Code CLI が MCP 経由で Kagura からメモリを呼び出す様子 — ▶ デモを見る

## Kagura Memory Cloud を選ぶ理由

AI は会話のたびにすべてを忘れてしまいます。Kagura はそれを解決し、検索するたびに賢くなります。

ほとんどの AI メモリーツールは、チャット機能を付けただけのベクトルデータベースです。Kagura は異なります。チーム規模で、完全な LLM ナレッジベースのパターン（Karpathy の LLM Wiki）を実装しています。

アプローチ	ストレージ	蓄積による成長	規模
ベクトル DB ／ RAG	埋め込みチャンク	なし — 検索のみ	任意
Karpathy の LLM Wiki	Markdown ファイル	LLM がページを書き換える	個人向け（約 100 ページ）
Kagura Memory Cloud	PostgreSQL + Qdrant + ニューラルグラフ	ヘブ学習 + スリープメンテナンス	チーム ／ 組織

機能	説明
適応型メモリー	検索するたびに、関連するメモリー間のつながりが自動的に強化されます。使うほどに、explore() が隠れた関連性をより見つけやすくなります。
ハイブリッド検索	セマンティック検索（OpenAI ／ セルフホスト型）+ BM25 キーワード検索 — 上位 1 件の精度は 96%
AI リランキング	セルフホスト型（Ollama/vLLM — ローカル、無料）、Voyage AI、または Cohere — 精度向上のためのクロスエンコーダーリランキング
ニューラルメモリーグラフ	ヘブ学習によって、バックグラウンドでナレッジグラフを構築します。explore() はグラフをたどり、思いがけない発見を促します。
エージェントメモリー基盤	単なるナレッジストアにとどまりません。配信モード（固定 ／ 時刻トリガー）、サーバーが付与する信頼境界、エージェント状態レーン、検索フィードバックシグナルを備え、自律型エージェントのループに必要なプリミティブを提供します。
エージェント制御プレーン（プレビュー）	ワークスペース単位のエージェントレジストリ、コンテキストを減算するバインディング、エージェントに紐づくメンバーキー、ライフサイクルのキルスイッチ、1 回の呼び出しによるセッションのブートストラップを提供します。v0.49.0 で導入されました。
72 個の MCP ツール	Guide、Memory、Agent Substrate、Agent Control Plane、Neural edges、Contexts、Tags、Files（R2）、Analyses（Memory Analysis）、Resources、Secrets、Sleep Maintenance、Usage、API-Key Bindings
マルチプロバイダー対応	埋め込みには OpenAI またはセルフホスト型（Ollama、vLLM — ローカル、プライベート、無料）を利用できます。
チーム利用に対応	ワークスペース、RBAC、コンテキスト分離、メモリー共有
Web UI	Next.js ダッシュボード — コンテキスト、検索設定、メンバー管理
5 分でセットアップ	./setup.sh を実行すれば完了です。

アーキテクチャ

Workspace (team/org)
├── Context A ("my-project")     ← like a folder
│   ├── Memory 1                 ← 3-layer: summary / context / content
│   ├── Memory 2
│   └── Neural edges (Hebbian)   ← automatic connections
├── Context B ("learning-notes")
│   └── ...
└── Members (Owner/Admin/Member/Viewer)

LLM ナレッジベース — 5 層の実装

Karpathy の LLM Wiki パターンは、従来の RAG を超える 5 層の「生きたナレッジベース」を説明しています。Kagura はその 5 層すべてをチーム規模で実装しています。

層	Kagura の実装	Karpathy のパターンとの違い
取り込み	REST /api/v1/memory、MCP remember、R2 ファイルストレージ、リソーストークン	+ バイナリデータ、+ マルチテナント
コンパイル	コンパイル API としての MCP — チャットエージェントが構造化されたツール呼び出し（remember(summary, content, type, tags)）でコンパイルし、スリープメンテナンスで一括統合します。	継続的なマイクロコンパイル（一括 Wiki 書き換えではありません）— スキーマで出力を強制
インデックス	3 種類のインデックス：BM25（キーワード）+ Qdrant（セマンティック）+ ヘブグラフ（関係性）— すべて自動管理	index.md を手動で保守する必要はありません
クエリ	ハイブリッド検索 + AI リランカー + explore によるグラフ探索	Markdown の grep を超え、セマンティック検索と関係性検索に対応
強化	ヘブ学習 — recall() のたびに、同時に取得されたメモリー間のエッジが強化されます。スリープメンテナンスによって定期的に統合されます。	LLM によるページ書き換えに対し、バックグラウンドでグラフが進化します（LLM コストゼロ）

蓄積による成長のループ：現在は明示的に行われます（回答を統合した後、ユーザー ／ エージェントが remember() を呼び出します）。ノイズを抑えるため、統合した回答の自動書き戻しは意図的にオプトイン方式にしています。

適応型メモリ：2 つの検索経路

Kagura では、高精度検索と探索を独立した 2 つの経路に分け、それぞれの目的に合わせて最適化しています。

recall()  ──→ Hybrid Search (semantic + BM25) ──→ [Reranker] ──→ Precise results
                      │
                      └──→ Hebbian Learning (background) ──→ Graph edges grow
                                                                │
explore() ──→ Graph Traversal (Neural Memory) ←─────────────────┘  Related discoveries

• recall() — 高精度検索です。ハイブリッド検索（セマンティック検索 60％＋BM25 40％）に、必要に応じて AI による再ランキングを加えます。最も関連性の高いメモリを返します。
• explore() — 探索です。Neural Memory グラフをたどり、キーワード検索では見つからない関連メモリを探します。
• ヘッブ学習 — recall() を実行するたびに、同時に取得されたメモリ間のエッジがバックグラウンドで強化されます。明示的な学習は不要です。システムを使ううちに、グラフが自然に成長します。

この分離は意図的なものです。グラフのシグナルを recall() に混在させると精度が低下することが、ベンチマークで検証されています（検証結果）。それぞれの経路が、最も得意とする処理を行います。

データの分離： すべてのデータは workspace_id → context_id → user_id の順にフィルタリングされます。メモリが境界を越えて漏れることはありません。Qdrant コレクションは 1 つだけで、ペイロードによるフィルタリングを行います。

技術スタック： FastAPI（非同期） · PostgreSQL · Qdrant · Redis · Next.js 16 · OAuth2 · Streamable HTTP による MCP

ベクトルバックエンド： デフォルトは Qdrant です。単一プロセスのセルフホスト／CLI／エッジ環境では、別途 Qdrant サーバーを用意せずに、組み込みの LanceDB バックエンド — 「Kagura Lite」（プレビュー） を実行できます（KAGURA_VECTOR_BACKEND=lance, cd backend && uv sync --locked --extra lite）。マルチワーカー環境や SaaS には適していません（LanceDB は単一ライターです）。デプロイ → 組み込みベクトルバックエンドをご覧ください。

クイックスタート

システム要件

	最低要件	推奨
CPU	2 コア	4 コア以上
RAM	4 GB	8 GB 以上
ディスク	10 GB の空き容量	20 GB 以上の空き容量

前提条件

• Docker と Docker Compose
• Python 3.11 以上
• Node.js 20 以上
• OpenAI API キー（埋め込み用）、またはローカル埋め込み用のセルフホスト型推論サーバー（例：Ollama）
• OAuth2 認証情報（任意。OAuth なしでも、パスワードと MFA によるログインが可能です）

セットアップ

1 行でセットアップ：

git clone https://github.com/kagura-ai/memory-cloud.git
cd memory-cloud
./setup.sh

Claude Code を使用する場合：

git clone https://github.com/kagura-ai/memory-cloud.git
cd memory-cloud
claude   # then run /setup

手順に沿ったセットアップ：

# 1. Clone
git clone https://github.com/kagura-ai/memory-cloud.git
cd memory-cloud

# 2. Configure environment (generates secrets, prompts for API keys)
(cd backend && python3 -m src.cli.setup_env)

# 3. Start all services
docker compose up -d

# 4. Run migrations
(cd backend && alembic upgrade head)

# 5. Create admin account (interactive — sets password, MFA, API key, embedding provider)
(cd backend && python3 -m src.cli.create_admin)

# Backend API:  http://localhost:8080
# Frontend UI:  http://localhost:3000
# API docs:     http://localhost:8080/redoc

.env.local の設定（setup_env により自動設定）：

設定	必須	説明
API_KEY_SECRET	はい	API キー暗号化用のシークレット（自動生成）
AUDIT_HMAC_KEY / AUDIT_PSEUDO_SALT	本番環境	監査ログ用 HMAC キーと消去用ソルト（自動生成）
OPENAI_API_KEY	はい*	埋め込み用の OpenAI API キー
SELF_HOSTED_BASE_URL	いいえ	セルフホスト型バックエンドの URL（デフォルト：http://localhost:11434）
EMBEDDING_PROVIDER	いいえ	openai（デフォルト）または self_hosted
GOOGLE_CLIENT_ID/SECRET	いいえ	Google OAuth2 ログイン（任意。パスワードでのログインも可能です）
GITHUB_CLIENT_ID/SECRET	いいえ	GitHub OAuth2 ログイン（任意）

* メモリ機能を使用するには、OPENAI_API_KEY または実行中のセルフホスト型推論サーバー（例：Ollama）のいずれかが必要です。

管理用 CLI

コマンド	用途
python3 -m src.cli.setup_env	シークレットを生成し、.env.local を設定します（Docker の起動前に実行）
python3 -m src.cli.create_admin	管理者、ワークスペース、API キー、.mcp.json、埋め込み設定を作成します
python3 -m src.cli.reset_password	パスワードや MFA をリセットします
python3 -m src.cli.delete_admin	管理者を削除します（再作成する場合）
python3 -m src.cli.transfer_context_creator	あるユーザーが作成したコンテキストを別のユーザーに移します（CLI 管理者 → OAuth アカウント。docs/deployment.md を参照）

backend/ ディレクトリから実行してください。Docker API コンテナが起動している必要があります。

プラットフォーム固有の注意事項

• WSL（Windows）：Windows 用 Docker Desktop をインストールし、WSL 統合を有効にします
• macOS：Mac 用 Docker Desktop をインストールします。brew install [email protected] node
• Linux（Ubuntu/Debian）：sudo apt install docker.io docker-compose-v2 python3.11 nodejs npm
• GCP（本番環境）：.env.local に本番環境の値（DATABASE_URL、QDRANT_URL、ENVIRONMENT=production、CORS_ORIGINS）と、非公開値である API_KEY_SECRET、AUDIT_HMAC_KEY、AUDIT_PSEUDO_SALT（openssl rand -hex 32）を設定します。デフォルト値または .env.example のプレースホルダーでは API の起動が拒否されます
• フロントエンドの環境変数：frontend/.env.example を frontend/.env.local にコピーして、次の値を設定します：
  • NEXT_PUBLIC_API_URL — バックエンドの URL（デフォルト：http://localhost:8080）
  • NEXT_PUBLIC_APP_URL — メタデータ用のフロントエンド URL
  • NEXT_PUBLIC_PLAN_FREE_DISPLAY_NAME / BASIC / PRO / PROMAX — プランの表示名をカスタマイズします（デフォルト：S/M/L/XL）

MCP クライアントを接続する

Claude Code、Claude Desktop、Claude Chat、ChatGPT、Gemini、Gemini CLI、および Streamable-HTTP MCP クライアントで動作します。

Claude Code（3 ステップ）：

1. サービスを起動し、http://localhost:3000/workspace/integrations/credentials?tab=api-keys を開いて API キーを作成します
2. .mcp.json.example を .mcp.json にコピーし、API キーを入力します（ここで作成したキーは、そのワークスペースにスコープが限定されます）：

cp .mcp.json.example .mcp.json
# Edit .mcp.json — set the API key

.mcp.json.example には、すべてのツールを利用できる URL が設定されています。"url" を次のいずれかに設定します：

• コアツール（デフォルト）： http://localhost:8080/mcp
• すべてのツール： http://localhost:8080/mcp?profile=full

OAuth クライアント（Claude.ai、Claude Desktop、ChatGPT、Gemini、Cursor、claude mcp add）は同じ /mcp URL を使用し、Web UI で選択したワークスペースに接続します。複数のワークスペースに所属している場合は、/mcp/w/{workspace_id} を指定すると、接続先を 1 つのワークスペースに固定できます。

デフォルト URL では、コアとなるメモリとコンテキストのツール（正確な一覧は「ツールプロファイル」を参照）が表示され、Sleep、分析、ファイル、エッジ、シークレット、リソース、エージェント制御プレーンは含まれません。これらは一覧に表示されないだけです。describe_tools を使うとセッション内で確認できます。多くのクライアントでは、モデルは一覧に表示されたツールしか呼び出せないため、これらが必要なタスクでは、以下の URL を使って再接続してください。クライアントにすべてのツールスキーマを最初から表示するには、?profile=full を追加します（一覧は約 2.6 倍になります）。ツールプロファイルを参照してください。

3. Claude Code を再起動して、動作を確認します：

You: "Remember: our API uses JWT with 1h expiry and refresh token rotation"
→ AI calls remember() — stored permanently

You: "What do we know about auth?"
→ AI calls recall() — finds it instantly, even months later

.mcp.json は .gitignore に含まれています。API キーが含まれるため、絶対にコミットしないでください。

全クライアントのセットアップ手順、メモリ同期フック、すぐに使える .claude/ テンプレート、kagura-memory Claude Code プラグイン（スキル＋ツールガードレールフック）、および WSL2 のネットワークに関する注意事項については、**MCP クライアントのセットアップ**を参照してください。

MCP ツール

14 カテゴリーにわたる 72 個のツール：ガイド（guide：必要に応じて参照できるツールマニュアル、describe_tools：URL に含まれていないツール）、メモリ（remember / remember_batch / recall / explore …）、エージェント基盤（ピン留めと時間指定による配信、決定論的な list / changes_since、1 回の呼び出しで行う bootstrap、状態、測定、フィードバック）、エージェントコントロールプレーン（プレビュー）、ニューラルエッジ、コンテキスト、タグ、ファイル（R2）、分析（メモリ分析）、リソース、シークレット（ゼロ知識）、スリープメンテナンス、使用状況、API キーバインディング。各ツールにはロールごとのアクセス制御があります。

必要なロールを含む、ツールごとのリファレンス：MCP ツールリファレンス

エージェントが書き込んだ内容は一覧表示して取り消せます。セッションごとに changes_since と rollback_session を使います（ステートレスな MCP クライアントは、_meta["ai.kagura/sessionId"] または Kagura-Session-Id ヘッダーで独自のセッションを指定できます）。セッション ID のないクライアントの場合は、自分が書き込んだ内容を時間範囲で指定します（by_me=true、since / until）。詳しくは、セッション ID を取得できるクライアントを参照してください。

クライアントは 72 個すべてを一覧表示する必要はありません。デフォルトの URL は上記のとおり、コアツール 22 個を一覧表示します（?profile=full ですべてを一覧表示）。?tools=remember,recall では指定したツールのみを一覧表示し、?add_tools=list_edges ではコアツールに指定したツールを追加して一覧表示します。詳しくはツールプロファイルを参照してください。

REST API

MCP ツールに加えて、完全な REST API を利用できます。

• メモリ：記憶、呼び出し、参照、削除、探索（/api/v1/memory/*）
• コンテキスト：CRUD、検索設定（/api/v1/contexts/*）
• エージェント（プレビュー）：レジストリ、コンテキストバインディング、統合されたブートストラップ（/api/v1/agents/*）
• ファイル：R2 を利用した署名付きアップロード／ダウンロード（/api/v1/files/*、最大 100 MiB）。従来の /api/v1/attachments/* ルートは 410 Gone を返します
• 分析：メモリ分析のプレビュー／開始／読み取り／キャンセル（/api/v1/analyses/*）
• リソース：外部イベントの取り込みとリソースの確認（/api/v1/resources/*）
• ワークスペース：管理、メンバー、招待（/api/v1/workspaces/*）
• 管理：ユーザー、プラン管理、ニューラル設定（/api/v1/admin/*）
• シークレット：ゼロ知識のシークレットストア。暗号文のみを保存し、サーバーが復号することはありません（/api/v1/config/secrets/*）

API ドキュメント全文：http://localhost:8080/redoc

認証

次の 2 つの OAuth2 プロバイダーに対応しています。

• Google OAuth2 — 任意です。GOOGLE_CLIENT_ID と GOOGLE_CLIENT_SECRET を設定してください
• GitHub OAuth2 — 任意です。GITHUB_CLIENT_ID と GITHUB_CLIENT_SECRET を設定してください

プロバイダーをまたいでメールアドレスが同じユーザーは、1 つのアカウントを共有します。OAuth プロバイダーがなくても、パスワードと MFA を使ったログインが可能です（クイックスタートを参照）。既存のアカウントでは、プロフィールからパスワードを追加し、確認済みのメールアドレスとそのパスワードでサインインすることもできます。詳しくはデプロイ → メールアドレスとパスワードでのサインインを参照してください。

プラン階層のカスタマイズ

プランでは、ワークスペースごとのリソース上限（コンテキスト／メモリ／1 日あたりの MCP 呼び出し回数）を管理します。デフォルトでは 4 つの階層が用意されています。S（free）、M（basic）、L（pro）、XL（promax）です。セルフホストのシングルユーザー環境では、ワークスペースに XL（promax）プランを割り当ててください。リソース、コネクター、公開コンテキストを作成できるのはこの階層のみです（数値の上限は環境変数で上書きできますが、階層の機能セットは変更できません）。デフォルト値、環境変数による上書き、任意の Stripe セルフサービス課金については、**デプロイ → プラン階層**を参照してください。

Claude Code での開発

このプロジェクトは、Claude Code と Kagura Memory Cloud 自体を活用して開発するように設計されています。事前設定済みのスラッシュコマンド、安全性フック、サブエージェント、ルールが .claude/ から自動的に読み込まれます。セットアップとツールのリファレンス全文については、**コントリビューション → Claude Code での開発**を参照してください。

ドキュメント

API リファレンス — 相互に補完する 2 つのエントリーポイント：

• 概念（Markdown）：API リファレンス — 認証、ベース URL、MCP エンドポイント、リクエスト／レスポンスの例
• エンドポイントリファレンス（ライブ）：http://localhost:8080/redoc — FastAPI から自動生成され、実行中のバックエンドと常に同期されます

概念とガイド：

• コアコンセプト — ワークスペース、コンテキスト、メモリ、ニューラルメモリ、MCP ツール
• MCP クライアントのセットアップ — Claude Code／Desktop／Chat、ChatGPT、Gemini、Gemini CLI、プラグインとテンプレート
• MCP ツールリファレンス — 必要なロールを含む全 72 個のツール
• アーキテクチャ — システム設計とデータフロー
• はじめに — 詳細なセットアップガイド
• チャンク分割ガイド — メモリ保存のベストプラクティス
• リソーストークンガイド — リソーストークンによる外部データの取り込み
• ニューラルメモリ評価 — ベンチマーク結果、アーキテクチャ上の判断
• 検索品質ベンチマーク — 精度テスト、再ランキング、ベストプラクティス
• 検索フィードバックと評価ゲート — フィードバックシグナルと自己更新ループを行わないポリシー（Agent Memory Substrate）
• デプロイ — Caddy リバースプロキシを使用した本番環境へのデプロイ
• コントリビューション — 開発環境のセットアップ、コードスタイル、PR ワークフロー
• セキュリティ — 脆弱性の報告、セキュリティ設計
• Python SDK — KaguraClient（MCP）に加え、リソース、ファイル、シークレット、ワークスペース、エージェントのブートストラップ用 REST クライアント、およびドキュメント用 FileIngestor
• プロジェクトサイト：www.kagura-ai.com — 概要、ユースケース、利用開始の手順

コントリビューション

開発環境のセットアップ、コードスタイル、PR ワークフローについては、CONTRIBUTING.md をご覧ください。

ライセンス

Apache License 2.0