Cortex

問題

あなたのコーディングエージェントは火曜日に厄介なバグを修正します。水曜日には新しいコンテキストウィンドウが開き、そのバグが存在したことすら分からなくなります。あなたは同じ説明をもう一度貼り付けることになります。

Cortex は、MCP を通じてエージェントが自ら書き込み・読み出しを行うメモリを提供します。構造化されたメモリ（bug_fix、decision、discovery、pattern、preference など）は、プロジェクトごとにスコープされ、関連性でランク付けされ、時間とともに減衰し、同じ症状が再発したときに再浮上します。

すべてのデータはマシン上の単一の SQLite /file に保存されます（~/.memoria/memoria.db）。アカウントも API キーもテレメトリも不要です。

Related MCP server: exocortex

含まれているもの

• 20のMCPツール — save / search / context / recall / hint / feedback / sessions / reflections / forget（全一覧）。

• ハイブリッド検索 — SQLite FTS5 のキーワード検索を、Reciprocal Rank Fusion によるベクターKNNと融合。埋め込みはオプションで、ローカルで実行されます（@xenova/transformers、384次元 MiniLM、約22MB、CPU）。

• 結果に応じた信頼度 — エージェントは提示されたメモリが 役に立った か 古かった か 誤誘導した かを報告します（memoria_feedback）。その信頼スコアが将来の検索結果を再ランク付けします。

• プロアクティブなヒント — memoria_hint はこれから行うツール呼び出し / プロンプト / ファイルパスを受け取り、前もって 挿入するための短いヒントを最大3つ返します。

• リフレクション — CPU のみのクラスタリング処理が関連メモリをグループ化し、エージェントの LLM がメタレッスンを統合します（Cortex 自身は LLM を呼び出しません）。

• 減衰と忘却 — 関連度は時間とともに減衰し、memoria_forget がプレビュー（デフォルトはドライラン）して下限をソフトデリートします。

• デフォルトでプライバシー保護 — API キー、PAT、JWT、SSH キー、<private>...</private> ブロックは、ディスクに書き込まれる前に除去されます。

• 運用対応 — 構造化 JSON ログ、Prometheus メトリクス（/api/metrics）、クォータ、オプションのベアラ認証、マルチテナントワークスペース。

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

要件は次のとおりです。Node >= 20（22 と 26 で検証済み）、git。better-sqlite3 はインストール時にビルドするか、prebuilt バイナリをダウンロードします。他に依存関係はありません。

git clone https://github.com/gonzalonicolasr/cortexmem.git
cd cortexmem
npm install
npm test          # optional: 216 tests, ~1s

あるいはクローンせずにインストールすると、cortexmem コマンドが PATH に追加されます:

npm install -g github:gonzalonicolasr/cortexmem
cortexmem --version

単純な CLI としてスモークテスト:

node bin/memoria.mjs save "Fix hydration bug" \
  --type bug_fix --what "moved the fetch out of useEffect" \
  --project demo --learned "SSR/CSR mismatch, not a race condition"

node bin/memoria.mjs search hydration --project demo
node bin/memoria.mjs stats

これで完了です。初回書き込み時に ~/.memoria/memoria.db にデータベースが作成されます。

エージェントに組み込む

Cortex は stdio 経由で MCP を話します。グローバルインストールした場合のコマンドは cortexmem mcp です。クローンを使う場合は、bin/memoria.mjs の絶対パスを node に渡してください。

claude mcp add cortex -- node /absolute/path/to/cortexmem/bin/memoria.mjs mcp
claude mcp list | grep cortex     # → ✓ Connected

[mcp_servers.cortex]
command = "node"
args = ["/absolute/path/to/cortexmem/bin/memoria.mjs", "mcp"]

{
  "mcpServers": {
    "cortex": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/cortexmem/bin/memoria.mjs", "mcp"]
    }
  }
}

pi 用の MCP 拡張機能をインストールし、上記の JSON 例と同じコマンド / 引数のペアを指定します。HTTP トランスポートもサポートしています。詳細は docs/self-hosting.md を参照してください。

設定を編集したあとはクライアントを再起動してください — Codex と Claude Code は設定をホットリロードしません。

エージェントに実際に使わせる

ツールだけでは不十分です。エージェントは いつ 書き込むかを知る必要があります。CLAUDE.md（メモリプロトコル）をエージェントの指示ファイル（CLAUDE.md、AGENTS.md、.cursorrules、pi の AGENTS.md など）にコピーしてください。約40行のガイドで、バグ修正・意思決定・発見・設定変更後に自動保存し、セッション開始時に memoria_context を呼ぶようエージェントに指示します。

CLI

memoria mcp                    Start the MCP server (stdio)
memoria serve [port]           Start the HTTP API (default 7437, loopback-only)
memoria save <title> [flags]   Save a memory
memoria search <query>         Full-text search
memoria context [project]      Print the project context block
memoria recent [flags]         Recent memories
memoria stats                  Counts by type / project
memoria projects               List projects
memoria decay                  Apply relevance decay

フラグ: --project --type --limit --what --why --where --learned --topic.

サーバーモード

ホームラボのすべてのマシン / エージェントでメモリを共有したい場合は、HTTP API を実行し、リバースプロキシを前面に配置します:

MEMORIA_HOST=127.0.0.1 MEMORIA_AUTH_TOKEN=$(openssl rand -hex 24) \
  node bin/memoria.mjs serve 7437
curl -s localhost:7437/api/health

エンドポイント リファレンス: docs/http-api.md。systemd ユニット、ベアラ認証、埋め込みのバックフィル、リフレクションの cron、バックアップについては、docs/self-hosting.md を参照してください。

⚠️ HTTP サーバーは X-Workspace-Id ヘッダーを信頼します（マルチテナント設計: 上流プロキシがユーザーを検証してそれを注入します）。MEMORIA_AUTH_TOKEN と proxy を前面に入れずに、void 常に no ce引出し性があります。

セマンティック検索（オプション）

npm install @xenova/transformers          # already an optionalDependency
export MEMORIA_SEMANTIC_SEARCH=1
node bin/backfill-embeddings.mjs          # embed existing memories

モデルは一度だけダウンロードされ（約22MB）、CPU 上で動作します。このフラグを有効にすると、memoria_search と memoria_recall はハイブリッド（FTS5 + KNN を RRF で融合）になります。無効の場合は、純粋なキーワード検索としてすべて動作します。非英語メモリの場合は、バックディルの前に MEMORIA_EMBEDDING_MODEL=Xenova/paraphrase-multilingual-MiniLM-L12-v2 を設定します（同じ 384 次元）。— セマンティック検索 を参照。

環境変数

クォータ

デフォルトはマルチテナントのホスティング環境向けに設定されています: アクティブなメモリは 1,000 件、論理テキスト 10 MB、プロジェクト 50 件、アクティブ セッション 5 件、メモリ 1 件あたり 32 KB。パーソナルなローカル環境では、値を上げてください:

export MEMORIA_UNLIMITED_WORKSPACES=1   # workspace 1 = the CLI/stdio default

MCP ツール

ツール名は、既存インストールとの後方互換性を保つために memoria_ プレフィックス（プロジェクトの元の名前）を維持しています。

データ、プライバシー、バックアップ

• 単一の SQLite ファイル（WAL モード）。sqlite3 ~/.memoria/memoria.db ".backup out.db" でバックアップできます。

• シークレットは行が書き込まれる前に削除されます: AWS キー、GitHub/GitLab PAT、OpenAI/Anthropic/Slack/Google/Stripe/Cloudflare キー、JWT、SSH 秘密鍵、および <private>...</private> で包んだ内容。これは安全ネットであり、シークレットを貼り付けていいというライセンスではありません。

• マシンの外部にデータが送信されるのは、自分自身 で HTTP サーバーを運行して公開しない限りありません。

開発

npm test          # vitest, 216 tests
npm run test:watch

多言語埋め込みテストは MEMORIA_TEST_MULTILINGUAL=1 というフラグでガードされているため、通常のスイートではモデルをダウンロードしません。変更履歴: CHANGELOG.md。

ホスティング（オプション）

自分で動かしたくない場合は、同じエンジンが cortexmem.com でホストされています。サインアップし、パネルから cc_... API キーをコピーして、ローカルコマンドの代わりにクライアントを HTTP エンドポイントに向けてください:

claude mcp add cortex https://cortexmem.com/api/cortex/mcp \
  --transport http --header "Authorization: Bearer cc_YOUR_KEY"

# ~/.codex/config.toml
[mcp_servers.cortex]
url = "https://cortexmem.com/api/cortex/mcp"

[mcp_servers.cortex.http_headers]
Authorization = "Bearer cc_YOUR_KEY"

セルフホスティング版は完全な機能を維持します。ホスト版は Web パネルと brain graph を追加するもので、メモリ本体ではありません。

ライセンス

MIT © Gonzalo Rocca — LICENSE を参照。