Cortex Memory Engine

Cortex

🧠 ブラウザーで Cortex を試す — インストール不要、124KB の WASM で、すべてクライアント側で実行されます。

Cortex が AI の記憶に役立ったら、⭐を付けてください — 1 秒ででき、ほかの人がこのプロジェクトを見つけやすくなります。

中文 | 日本語 | 한국어

個人向け AI エージェントのローカルメモリー。

プライベート。無料。ローカル。— 個人向け AI エージェントのためのメモリーエンジンです。

AI の記憶アーカイブは、お使いのデバイスに保存されます。 純粋な Rust 製です。バイナリーは 3.8MB です。ローカルエンジンにホステッドサービスは不要で、テレメトリーも一切収集しません。暗号化同期は任意で、ご自身のクラウドストレージを使用します。Muse 共有も任意で、承認した抜粋だけを Cortex Cloud と Meta に送信します。（オンデバイスのセマンティック検索では、初回使用時に約 30MB のモデルを一度ダウンロードし、その後は完全オフラインで動作します。あるいは CORTEX_NO_EMBEDDINGS=1 で 100％オフラインにできます。セキュリティとプライバシーをご覧ください。）

利用できる機能

• 🔒 デフォルトでプライベート — 記憶はローカルの SQLite ファイルに保存されます。同期間と Muse 共有には明示的なオプトインが必要です。テレメトリーは一切ありません（CI で適用）。
• 🧠 テキストファイルではない、本物のメモリー — 4 つの階層、複数シグナルによる検索、自己修正型ベイズ信念、チャネルを横断する人物グラフを備えています。
• ⚡ サブミリ秒 — 取り込みは 156µs、検索は 568µs です。ネットワーク往復が不要で、クラウドメモリー API より約 528 倍高速です。
• 🔌 あらゆるエージェントにすぐ導入可能 — 1 つの MCP サーバーで、Claude Code／Claude Desktop（または任意の MCP クライアント）にセッションをまたいで持続するメモリーを提供します。
• 🤝 Meta Muse を選んだ抜粋に接続 — アーカイブはローカルに保存されたままです。任意のサービス https://cortex.alvinsclub.ai が提供するのは、承認済みのエクスポートのみです。開示には日次上限があり、取り消しも可能です。共有した抜粋はサーバーと Meta が読み取れます。セットアップとプライバシー上の制限 →
• ☁️ デバイス間でも自分のもの — 任意のエンドツーエンド暗号化同期を、ご自身の iCloud／Drive／Dropbox 経由で利用できます。この同期に Cortex サーバーは不要です。

セッションをまたいで記憶する様子をご覧ください — 約 30 秒：

brew install gambletan/tap/cortex-mcp-server          # or: cargo build --release -p cortex-mcp-server
claude mcp add cortex-memory -- cortex-mcp-server ~/.cortex/memory.db

Claude に 「Fly.io でデプロイすることと、プッシュ前に必ずテストを実行することを覚えておいて」 と伝えます。まったく新しいセッションを開いて、「このプロジェクトをデプロイするには？」 と尋ねてください。AI は記憶から回答します。すべてお使いのマシン上で動作します。

⭐ 役立ったら、スターを付けてください — プライバシーを尊重するメモリーエンジンを、ほかの人が見つける助けになります。

---

LLM はセッションごとに初期状態から始まります。あなたの名前や好み、昨日の会話、先週の決定を忘れてしまいます。一般的な対処法は、順位付けや減衰のない単純なテキストファイル、キーワード検索、または 200～500ms の遅延が発生し、料金がかかり、個人データが他人のサーバーに送られるクラウド API です。Cortex は、セッションやチャネルをまたいで保持され、自ら進化する構造化された長期メモリーを AI に提供します — すべてローカルに、すべてあなたのものです。 あなたの記憶がクラウドプロバイダーの学習データになったり、スタートアップの収益化資産になったり、監視の標的になったりすることはありません。

Cortex と Mem0 と OpenAI Memory の比較

	Cortex	Mem0	OpenAI Memory
プライバシー	ローカルアーカイブ。Muse によるクラウドへのエクスポートは任意	クラウド API（データは相手のサーバー上に保存）	OpenAI のサーバー
レイテンシ	156µsで取り込み、568µsで検索	約200～500ms	約300～800ms
コスト	永久に無料	月額99ドル以上（Pro）	ChatGPT Plus（月額20ドル）
メモリー階層	4（作業／エピソード／意味／手続き）	1（フラット）	1（フラット）
ベイズ的信念	証拠に基づいて自動修正	なし	なし
人物グラフ	チャネルをまたいだIDの解決	有料プランのみ	なし
会話の圧縮	セッションを自動で要約	なし	なし
関係性の推論	パターンベース（EN＋CN）	なし	なし
時間的な検索	意図を考慮（「最近」「初めて」など）	なし	なし
矛盾の検出	信頼度スコア付きで自動検出	なし	なし
統合	エピソードから意味へ自動昇格	なし	なし
コンテキストの注入	トークン予算に合わせたLLM対応の出力	手動	自動だが不透明
インポート／エクスポート	JSON による完全なバックアップと復元	API のみ	エクスポート不可
セルフホスト	ネイティブバイナリ、Docker、MCP	クラウドのみ	クラウドのみ
バイナリサイズ	3.8 MB	npm パッケージ	該当なし
依存関係	実行時サービス不要（単一バイナリ）	Node.js＋クラウド	該当なし
オープンソース	MIT	一部のみ	なし
暗号化	AES-256-GCM による暗号化同期（オプトイン）	なし	なし
鍵のローテーション	バージョン管理されたエンベロープ、前方秘匿性	なし	なし
プライバシーレベル	プライベート（デフォルト。同期されません）／共有／公開 — メモリーごとにオプトイン。降格すると他のデバイスから取り消されます	なし	なし
ツールの認可	MCP インターフェースでデフォルト拒否のケイパビリティポリシーを適用	なし	なし
テレメトリゼロ	分析なし、外部への通信なし、検証可能	不明	なし
コスト	永久に無料、無制限	月額99ドル以上（Pro）	月額20ドル（Plus）
中国語NLP	ネイティブ対応（推論、検索、関係性）	なし	限定的
名前空間の分離	ユーザー／コンテキストごとにメモリーを分離	なし	なし
プラグインシステム	取り込み／検索／統合用のコンパイル時フック	なし	なし
MCP ツール	Claude／LLM 連携用の30個のツール	サードパーティー	該当なし

パフォーマンスベンチマーク

操作	Cortex	Mem0（クラウド）	ファイルベース
取り込み	156µs	約200ms	約1ms
検索（上位10件）	568µs	約300ms	約10ms
コンテキスト生成	621µs	約500ms	手動
信念の更新	66µs	該当なし	該当なし
人物グラフ	51µs	有料プラン	該当なし
構造化された事実	45µs	該当なし	該当なし
1K件のメモリー検索	1.6ms	約500ms	約50ms

Mem0 クラウドより528倍高速です。Mem0 と OpenAI Memory のどちらにもない機能を備えています。

注： ベンチマークには、取り込みのたびに行うプロアクティブ推論（事実、好み、関係性の自動抽出）が含まれます。推論を行わない場合の生の取り込みは約15µsです。数値は M シリーズ Mac での cargo bench の結果です。

LoCoMo ベンチマーク（ACL 2024）

長期的な会話メモリを評価する学術水準のベンチマークです。4 つのカテゴリにわたり、10 件の会話と 1540 件の QA ペアで構成されています。

システム	単一ホップ	マルチホップ	オープンドメイン	時間関連	総合
Backboard	89.4%	75.0%	91.2%	91.9%	90.0%
MemMachine v0.2	—	—	—	—	84.9%
Cortex	72.5%	59.5%	88.8%	74.1%	73.7%
Mem0-Graph	65.7%	47.2%	75.7%	58.1%	68.4%
Mem0	67.1%	51.2%	72.9%	55.5%	66.9%
OpenAI Memory	—	—	—	—	52.9%

主な結果：

• オープンドメイン 88.8% — Mem0（72.9%）を +15.9% 上回ります
• 時間関連 74.1% — Mem0（55.5%）を +18.6% 上回ります
• 単一ホップ 72.5% — Mem0（67.1%）を +5.4% 上回ります
• マルチホップ 59.5% — Mem0（51.2%）を +8.3% 上回ります
• 総合 73.7% — Mem0（66.9%）を +6.8%、OpenAI Memory（52.9%）を +20.8% 上回ります

Cortex は 4 つすべてのカテゴリで Mem0 を上回ります。しかも、完全にローカルで実行され、エンドツーエンド暗号化に対応し、コストは $0 です。

セットアップ： Claude Sonnet 4（QA + 評価）、nomic-embed-text（Ollama 経由の埋め込み）、上位 30 件を検索。このセットアップで再現できます：python3 bench/locomo_bench.py（ANTHROPIC_API_KEY と nomic-embed-text を備えたローカル Ollama が必要です）。数値は v1.7 エンジンで測定したものです。v2.2 の検索ビーム修正（5K での言い換え再現率が 40%→90%、docs/scale-test-2026-06-13.md を参照）は、LoCoMo でまだ再実行されていません。そのため、これらは v2.2 の実績ではなく、最後に検証された数値として報告しています。

アーキテクチャ

Cortex は、人間の認知に着想を得た 4 層のメモリモデルを実装しています。

                    +---------------------+
                    |   Working Memory    |  Current session context
                    +---------------------+
                              |
                    +---------------------+
                    |   Episodic Memory   |  Raw experiences: conversations, events, observations
                    +---------------------+
                              |  consolidation (decay, promotion, pattern extraction)
                    +---------------------+
                    |   Semantic Memory   |  Distilled facts, preferences, relationships
                    +---------------------+
                              |
                    +---------------------+
                    | Procedural Memory   |  Learned routines, user-specific workflows
                    +---------------------+

作業メモリには、現在のセッションの一時メモを保持します。エピソード記憶には、タイムスタンプとソースメタデータを含む生の経験を保存します。統合エンジンは、繰り返し現れるパターンを定期的に意味記憶の事実へ昇格させ、古くなったエピソードを減衰させます。手続き記憶には、学習したワークフローや定型処理を記録します。

主なコンポーネント

人物グラフ

チャネルをまたいで ID を解決します。Telegram でメッセージを送信し、メールを送り、カレンダーの予定にも登場する同一人物を、単一の ID ノードに統合します。人物ごとに、やり取り、関係の強さ、コミュニケーションパターンを追跡します。

ベイズ信念システム

世界についての理解を自己修正します。信念は証拠から形成され、新たな観察のたびに更新され、反証されることもあります。確信度スコアは、直近の情報に偏ることなく、実際の確実性を反映します。

cortex.observe_belief("user_prefers_morning_meetings", true, 0.8)?;
cortex.observe_belief("user_prefers_morning_meetings", false, 0.6)?;
// Confidence adjusts automatically via Bayesian update

統合エンジン

エピソード記憶から意味記憶への昇格、古くなったメモリの減衰、パターンの抽出を行います。メモリストアをコンパクトで検索可能な状態に保つバックグラウンドサイクルとして動作します。昇格、減衰、統合された内容のレポートを返します。

マルチシグナル検索

クエリでは、関連度の順位付けに 5 つのシグナルを組み合わせます。

• 類似度 -- クエリの埋め込みに対するベクトルのコサイン距離
• 時間関連性 -- 設定可能な減衰を用いた新しさの重み付け
• 重要度 -- アクセスパターンと明示的なヒントに基づく重要度のスコアリング
• ソーシャル -- 特定の人物が関わるメモリを優先
• チャネル -- ソースチャネルによる絞り込みまたは優先

コンテキスト注入プロトコル

メモリの状態から、LLM が利用できるコンテキスト文字列を生成します。トークン予算と、任意のチャネル／人物フィルターを渡すと、LLM が直接利用できる構造化テキストブロックを返します。

ストレージ

永続化には SQLite、高速な類似検索にはインメモリのベクトルインデックスを使用します。単一ファイルのデータベースで、外部サービスは不要です。エッジ環境へのデプロイを想定しており、ノート PC、Raspberry Pi、サーバーで動作します。

クラウド同期

サードパーティのサーバーを介さず、独自のクラウドストレージを通じてデバイス間でメモリーを同期します。

Device A (Mac)              Your Cloud Storage              Device B (iPhone)
┌──────────┐         ┌──────────────────────┐         ┌──────────┐
│ SQLite DB │ ──W──>  │ iCloud / GDrive /    │  <──R── │ SQLite DB│
│ (local)   │         │ OneDrive / Dropbox   │         │ (local)  │
│           │ <──R──  │                      │  ──W──> │          │
└──────────┘         └──────────────────────┘         └──────────┘

• 変更履歴ベース：各デバイスは、専用のサブフォルダーに追記専用の操作ログを書き込みます
• 競合なし：デバイスが同じファイルに書き込むことはありません。マージでは、ハイブリッド論理クロックを使用した最終書き込み優先方式を採用しています
• 暗号化：AES-256-GCM 暗号化（任意）。クラウドアカウントが侵害されても、メモリーはプライベートな状態に保たれます
• 改ざん検知可能：同期マニフェストとすべての操作には HMAC が付与されます。改ざんされた oplog の行や平文が注入された行は拒否され、完全性保護のないマニフェストは読み込みを拒否します（キーをロールバックする方法はありません）
• キーのローテーションと前方秘匿性：履歴を再暗号化せずに新しいキー バージョン（ENC2 エンベロープ）へローテーションできます。古いバージョンは引き続き読み取り可能で、新しい書き込みは漏えいした古いキーでは読み取れません
• プライバシーを考慮したメモリーごとのオプトイン：プライベートなメモリー（デフォルト）はデバイスから外部に出ません。メモリーを shared にすると同期されます。再び private に戻すと、取り消しによってほかのデバイスから削除されます（ローカルコピーは保持されます）
• 再起動後も継続：同期設定はデータベースに保存されます（パスフレーズはディスクに保存されず、macOS のログイン Keychain または CORTEX_SYNC_PASSPHRASE を使用します）。サーバーは同期を再開し、バックグラウンドでの取得（30 秒ごとのポーリングと fs ウォッチャー）を自動的に開始します

対応プロバイダー：iCloud Drive、Google Drive、OneDrive、Dropbox（自動検出）。

use cortex_core::sync::SyncConfig;
use cortex_core::types::PrivacyLevel;

// Enable sync with encryption (settings persist; passphrase goes to the OS keychain)
let config = SyncConfig::new(sync_dir, device_id, device_name)
    .with_encryption("my-strong-passphrase");
cortex.enable_sync(config)?;

// Opt a memory into sync — everything is Private unless you say otherwise
cortex.set_memory_privacy(mem_id, PrivacyLevel::Shared { scope: "all".into() })?;

// Pull changes from other devices (also happens automatically in the background)
let applied = cortex.sync_pull()?;
println!("Applied {} remote changes", applied);

セキュリティとプライバシー

機能	詳細
暗号化	Argon2id による鍵導出を使用した AES-256-GCM（行ごとにランダムな nonce）
鍵のローテーション	バージョン管理された ENC2 エンベロープと、バージョンごとのパスフレーズ由来鍵を使用します。AES 鍵の流出に対する前方秘匿性を確保し、全面的な再暗号化も不要です
整合性	同期マニフェストとすべての同期操作に HMAC を適用します。暗号化された oplog 内の平文行は即座に拒否されます（インジェクション対策）
プライバシーレベル	Private（デフォルト。同期されません）、Shared、Public があります。取り込み時（privacy 引数／--privacy）または後から（memory_set_privacy）設定できます。Private に変更すると、他のデバイスからそのメモリが取り下げられます
機能ポリシー	MCP サーフェス上で、デフォルト拒否のツール認可を適用します。capabilities.json でツールグループ（read／write／sync／plugins）または個別のツールを許可します。許可されていないツールは表示されず、呼び出しもできません。不正なポリシーは安全側に倒して拒否されます
クエリ予算	すべての検索に上限を設けます（候補数の上限＋実時間の上限）。クエリのコストはストア全体のサイズに応じて増加しません。DoS 対策とタイミングサイドチャネルの制限を同時に実現します
シークレットの取り扱い	Cortex は同期パスフレーズをディスクに書き込みません。macOS のログイン Keychain または環境変数のみを使用します。パスフレーズがない場合は安全側に倒し、同期を無効にして平文を決して使用しません
メモリのゼロ化	破棄時に機密データを RAM から消去します（zeroize クレート）
テレメトリーなし	アナリティクスやテレメトリーはありません。ローカルコアのネットワーク依存関係は CI で強制的にチェックされます（scripts/check-no-network-egress.sh）。ネットワーク／テレメトリー用クレートが cortex-core のデフォルトツリーに入るとビルドは失敗し、このチェックでは --no-default-features バイナリが完全にネットワークを使用しないことも証明します
埋め込みモデルの取得（初回のみ）	デフォルトの cortex-mcp-server はデバイス上でのセマンティック検索を有効にします。初回の取り込み時に、Hugging Face CDN から約 30 MB のモデル（all-MiniLM-L6-v2）をダウンロードし、その後は完全にオフラインで動作し、データを一切送信しません。完全なオフライン環境では、CORTEX_NO_EMBEDDINGS=1（キーワード／FTS による検索。ネットワーク通信なし）を指定して実行するか、--no-default-features を指定してビルドしてください。ダウンロード前に stderr へ初回のみ通知が表示されます。何も通知せずに取得することはありません
Muse 共有（オプトイン）	ホスト型の Cortex Cloud は、OAuth、署名付きデバイス管理、日次予算、メタデータのみの監査を使用し、承認済みの抜粋のみを提供します。muse_unshare で抜粋を削除し、muse_disconnect でクラウドテナントを削除できます。セルフホスト型ゲートウェイも利用できます。Muse は開示されたコピーを保持する場合があります。Cortex からそれらを消去することはできません。ガイド
ローカル利用ではアカウント不要	ローカルエンジンに API キー、登録、クラウドサービスは不要です。ホスト型の Muse 共有では、ウェブアカウントを使わずに、デバイス管理型のクラウドテナントが作成されます

脅威モデルの全容については、SECURITY.md を参照してください。

前提条件

Rust ツールチェーン（cargo を提供）をインストールします。

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

インストール後、ターミナルを再起動するか、次を実行してください。

source "$HOME/.cargo/env"

確認します。

cargo --version

実際の使用例：本当に記憶するパーソナル AI

実際の会話を交わす 1 週間を通して、AI アシスタントが使われる様子を想像してみてください。

# Day 1 — You chat on Telegram
You: "Sarah works at Stripe. She's interested in our API."

  Cortex auto-extracts:
  ├── episodic memory stored (156µs)
  ├── fact: Sarah → works_at → Stripe (confidence: 0.70)
  └── person resolved: sarah_telegram

# Day 2 — Sarah emails you
From: [email protected]
"Here's the technical spec we discussed."

  Cortex:
  ├── person resolved: [email protected] → merged with sarah_telegram
  │   (same person, different channel — automatic identity resolution)
  └── fact: Sarah → sent → technical spec

# Day 3 — You ask your AI
You: "What's the status with Stripe?"

  Cortex retrieves (568µs):
  ├── Sarah works at Stripe (semantic fact)
  ├── Meeting went well, interested in API (episodic, Day 1)
  ├── She sent technical spec (episodic, Day 2)
  └── Cross-channel context: Telegram + Email unified under one person

  Your AI responds with full context — no "sorry, I don't remember" 🎯

# Day 5 — New information arrives
You: "Sarah now works at Anthropic."

  Cortex:
  ├── contradiction detected: Sarah works_at Stripe vs Sarah works_at Anthropic
  ├── old fact superseded + decayed: Stripe (salience ×0.3, kept as history)
  ├── new fact stored: Sarah → works_at → Anthropic
  └── current employer now ranks first; self-correcting, no manual cleanup

  (Third-party relations are extracted from natural-language verbs —
   "works at / works for / joined / now works at", "runs on", "hosted in",
   "manages", "part of", … — between two proper-noun entities.)

# Day 7 — Consolidation runs
  Cortex auto-consolidation:
  ├── 3 episodic memories about Sarah → promoted to semantic summary
  ├── stale memories from other topics → decayed
  └── pattern detected: you have recurring Monday meetings

これらはすべて 各操作 1 ミリ秒未満でローカルに実行されます。クラウドは使いません。API 呼び出しもありません。他の誰にもデータは見られません。

インストール

Homebrew（macOS／Linux）

brew tap gambletan/tap
brew install cortex-mcp-server

ソースから

cargo build --release -p cortex-mcp-server
cp target/release/cortex-mcp-server ~/.local/bin/

公式パッケージ（類似品にご注意ください）

Cortex は cortex-ai-memory という名前で公開されています。npm/PyPI には名前が似ていても、このプロジェクトとは無関係のパッケージがいくつかあります。必ず以下のパッケージをご利用ください。

エコシステム	公式パッケージ	用途
バイナリ／MCP サーバー	GitHub Releases、または brew install gambletan/tap/cortex-mcp-server	メモリエンジン（主用途）
PyPI	cortex-ai-memory	Python バインディング
npm	@cortex-ai-memory/cortex-memory（スコープ付き）	OpenClaw メモリプラグイン

⚠️ 当プロジェクトのものではありません： npm cortex-mcp、npm cortex-ai-memory（スコープなし）、PyPI cortex-memory。 正式な情報は常にこのリポジトリをご確認ください — github.com/gambletan/cortex。迷った場合は、Releases のバイナリが正式なインストール方法です。

クイックスタート

use cortex_core::Cortex;

// Open (or create) a memory database
let cortex = Cortex::open("memory.db")?;

// Ingest a memory from a Telegram conversation
let embedding = your_embedding_fn("Met with Alice about the Q3 roadmap");
cortex.ingest(
    "Met with Alice about the Q3 roadmap",
    "telegram",               // source channel
    Some("alice_123"),         // user ID (triggers identity resolution)
    Some(0.8),                 // salience hint
    Some(embedding),           // vector embedding
)?;

// Add a semantic fact directly
cortex.add_fact(
    "Alice", "works_at", "Acme Corp",
    0.95, "telegram", None,
)?;

// Store a preference
cortex.add_preference("timezone", "America/Los_Angeles", 0.9)?;

// Retrieve relevant memories
let results = cortex.retrieve(
    "What do I know about Alice?",
    5,                         // top-k
    None,                      // any channel
    None,                      // any person
    Some(query_embedding),     // vector for similarity search
)?;

// Generate LLM-ready context (token-budgeted)
let context = cortex.get_context(
    2000,                      // max tokens
    Some("telegram"),          // channel filter
    None,                      // no person filter
)?;
// Pass `context` as system/user message prefix to your LLM

// Run consolidation (call periodically)
let report = cortex.run_consolidation()?;
println!("Promoted: {}, Decayed: {}", report.promoted, report.decayed);

Python バインディング

PyO3 で構築されたネイティブモジュールで、PyPI から cortex-ai-memory（pip install cortex-ai-memory）として公開されています。

from cortex import Cortex

cx = Cortex.open("memory.db")
cx.ingest("Had lunch with Bob at the Thai place", channel="imessage", user_id="bob")
results = cx.retrieve("Where does Bob like to eat?", limit=5)

unified-channel-hub との連携

Cortex は unified-channel-hub のメモリレイヤーとして設計されています。あらゆるチャネルアダプターからメッセージが送られると、Cortex が取り込んでインデックス化します。また、コンテキスト注入プロトコルにより、応答の前に関連するメモリが LLM に渡されます。

Telegram ─┐                          ┌─ Context
Discord  ─┤  unified-channel-hub  →  │  Cortex  →  LLM
Email    ─┤  (ingest)                 │  (retrieve + inject)
Calendar ─┘                          └─ Response

LangGraph との連携

langchain-mcp-adapters を使えば、カスタムコードなしで、あらゆる LangGraph エージェントに永続メモリを追加できます。

from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI

model = ChatOpenAI(model="gpt-4o")

async with MultiServerMCPClient({
    "cortex": {
        "command": "cortex-mcp-server",
        "args": ["~/.cortex/memory.db"]
    }
}) as client:
    agent = create_react_agent(model, client.get_tools())
    # Agent now has all 30 Cortex memory tools
    result = await agent.ainvoke({
        "messages": [{"role": "user", "content": "What do you remember about Alice?"}]
    })

LangGraph エージェントは、memory_search、memory_ingest、fact_add、belief_observe、person_resolve をはじめ、さらに 25 個のツールをすぐに利用できます。すべてローカルで動作します。

DeerFlow（ByteDance）との連携

Cortex は、ByteDance のオープンソースのマルチエージェント・オーケストレーションプラットフォームである DeerFlow の永続メモリレイヤーとして動作します。コードの変更は不要です。

# Add to DeerFlow config.yaml
mcp_servers:
  cortex-memory:
    command: cortex-mcp-server
    args:
      - ~/.cortex/deerflow.db

DeerFlow のすべてのエージェント（Telegram、Slack、Feishu）は、30 個のメモリツールをすぐに利用できます。すべてのチャネルを横断したセッション間メモリ、事実の保存、人物グラフ、信念の追跡が可能です。

CLI

Cortex は単体の CLI ツールとしても使えます。MCP クライアントは不要です。

$ cortex-mcp-server --help
Cortex memory engine — MCP server & CLI tools

Usage: cortex-mcp-server [DB_PATH] [COMMAND]

Commands:
  ingest  Store a new memory
  search  Search memories
  stats   Show memory statistics
  sync    Show cloud sync status and detected providers
  export  Export all data as JSON
  import  Import data from JSON file
  info    Show version, DB path, and capabilities
  digest  Show weekly memory digest
  gateway Muse gateway: share an explicit slice of memory with Meta Muse over remote MCP
  help    Print this message or the help of the given subcommand(s)

Arguments:
  [DB_PATH]  Path to the Cortex database file (default: ~/.cortex/memory.db)

Options:
  -h, --help     Print help
  -V, --version  Print version

使用例：

# Store a memory
cortex-mcp-server ~/.cortex/memory.db ingest "Met with Alice about Q3 roadmap"
cortex-mcp-server ~/.cortex/memory.db ingest -c telegram "Sarah now works at Anthropic"

# Search
cortex-mcp-server ~/.cortex/memory.db search "Alice"
cortex-mcp-server ~/.cortex/memory.db search -l 10 "Q3 roadmap"

# Stats
cortex-mcp-server ~/.cortex/memory.db stats

# Cloud sync
cortex-mcp-server ~/.cortex/memory.db sync                        # status
cortex-mcp-server ~/.cortex/memory.db sync enable                  # auto-detect provider
cortex-mcp-server ~/.cortex/memory.db sync enable -p icloud        # specific provider
cortex-mcp-server ~/.cortex/memory.db sync pull                    # pull remote changes

# Export / Import (backup & restore)
cortex-mcp-server ~/.cortex/memory.db export -o backup.json
cortex-mcp-server ~/.cortex/new.db import backup.json

# Version & capabilities
cortex-mcp-server ~/.cortex/memory.db info

# Meta Muse gateway (see docs/muse.md)
cortex-mcp-server gateway allow "I prefer aisle seats"   # export one memory to Muse
cortex-mcp-server gateway preview "booking a flight"      # exactly what Muse would get
cortex-mcp-server gateway serve --oauth --public-url https://<you>.ts.net   # Muse signs in with OAuth
cortex-mcp-server gateway connect K7QM-2XDF               # approve a sign-in, on your computer only
cortex-mcp-server gateway off                             # kill switch

サブコマンドを指定しない場合は、MCP stdio モード（Claude Code／Claude Desktop との連携）で起動します。

MCP サーバー（Claude Code／Claude Desktop）

Cortex は MCP サーバーとして提供されており、MCP 互換のクライアントであればどれでも使用できます。

セットアップ

1. バイナリをビルドしてインストールします：

mkdir -p ~/.local/bin ~/.cortex
cargo build --release -p cortex-mcp-server
cp target/release/cortex-mcp-server ~/.local/bin/

2. MCP サーバーとして登録します：

Claude Code（CLI）：

# Global (all projects)
claude mcp add cortex --scope user -- ~/.local/bin/cortex-mcp-server ~/.cortex/memory.db

# Or per-project
claude mcp add cortex -- ~/.local/bin/cortex-mcp-server ~/.cortex/memory.db

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "cortex": {
      "command": "/Users/you/.local/bin/cortex-mcp-server",
      "args": ["/Users/you/.cortex/memory.db"]
    }
  }
}

3. 「don't ask」モードでツールを許可します：

~/.claude/settings.json の permissions.allow に追加します：

"mcp__cortex__*"

注：MCP ツールの権限では、括弧を使った形式（例：mcp__cortex__memory_ingest(*)）はサポートされていません。代わりにワイルドカード mcp__cortex__* を使用してください。

4. 自動化します — CLAUDE.md（プロジェクト用またはグローバルな ~/.claude/CLAUDE.md）に追加します：

# Memory (Cortex)
You have persistent memory via Cortex MCP tools. Use them automatically:
- Start of conversation: call `memory_context` to load what you know about the user
- When the user shares a preference, fact, or personal info: call `memory_ingest` to store it
- When you learn a structured fact: call `fact_add` (e.g. "User works_at Google")
- When you detect a preference: call `preference_set` (e.g. editor=neovim)
- When evidence supports or contradicts a belief: call `belief_observe`
- When talking to someone new: call `person_resolve` to track identity
- Periodically: call `memory_consolidate` to clean up stale memories

5. セッション開始時にメモリを自動注入します（Claude Code フック — 完全自動）：

~/.claude/hooks/cortex-memory-inject.sh を作成します：

#!/bin/bash
CORTEX_BIN="${CORTEX_BIN:-$HOME/.local/bin/cortex-mcp-server}"
CORTEX_DB="${CORTEX_DB:-$HOME/.cortex/memory.db}"
[ -x "$CORTEX_BIN" ] || exit 0

printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"hook","version":"1.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"memory_context","arguments":{"max_tokens":1500}}}' \
  | "$CORTEX_BIN" "$CORTEX_DB" 2>/dev/null \
  | grep '"id":2' \
  | python3 -c "import sys,json; r=json.load(sys.stdin); print(r['result']['content'][0]['text'])" 2>/dev/null

~/.claude/settings.json に追加します：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/cortex-memory-inject.sh"
          }
        ]
      }
    ]
  }
}

これで、Claude Code の新しいセッションが始まるたびに、メモリコンテキストが自動的に読み込まれます。手作業は一切不要です。作業を通じて Claude が学習し、セッションをまたいで記憶します。

デバイス間のメモリ同期

Claude のメモリは、MacBook、iMac、仕事用のノートパソコンなど、すべてのデバイスであなたについてきます。同期には、あなた自身のクラウドストレージを使用します。

同期を有効にする（1 つのコマンド）：

You: "Enable cross-device memory sync"

Claude calls sync_enable → auto-detects iCloud Drive →
  generates device ID + AES-256-GCM encryption key → done.

Output:
  Provider:   iCloud Drive
  Encryption: AES-256-GCM
  Passphrase: a1b2c3...  ← save this for your other devices

2 台目のデバイスでは、1 つのスクリプトですべてを実行します（ビルド／インストール、iCloud の待機、参加、復元）。

git clone https://github.com/gambletan/cortex && cortex/scripts/setup-device-sync.sh
# Prompts for your passphrase (hidden input; or set CORTEX_SYNC_PASSPHRASE)
# → full restore on join, passphrase saved to that device's login Keychain

または、会話形式で実行します。

You: "Enable sync with passphrase a1b2c3..."

Claude calls sync_enable(passphrase: "a1b2c3...") →
  connects to the same iCloud sync folder → pulls all memories.

Now both devices share the same memory — and keep sharing it
automatically (background sync: 30s poll + filesystem watcher).

同期されるものと、されないもの：

• プライベートメモリ（デフォルト）がデバイスの外に出ることはありません。メモリごとにオプトインできます。privacy: "shared" を指定して memory_ingest を実行するか、cortex-mcp-server ingest --privacy shared を実行するか、既存のメモリに対して memory_set_privacy を実行します。
• 共有メモリを private に戻すと、他のデバイスから**取り消され（削除され）**ます。ローカルのコピーは残ります。
• 同期データはすべて、HMAC による整合性検証を備えたAES-256-GCM で暗号化されます。クラウドアカウントが侵害されても、メモリはプライベートに保たれ、改ざんも検出されます。
• 再起動後も同期は維持されます。設定は永続化され、パスフレーズは OS のキーチェーンに保存され、サーバーは自動的に再開します。
• サーバーも API もアカウントも不要です。あなた自身のクラウドフォルダーだけで利用できます。

CLI での代替手段：

# Device A
cortex-mcp-server sync enable
# Save the passphrase from the output

# Device B
cortex-mcp-server sync enable --passphrase "your-passphrase-from-device-A"

# Manual pull (background sync also pulls automatically)
cortex-mcp-server sync pull

複数プロジェクトの分離

複数のプロジェクトを並行して作業していますか？別々のデータベースを使用してメモリを物理的に分離できます。プロジェクト間の情報漏えいはなく、コードの変更も不要です。

~/.cortex/
├── global.db          # User preferences, people graph, cross-project knowledge
├── my-app.db          # Project A memories
└── my-api.db          # Project B memories

グローバル設定（~/.claude/settings.json）— ユーザーレベルのナレッジ：

{
  "mcpServers": {
    "cortex-global": {
      "command": "~/.local/bin/cortex-mcp-server",
      "args": ["~/.cortex/global.db"]
    }
  },
  "permissions": { "allow": ["mcp__cortex-global__*", "mcp__cortex-project__*"] }
}

プロジェクトごとの設定（~/.claude/projects/<path>/settings.json）— プロジェクト固有の設定：

{
  "mcpServers": {
    "cortex-project": {
      "command": "~/.local/bin/cortex-mcp-server",
      "args": ["~/.cortex/my-app.db"]
    }
  }
}

次に、以下のメモリ分離ルールをプロジェクトの CLAUDE.md に追加します。

## Memory Isolation

Two Cortex MCP servers: `cortex-project` (project DB) and `cortex-global` (global DB).

### Write Policy
- Save to `cortex-project` if the memory is about this repo's architecture, code,
  modules, tests, workflows, configs, bugs, decisions, or terminology.
- Save to `cortex-global` only for long-term user preferences, communication style,
  cross-project habits, or personal background useful across repos.
- **Default: if uncertain, save to `cortex-project`.**

### Read Policy
1. Query `cortex-project` first.
2. Query `cortex-global` second, only for user-level preferences.
3. Prefer project memory when they conflict.

### Anti-Leak Rules
- Never auto-copy from `cortex-project` into `cortex-global`.
- Never store repo-specific paths, module names, or account names in `cortex-global`.
- Never treat project implementation details as user-global preferences.

### Update Rule
- Cortex is append-only. To update: search old entry → delete → ingest new.

これにより、プロジェクトごとに独立した Cortex インスタンスを 2 つ利用でき、ユーザーの共有ナレッジを保ちながら完全に分離できます。

30 個のツール

ツールへのアクセスは、任意で設定できる デフォルト拒否の機能ポリシー によって制御されます。データベースの隣に capabilities.json（{"version":1,"grants":["read","write"]}）を配置すると、許可されたツールグループ（read／write／sync／plugins／all）または 正確なツール名のみが一覧に表示され、呼び出し可能になります。ポリシーファイルがない場合は、すべて有効です（従来の動作）。

ツール	目的
memory_ingest	メモリを保存します（テキスト、チャネル、人物のコンテキスト、任意の privacy）
memory_set_privacy	メモリのプライバシーレベルを変更します。shared に昇格すると同期され、private に降格すると他のデバイスから取り消されます
memory_search	すべてのメモリ階層を対象にセマンティック検索します
memory_context	LLM 向けのコンテキスト要約を生成します（トークン予算に基づく）
memory_consolidate	減衰＋昇格＋一括処理のサイクルを実行します
memory_infer	保存せずに推論をプレビューします
memory_compress	古い会話セッションを圧縮します
memory_stats	メモリ統計情報（階層ごとの件数、インデックスサイズ）を取得します
memory_decay	エピソード記憶に時間的減衰を適用します
belief_observe	証拠を使ってベイズ信念を更新します
belief_list	信頼度のしきい値を超える信念を検索します
fact_add	構造化された知識（主語・述語・目的語）を保存します
fact_query	エンティティで事実を検索します（SQL インデックス付き）
preference_set	信頼度を付けてユーザーの好みを保存します
preference_query	キーパターンで好みを検索します
person_resolve	チャネルをまたいで人物の同一性を解決します
person_list	既知の人物をすべて一覧表示します
contradiction_check	事実の矛盾を確認します
relationship_extract	テキストから関係性を抽出します
sync_status	クラウド同期の状態（プロバイダー、デバイス、保留中の操作）を確認します
sync_providers	利用可能なクラウドストレージプロバイダーを検出します
sync_enable	任意の暗号化を使って、デバイス間のクラウド同期を有効にします
sync_pull	他のデバイスからリモートの変更を取得して適用します
memory_archive	メモリをコールドストレージにアーカイブします
memory_restore	アーカイブ済みのメモリをアクティブな階層に戻します
memory_delete	ID を指定してメモリを完全に削除します
memory_ingest_batch	単一のトランザクションで複数のメモリを取り込みます
tag_list_taxonomy	メモリ全体で使用中のタグを件数とともに一覧表示します
namespace_list	メモリ件数とともにすべての名前空間を一覧表示します
person_merge	2 つの人物 ID を 1 つに統合します

OpenClaw プラグイン

自動想起と自動記録を備えた永続メモリを OpenClaw エージェントに提供します。

インストール：

# 1. Install Cortex binary
curl -fsSL https://raw.githubusercontent.com/gambletan/cortex/main/install.sh | bash

# 2. Install the OpenClaw plugin
openclaw plugin add @cortex-ai-memory/cortex-memory

設定（任意 — デフォルト設定のままでも動作します）：

{
  "plugins": {
    "@cortex-ai-memory/cortex-memory": {
      "autoCapture": true,
      "autoRecall": true,
      "topK": 10
    }
  }
}

機能：

• autoCapture：各ターンの後に会話のコンテキストを自動的に保存します
• autoRecall：各ターンの前に関連するメモリを挿入します（エージェントが「記憶」します）
• 7 つのツール：memory_search、memory_store、fact_add、belief_observe、person_resolve など

設定オプションの詳細は、openclaw-plugin/README.md を参照してください。

プロジェクト構成

cortex/
├── cortex-core/          # Rust core library (all memory logic)
│   ├── src/
│   │   ├── lib.rs              # Cortex entry point
│   │   ├── types.rs            # MemObject, MemoryTier, etc.
│   │   ├── inference.rs        # Proactive inference (EN + CN)
│   │   ├── episode.rs          # Episodic memory store
│   │   ├── semantic.rs         # Semantic facts + preferences
│   │   ├── working.rs          # Working memory (session scratch pad)
│   │   ├── procedural.rs       # Learned routines
│   │   ├── people.rs           # People graph + identity resolution
│   │   ├── belief.rs           # Bayesian belief system
│   │   ├── consolidation.rs    # Episodic→semantic promotion + decay
│   │   ├── retrieval.rs        # Multi-signal retrieval engine
│   │   ├── context.rs          # LLM context generation
│   │   ├── sync/               # Cloud sync (oplog, HLC, merge, encryption)
│   │   └── storage/            # SQLite + in-memory vector index
│   └── benches/                # Performance benchmarks
├── cortex-http/          # HTTP REST API (axum, local-only)
├── cortex-mcp-server/    # MCP server binary (3.8MB)
├── cortex-python/        # Python bindings (PyO3, WIP)
├── openclaw-plugin/      # OpenClaw memory plugin
├── Dockerfile            # Self-hosted Docker image
└── Cargo.toml            # Workspace root

HTTP API

Cortex には、あらゆる言語やフレームワークとの連携に使える軽量な HTTP サーバーが付属しています。デフォルトでは 127.0.0.1 にバインドされるため、データがマシンの外部に出ることはありません。

# Build & run
cargo build --release -p cortex-http
./target/release/cortex-http --port 3315 --db ~/.cortex/memory.db

# Or via Docker (pre-built from GHCR)
docker run -v ~/.cortex:/data -p 3315:3315 ghcr.io/gambletan/cortex/cortex-http:latest

# Or build locally
docker build -t cortex .
docker run -v ~/.cortex:/data -p 3315:3315 cortex

エンドポイント

メソッド	パス	説明
GET	/health	ヘルスチェック
POST	/v1/memories	メモリーを取り込む
POST	/v1/memories/search	セマンティック検索
GET	/v1/memories/context	LLM コンテキストを生成
POST	/v1/memories/consolidate	統合サイクルを実行
POST	/v1/memories/infer	推論をプレビュー（保存なし）
POST	/v1/facts	セマンティックファクトを追加
POST	/v1/facts/contradictions	矛盾を確認
POST	/v1/preferences	設定を指定
GET	/v1/beliefs	信念の一覧を取得
POST	/v1/beliefs/observe	証拠を使って信念を更新
POST	/v1/people	人物の身元を特定
POST	/v1/memories/compress	古い会話セッションを圧縮
POST	/v1/relationships/extract	テキストから関係性を抽出
GET	/v1/export	すべてのデータをエクスポート（JSON バックアップ）
POST	/v1/import	バックアップからデータをインポート

使用例

# Store a memory
curl -X POST http://localhost:3315/v1/memories \
  -H 'Content-Type: application/json' \
  -d '{"text": "I prefer dark mode", "channel": "cli"}'

# Search
curl -X POST http://localhost:3315/v1/memories/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "preferences", "limit": 5}'

# Export all data (backup to iCloud, NAS, etc.)
curl http://localhost:3315/v1/export > ~/iCloud/cortex-backup.json

# Import from backup
curl -X POST http://localhost:3315/v1/import \
  -H 'Content-Type: application/json' \
  -d @~/iCloud/cortex-backup.json

ロードマップ

• v0.2 ✅ — ローカル埋め込みの統合（all-MiniLM-L6-v2/ONNX）、バッチクエリ、重要度を考慮した減衰と自動統合
• v0.3 ✅ — プロアクティブな推論（ファクトの自動抽出）、時間認識、矛盾検出、中国語 NLP
• v0.4 ✅ — HTTP REST API（axum）、インポート／エクスポート（JSON バックアップ）、Docker パッケージング
• v0.5 ✅ — 会話の圧縮、関係性の推論（EN + CN）、時間的検索の強化、112 件のテスト
• v1.0 ✅ — 機能比較表、ベンチマークの更新、Cortex、Mem0、OpenAI の 18 機能比較
• v1.1 ✅ — HNSW ベクトルインデックス（5 万件の検索：12ms → 91µs）、Python SDK（pip install cortex-ai-memory）
• v1.2 ✅ — 否定表現の検出（EN + CN）、マルチホップ検索、117 件のテスト
• v1.3 ✅ — コンテキスト品質の最適化、クエリ拡張、双方向の関係性、126 件のテスト
• v1.4 ✅ — 増分 HNSW、SQL インデックス付きエンティティクエリ、LLM 要約フック、18 個の MCP ツール、減衰の設定、LLM 支援推論、131 件のテスト
• v1.5 ✅ — Docker イメージ（GHCR による自動公開）、バッチ取り込み、重複排除、名前空間の分離、プラグインシステム、イベントバス、アーカイブ、351 件のテスト
• v1.6 ✅ — Int8 量子化（ストレージを 75% 削減）、マテリアライズドカラムインデックス、FTS5 トリガー、LRU キャッシュ（MemObject + entity-facts）、rayon による並列減衰、Arc 埋め込み、世代ベースのキャッシュ無効化、25 個の MCP ツール、バッチ推論、中国語 NLP の強化
• v1.7 ✅ — クラウド同期（変更ログベース、HLC 順序付け、LWW マージ）、AES-256-GCM 暗号化（Argon2id KDF）、プライバシーの適用（Private/Shared/Public）、zeroize（メモリーの消去）、SECURITY.md、27 個の MCP ツール、400 件以上のテスト
• v2.0 ✅ — バックグラウンド同期（ファイルシステム監視 + ポーリング）、Web ダッシュボード、Homebrew tap、統合ドキュメント（CrewAI/AutoGen/LangGraph/DeerFlow）、/v1/memories/recent API、Codex レビュー修正 12 ラウンド、489 件のテスト
• v2.1 ✅ — WASM ビルド（124KB、ブラウザー内で完全に動作、GitHub Pages デモ）
• v2.2 ✅ — セキュリティ強化シリーズ（自己進化イテレーション 11～17）：マニフェスト + 操作ごとの HMAC、平文インジェクションの拒否、タイミング攻撃への耐性強化、前方秘匿性を備えた鍵ローテーション（ENC2）、クエリ予算の上限設定、デフォルト拒否の MCP ケイパビリティポリシー、メモリーごとのプライバシーオプトインとデバイス間の撤回、永続同期（Keychain）+ 自動バックグラウンド同期、フリークエンシーランキング、ワンショットのデバイスセットアップスクリプト、30 個の MCP ツール、500 件以上のテスト
• v2.3 — モバイル向けターゲット（iOS/Android）、マルチモーダルメモリー

---

Cortex が役に立った場合は、ぜひスター ⭐ を付けてください。ほかの人がこのプロジェクトを見つけやすくなり、開発継続の励みになります！

ライセンス

MIT