Cross-Agent Memory

エージェント横断メモリ

すべての AI コーディングエージェントで使える、1 つのローカルメモリ。
Claude Code の履歴、Codex のセッション、Cursor での作業、プロジェクトのドキュメントや決定事項を 一度だけインデックス化すれば、すべてのエージェントから検索でき、データはいつまでもあなたのものです。

日本語 | 中文

🎬 ▶ デモ全編を再生（2 分、中国語ナレーション）

https://github.com/user-attachments/assets/a8d5d77c-98bc-42f7-9c58-7b48295875fe

実際の操作：インストール → 確認 → 保存 → 検索。モックアップではありません。ポスターをクリックすると、ナレーション付きの 2 分間の手順説明を再生できます。

---

課題

すべての AI コーディングツールは、何も知らない状態から始まります。

Claude Code と 1 週間かけてアーキテクチャを設計し、翌週に Codex に切り替えても、決めたことやその理由は何も伝わっていません。コンテキストをもう一度貼り付け、プロジェクトについて説明し直します。3 つのツールを使うころには、同じ会話を 5 回も繰り返していますが、その内容を検索することはできません。

cross-agent-memory がこの問題を解決します。 小規模なローカルメモリサービスを実行し、次の機能を提供します。

1. 取り込み — あらゆる AI ツール（Claude Code／Codex 系の CLI／OpenCode／ZCode／…）のセッション履歴と、指定したあらゆるプロジェクトフォルダーを取り込みます。
2. インデックス化 — すべてをローカルの埋め込み表現でインデックス化し、検索可能な 1 つのストアにまとめます。
3. 提供 — HTTP API、または直接 MCP ツール としてすべてのエージェントに提供します。これにより、MCP 対応エージェントなら、ほかのすべてのエージェントやあなた自身がすでに見つけた情報を呼び出せます。

クラウド不要。アカウント不要。データがあなたのマシンの外に出ることはありません。

機能

• 🔒 ローカルファーストで、設計からプライバシーを重視 — 埋め込み表現の生成と検索はお使いの マシン上で実行されます（Ollama + SQLite + sqlite-vec）。機内モードでも利用できます。
• 🧠 ツール横断を前提に設計 — Claude Code、OpenCode、ZCode の セッションストア用コネクターに加え、あらゆるプロジェクト／ドキュメントフォルダーに対応する汎用ファイルウォッチャーを備えています。 どのツールで作成されたかにかかわらず、エージェントは 1 つの メモリを共有します。
• 🔌 1 行で MCP と連携 — memory_search、memory_write、 memory_stats を Model Context Protocol 経由で利用できます。Claude Code、 Codex CLI、Cursor など、MCP に対応するあらゆるツールで今すぐ使えます。
• ⚡ 実運用規模でも高速 — 大規模なコーパス向けに構築されています。sqlite-vec vec0 KNN による 1 ビットの粗い再現率フィルター と ホット／ウォーム／コールド階層化 を採用しています。リファレンス デプロイでは 2,000,000 個以上のチャンクを 0.36～1.20 秒で 検索します（ 実測値を参照）。
• 🛠 運用ツールも付属 — ヘルス／モニターエンドポイント、ローリングウィンドウによる劣化検出、バックアップと復元、スナップショットのアーカイブ、階層メンテナンス用スクリプトを備えています。
• 📈 実運用で検証済み — 4 つの異なる AI ツールが毎日 1 つのメモリを共有し、数百万のチャンクと日次の増分インデックス化を行う、継続稼働中のマルチエージェントシステムから抽出されました。

アーキテクチャ

        Claude Code      Codex-style CLI     OpenCode / ZCode      any project
             │                  │                  │                  │
             ▼                  ▼                  ▼                  ▼
      ┌────────────────────────────────────────────────────────────────────┐
      │                         Connectors / Indexers                      │
      │   incremental watermarks · content-hash dedup · active-session     │
      │   skip · unified chunker · local embeddings (Ollama, e.g. bge-m3)  │
      └────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
      ┌────────────────────────────────────────────────────────────────────┐
      │                      SQLite memory store (single file)             │
      │   chunks (source of truth)  ├─ vec0 KNN index (sqlite-vec)         │
      │   FTS-ready metadata        ├─ 1-bit recall codes (Hamming)        │
      │                             └─ hot / warm / cold tier tables       │
      └────────────────────────────────────────────────────────────────────┘
                                      │
                    ┌─────────────────┴───────────────────┐
                    ▼                                     ▼
        HTTP API (port 5370)                    MCP server (stdio)
        /api/search /api/memories               memory_search
        /api/stats  /api/health ...             memory_write / memory_stats
                    ▲                                     ▲
                    └─────────────────┬───────────────────┘
                                      │
                    every agent you use, in any language/tool

設計上の説明と検索パイプラインの全容は、 docs/ARCHITECTURE.md に記載されています。

🤖 AI エージェントにインストールしてもらう（一度貼り付けるだけ）

最も手早い方法は、このリポジトリを AI コーディングアシスタントで開き、以下のブロックを貼り付けることです。すべてをローカルにインストールします。仮想環境、依存関係、新しい独立したデータベースを用意し、実際の書き込みと検索の一連の動作を検証したうえで、正確なコマンドと結果を報告します。データが外部に送信されることはありません。エージェントはお使いのマシン上でのみ動作します。

Install this repository locally. Read AGENTS.md and INSTALL-FOR-AI.md first.
Use ./install.sh --dry-run, then ./install.sh. Keep all runtime data isolated
from existing databases and bind only 127.0.0.1. Verify initialization twice,
Ollama bge-m3, health, and a real write/search round trip using examples/run.py.
Add the client instructions from examples/client-instructions.md. Report exact
commands, results and blockers; do not claim success from health alone.
Do not import personal projects, restore backups or change system services.

自分で作業する場合は、すぐ下の手動手順をご覧ください。エージェント向けには、同じ手順が INSTALL-FOR-AI.md と AGENTS.md に記載されています。

クイックスタート

0. 前提条件

• macOS または Linux（Windows はまだサポートされていません。コネクターが POSIX ファイルロックを使用します）
• Python 3.10+
• ローカルで実行中の Ollama（埋め込み用）

ollama pull bge-m3            # ~1.2 GB, good multilingual embedding model

1. インストール

git clone https://github.com/indamices/cross-agent-memory.git
cd cross-agent-memory
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

2. サービスを起動する

python3 server.py
# Server listening on 127.0.0.1:5370

3. 記憶させる情報を登録する

任意のプロジェクトフォルダー（ドキュメント、決定事項、メモなど）を登録します。

curl -s -X POST http://127.0.0.1:5370/api/register \
  -H 'Content-Type: application/json' \
  -d '{"root": "/path/to/your/project"}'

フォルダーに .memory-service.yaml がない場合は、適切なデフォルト設定が使われます。詳しくは examples/ をご覧ください。ファイルはすぐにインデックス化され、その後の変更はデバウンス時間（デフォルトは 1 時間、MEMSVC_WATCH_DEBOUNCE）ごとにまとめて処理されます。すぐに反映するには、POST /api/reindex {"project": "..."} を実行するか、MEMSVC_WATCH_DEBOUNCE=0 を設定して起動します。

または、コネクターを使って AI ツールのセッション履歴を取り込みます。

python3 connectors/index_claude_code.py     # ~/.claude/projects/**/*.jsonl
python3 connectors/index_opencode.py        # ~/.local/share/opencode/opencode.db
python3 connectors/index_zcode.py           # ~/.zcode/v2/tasks-index.sqlite

4. どこからでも検索する

curl -s -X POST http://127.0.0.1:5370/api/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "why did we choose the tiered storage design", "n_results": 5}'

または、メモリに直接書き込みます（決定事項や洞察など。エージェントのフックに最適です）。

curl -s -X POST http://127.0.0.1:5370/api/memories \
  -H 'Content-Type: application/json' \
  -d '{"items": [{"type": "decision", "content": "We picked sqlite-vec over a server-based vector DB for local-first operation."}]}'

エージェントを接続する（MCP）

mcp_server.py は、メモリ API をツールとして公開する、依存関係不要の MCP（stdio）サーバーです。エージェントからこのサーバーを指定します。

Claude Code

claude mcp add memory -- python3 /ABS/PATH/cross-agent-memory/mcp_server.py

または .mcp.json に設定します。

{
  "mcpServers": {
    "memory": {
      "command": "python3",
      "args": ["/ABS/PATH/cross-agent-memory/mcp_server.py"],
      "env": { "MEMORY_SERVICE_URL": "http://127.0.0.1:5370" }
    }
  }
}

Codex CLI（~/.codex/config.toml）

[mcp_servers.memory]
command = "python3"
args = ["/ABS/PATH/cross-agent-memory/mcp_server.py"]
env = { MEMORY_SERVICE_URL = "http://127.0.0.1:5370" }

Cursor / その他の MCP エージェント — そのツールの MCP 設定に、同じサーバーコマンドと引数を指定します。MEMSVC_TOKEN を設定してサービスを起動した場合は、MCP サーバーにも MEMORY_SERVICE_TOKEN を設定してください。

接続すると、エージェントは次のツールを利用できます。

ツール	機能
memory_search	すべてのツールの、インデックス化されたすべてのセッション／プロジェクトを対象にセマンティック検索します
memory_write	今後のセッションで使えるよう、決定事項／洞察／発見を保存します
memory_stats	コレクションとそのサイズを一覧表示します

検索の仕組み

各 /api/search リクエストは、次の段階的なパイプラインを実行します。

1. クエリの埋め込み — Ollama を使ってローカルで計算し、テキストハッシュでキャッシュします。
2. 大まかな想起 — 各チャンクの次元ごとに 1 ビットのコードを使い、ハミング距離による事前フィルタリングを行います（小規模なコレクションでは自動的にスキップされます）。
3. 正確な KNN — 候補リストを対象に、sqlite-vec vec0 でコサイン KNN を実行します（sqlite-vec が利用できない場合は numpy の総当たり検索に切り替わります）。
4. 再ランキング — 時間減衰（半減期 30 日）＋ MMR による多様性の確保＋小さな helpful フィードバック係数を適用します。
5. 結果 — 各ヒットについて、テキスト、ソース、距離、スコアを返します。

内部では、重要ながら目立たない処理も行います。コンテンツハッシュによる重複排除、コネクターごとの増分処理ウォーターマーク、書き込み中のセッションのスキップ、バッチ書き込みの速度調整、WAL のチューニング、古くなったインデックスの自動修復などです。

実測値

参照用のデプロイ環境（複数エージェント構成で、このサービスを 24 時間 365 日稼働させている Mac mini M4 Pro）での値です。

指標	値
インデックス化されたチャンク	16 個のコレクションに 2,013,030 件
1 つのメモリを共有するツール	4（Claude Code、OpenCode、ZCode、OpenClaw）
/api/search のサンプルレイテンシ	0.36 秒～1.20 秒（本番環境での 5 件のクエリ、キャッシュがウォーム状態）
埋め込みモデル	bge-m3（1024 次元）、ローカルの Ollama
ストレージ	単一の SQLite ファイル＋派生した vec0 インデックス（いつでも再構築可能）

これらは、規模が大きく雑多で、絶えず増え続けるコーパスでの実測値であり、おもちゃのベンチマークではありません。コーパスのサイズやハードウェアによって結果は異なります。新しいデータベースなら、すべて 100 ミリ秒未満です。

API の概要

エンドポイント	メソッド	説明
/api/ping	GET	稼働確認（DB にアクセスしません）
/api/health	GET	埋め込みの状態、ディスク、縮退の理由を含むヘルス情報
/api/stats	GET	コレクション数とチャンク数
/api/projects	GET	設定済みのプロジェクト
/api/monitor	GET	レイテンシー／キャッシュ／ディスクのメトリクス
/api/search	POST	セマンティック検索（query、n_results?、project?）
/api/memories	POST	メモリー項目を直接取り込みます
/api/feedback	POST	チャンクを helpful／unhelpful としてマークします（ランキングに影響します）
/api/register	POST	インデックス作成対象としてプロジェクトディレクトリを登録します
/api/reindex	POST	強制的に再インデックスします（単一プロジェクトまたはすべて）
/api/backup / /api/restore	POST	データベースをバックアップ／復元します
/api/archive-snapshots	POST	古いスナップショットファイルを圧縮します

リクエスト／レスポンスの例を含む完全なリファレンス：docs/API.md。

設定

デフォルト設定のままですべて動作します。必要に応じて環境変数で調整してください。

変数	デフォルト値	用途
MEMSVC_PORT	5370	HTTP ポート
MEMSVC_DB	./memory.db	SQLite データベースのパス
MEMSVC_SEARCH_MODE	vec	vec（sqlite-vec）または legacy（numpy）
MEMSVC_BIT_RECALL	on	1 ビットの粗い検索候補の事前絞り込み（無効にするには off）
MEMSVC_MAX_CONCURRENCY	8	HTTP ワーカーの上限（超過時は即座に 503 を返します）
MEMSVC_STALL_WATCHDOG	on	検索が停止したときにスタックを出力します
MEMSVC_AUTH	(未設定)	1 でベアラートークン認証を有効にします（書き込みには Authorization: Bearer <token> が必要です）
MEMSVC_API_TOKEN	(未設定)	ベアラーシークレット。設定すると認証も有効になります
MEMSVC_READ_REQUIRES_TOKEN	(未設定)	1 で読み取りにもトークンを必須にします
MEMSVC_BACKUP_DIR	backups	データベースのバックアップディレクトリ
MEMSVC_SLOW_THRESHOLD_MS	8000	ヘルスチェックで使用する遅いクエリのしきい値
MEMORY_MISS_LEDGER	(無効)	結果がゼロまたは低品質だった場合の JSONL（書き戻し候補）
MEMORY_HITS_LEDGER	(無効)	クエリごとの上位ヒットをサンプリングする JSONL
CLAUDE_PROJECTS_DIR	~/.claude/projects	Claude Code コネクターのソース
OPENCODE_DB / OPENCODE_DBS	~/.local/share/opencode/…	OpenCode コネクターのソース
ZCODE_DB	~/.zcode/v2/tasks-index.sqlite	ZCode コネクターのソース
MEMORY_SERVICE_URL	http://127.0.0.1:5370	MCP サーバーで使用されます
MEMORY_SERVICE_TOKEN	(未設定)	認証が有効な場合に使用するベアラートークン

運用

• ヘルスチェック：GET /api/health は status、ディスク使用量、埋め込みの 可用性、縮退の理由（遅いクエリやディスク逼迫など）を報告します。 誤検知を避けるよう設計されており、cron や監視システムによる定期的なチェックに適しています。
• バックアップ：scripts/backup_silent.py（cron に適しています）または POST /api/backup を使用します。POST /api/restore で復元できます。
• 階層化（任意）：scripts/migrate_to_vec0.py で vec0 インデックスを構築します。 scripts/tier_rebuild.py ではホット／ウォーム／コールドの階層テーブルを構築し、 非常に大規模なコーパスでホットセットを小さく保ちます。
• スナップショットのアーカイブ：scripts/archive_silent.py。
• アラート付きヘルスチェック cron：scripts/health_check.py（Feishu Webhook による通知にも対応しています。.alert.env` を設定してください）。

設計上の選択（および対象外）

• ベクトルサーバーではなく SQLite。 ファイル 1 つで、サービスは不要、 簡単にバックアップでき、オフラインでも動作します。vec インデックスは派生データであり、再構築できます。
• API ではなくローカル埋め込み。 プライバシーを確保し、追加コストもかかりません。 別のモデルを使いたい場合は config.py でモデルを変更してください。
• ファイルを信頼できる唯一の情報源とします。 インデックス化されたデータはすべて ソースから再取り込みできます。データベースを削除しても、ディスク上のデータは失われません。
• クラウド同期製品ではありません。 1 台のマシンで複数のエージェントが 1 つの メモリーを使うためのローカルサービスです。マルチユーザー／サーバーモードはロードマップに含まれています。
• ベクトルデータベースのベンチマーク対象ではありません。 生の ANN スループットよりも、 依存関係を少なくすることと運用性を優先しています。

ロードマップ

• Web コンソール（メモリーの閲覧／検索／整理）
• コネクターの追加：Codex CLI セッションストア、Cursor、Aider、汎用 JSONL
• 抽出パイプラインを備えた、第一級のメモリータイプ（事実／教訓／コード変更のコンテキスト）
• 複数のハードウェアを使う人向けのマルチマシン同期
• ワンコマンドでインストールできる Python パッケージ／Docker イメージ

Issue や PR を歓迎します。特に、新しいコネクターをお待ちしています。CONTRIBUTING.mdをご覧ください。

謝辞

優れたツールを基盤として構築されています：SQLite、 sqlite-vec、 Ollama、numpy、 watchdog。

ライセンス

MIT © 2026 indamices