hypermnesia-mcp

責任の所在を確認できる、AI コーディングエージェント向けメモリ。
セッションをまたいで決定事項、修正内容、プロジェクトのコンテキストを保持し、何が取得されたかを確認できます。
デフォルトではローカルで動作します。アカウントも API キーも、管理するサーバーも不要です。

現在の Sovereign は、このような仕組みです。 すべてがお使いのマシン上で動作します。デフォルトではローカルの SQLite ファイルを使い、必要に応じて PostgreSQL + pgvector を選べます。検索処理に LLM は使わず、データが localhost の外に出ることもありません（外部に接続するインテグレーションを設定した場合を除きます）。プロジェクトのメモリは、ご自身が所有し、削除できるファイルです。

Claude Code と Codex で Cortex のメモリを共有できます。 どちらのネイティブプラグインでも、同じメモリツールと、記録、想起、プロジェクトのコンテキスト取得を自動化する 11 個のライフサイクルフックモジュールを利用できます。プロジェクトでどちらのエージェントを使っても、切り替え後にメモリを引き継げます。 macOS で実際の Claude および Codex セッションを使って検証済み。 同じ stdio MCP サーバーは、Claude Desktop、Claude Cowork、その他のローカル MCP ホストにもメモリツールを提供します。

環境に配慮したソフトウェアを目指しています。 データセンターに届かない処理は、電力を必要としません。また、エージェントが最初から適切なコンテキストを見つければ、読み直すファイルも少なくなります。この方針に基づき、 Green Software Foundation の SCI メソッドを採用しています。また、測定していないため、CO₂ 排出量やエネルギー消費量の数値は公表していません。 公表する内容としない内容 ↓

神経科学に基づく 36 のメカニズム · 57 個のメモリツール · 11 個のライフサイクルフック · プロジェクトごとに自動で整理される Wiki — すべてローカルで動作する、MIT ライセンスのオープンソースです。

インストール

Claude Code — マーケットプレイスを追加してプラグインをインストールします。

claude plugin marketplace add cdeust/Cortex
claude plugin install hypermnesia-mcp
claude --init-only

claude --init-only はプラグインの Setup フックを実行し、最初のセッションの前に Cortex のランタイム（基本的な依存関係、セマンティック検索、その埋め込みモデル）をインストールします。このコマンドは何も出力せず、インストールに失敗しても終了コード 0 で終了します（Claude Code は Setup フックの出力を破棄するためです）。進行状況を確認し、失敗時にエラー終了コードを受け取るには、代わりにインストール済みプラグインから scripts/init_plugin.py を実行してください（そのパスは claude plugin list --json の installPath です）。

同じ方法で、コマンドを 1 つ実行して更新し、再度初期化します。

claude plugin update hypermnesia-mcp
claude --init-only

Claude Desktop — Releases から hypermnesia-mcp.mcpb をダウンロードして開くか、Settings → Extensions を使用してください。バンドルにはツールが含まれますが、フックは含まれません。MCPB 形式にはフックがありません。

Claude Cowork は自動検出され（CLAUDE_ENVIRONMENT=cowork）、ローカルの SQLite ストアを使用します。PostgreSQL は不要です。

Codex では、メモリツールと自動フックを使うためにネイティブプラグインをインストールしてください。

uv tool install "hypermnesia-mcp[sqlite]"
codex plugin marketplace add cdeust/Cortex
codex plugin add hypermnesia-mcp-codex@cortex-codex-plugins

Codex で /hooks を開き、Cortex のフックを確認して信頼したうえで、新しいセッションを開始してください。フック定義を変更した場合、更新後に改めて信頼する必要があります。このプラグインは Claude Code と同じ保存済みのバックエンド選択を使用します。両方のホストが同じ設定ルートとストアを使用している場合、メモリを共有します。 Codex の設定の詳細。

その他の stdio MCP ホスト（Gemini CLI、Cursor、Windsurf、VS Code）も同じサーバーを起動し、同じツールを利用できます。起動コマンドをご覧ください。WSL、TLS クライアント証明書、企業プロキシについては、デプロイシナリオで説明しています。

Cortex の依存関係は、プラグインのデータディレクトリ内に、ロックされた依存関係セットごと（sets/<key>）に保存されます。そのため、ロックされた依存関係に変更のない更新（ほとんどのリリース：v4.9.0 から v4.23.5 までの 29 件中 21 件）では、そのセットがインストール済みの状態で見つかります。バックグラウンドジョブが、インストール済みバージョンから参照されていないセットを削除します。ネットワーク接続は行いません。セットが見つからない場合（インストール後の最初のセッション、またはロックされた依存関係が変わる更新後で、claude --init-only を先に実行していない場合）、フックはインストールされません。SessionStart には Cortex is installing its dependencies (about 2 minutes, about 5 with semantic search); memory is available when it is done と表示され、Edit/Write ガードは編集を許可し、その間は Cortex ゲートが無効であることを伝えます。また、MCP サーバーがバックグラウンドでセットをインストールします。次のセッション（または完了後の同じセッション）には、Cortex ready: <store>, <n> memories; <how recall ranks> と表示されます。claude --init-only（または進捗を表示する python3 scripts/init_plugin.py）を実行すると、最初のセッションより前にすべてをインストールできます。この場合に限り、そのセッションは準備完了の状態で開始します。Cortex を使わずに作業する場合は、オンラインでもオフラインでも、claude plugin disable hypermnesia-mcp@cortex-plugins を実行してください。

macOS と Linux（glibc）では、新規インストール時に claude --init-only を実行すると、pgvector と pg_trgm を備えた専用の PostgreSQL サーバーもプラグインに用意されます。ピン留めされ、sha256 で検証されたバイナリ（約 13 MB。pgvector は Cortex の CI でコンパイルされ、ビルドの来歴が証明済み）を 127.0.0.1 で実行するため、Homebrew やシステムの PostgreSQL は不要です。データは ~/.claude/methodology/managed-pg/ に保存されるため、プラグインをアンインストールしてもメモリは削除されません。これは、起動してスキーマが作成された後にのみストアになります。起動できない場合（たとえば、libxml2.so.2 または OpenSSL 3 がない Linux ディストリビューションの場合）は、Windows と同様に SQLite ストアが使用され、セッション開始時に理由が表示されます（SQLite fallback: ...）。同じアカウントの Codex プラグインは、このサーバーに接続します。既存の SQLite ストアは移動されません（ADR-1114）。

それ以外の場合、初回使用時に ~/.claude/methodology/ の下にローカルの SQLite ストアが作成されます。モデルは必要になったときに一度だけダウンロードされ、その後はオフラインで実行されます。埋め込みモデルと再ランキングモデルのファイルは、どちらも初回使用時に取得されます。オプションのインテグレーション、リモート PostgreSQL、OTLP テレメトリーがネットワークを使用するのは、明示的に設定された場合のみです。正確な範囲はPRIVACY.mdをご覧ください。

既存の PostgreSQL 設定は維持されます。設定済みの database_url オプション（または DATABASE_URL）、あるいは install-plugin.sh --postgres が書き込むバックエンドマーカーがあれば、プラグイン独自のサーバーや SQLite のデフォルト設定より常に優先されます。設定なしでローカルの cortex データベースを使用していたインストールも、そのまま維持されます。初回起動時に、localhost:5432 で何もリッスンしておらず、かつ PostgreSQL を設定する PG* 変数もない場合に限り、Cortex は SQLite に切り替え、その選択を記録して表示します。新規インストールでは、設定されていないデータベースに接続することはありません。

claude plugin uninstall cortex
claude plugin install hypermnesia-mcp

claude plugin uninstall cortex-viz@cortex-plugins
claude plugin marketplace update cortex-plugins
claude plugin install hypermnesia-mcp-viz@cortex-plugins

許可リスト、フック、スキル、エージェントでは、組み合わせたツール名をどちらも移行する必要があります。 mcp__plugin_cortex-viz_cortex-viz__open_visualization は mcp__plugin_hypermnesia-mcp-viz_hypermnesia-mcp-viz__open_visualization に、 mcp__plugin_cortex-viz_cortex-viz__get_methodology_graph は mcp__plugin_hypermnesia-mcp-viz_hypermnesia-mcp-viz__get_methodology_graph に変更します。

コンテキストを役立つ状態に保つ

セッションをまたいで、エージェントは決定事項を記憶し、似た問題が再発したときに以前の修正を活用し、記憶を裏付ける情報源を示して、あなたが修正できるようにする必要があります。Cortex は、その状態を可視化しながら、コンテキストを利用可能な状態に保ちます。

Cortex はローカルの品質チェックを通じてこれを実現します。何が書かれているか、その参照先が解決できるか、決定が変わったときに何が起きるか、そして時間の経過とともに何が薄れていくかを確認します。

何が保存されるか

書き込み時には、すでに保存されている内容と照合するローカルの新規性チェック（実装では予測符号化ゲートと呼んでいます）が行われます。新しい内容は書き込まれ、ほぼ重複する内容は別に保存されるのではなく、内容を言い換えている既存の記憶に統合されます。

// Illustrative project decision:
remember({ content: "Keep session state in Redis so TTL expiry is handled consistently." })
// → { stored: true, action: "stored" }

意図的な書き込みは、目新しさがないという理由で拒否されることはありません。バックグラウンドでの自動記録は拒否されます。これにより、意図して残したい記憶が自動記録に埋もれるのを防ぎます。

検証可能かどうか

すべての記憶は、ネットワーク呼び出しなしで、書き込み時にローカルで評価されます。この評価は信頼度スコアではありません。主張に、このマシン上で解決できる参照が含まれているかどうかを示します。

// → provenance: { grade: "unverifiable",
//                 reason: "dead_refs: deps/numpy/_core/_multiarray_umath.cpython-313-darwin.so",
//                 hint: "1 of 9 checkable reference(s) could not be resolved" }

その記憶が参照していたファイルはすでに存在しなくなっていたため、検証済みとして黙って提示されるのではなく、unverifiable とラベル付けして保存されました。解決可能なパスを使って書き直すと、同じ記憶は verified と評価されます。記憶を呼び出すと、その種類が示されます。verified という評価が意味するのは参照先がローカルで解決できるということであり、主張が独立して真実だと証明されたということではありません。

間違いが判明したとき

訂正は上書きではなく、以前の記憶に取って代わります。新しい記憶には置き換える対象が記録され、古い記憶は呼び出し時の優先度が下がり、一連の経緯は追える状態で保たれます。

remember({ content: "...", supersedes_id: 4360411 })
// → { action: "superseded", memory_id: 4360412, superseded_id: 4360411 }

正しかったかどうか

記憶には起きたことが記録されます。予測には、結果が判明する前に予想していたことが記録されるため、Cortex は後から予測が間違っていたかどうかを確認できます。predict は、その時点の信頼度を保持した、反証可能な主張を書き込みます。resolve_prediction は、呼び出し元が提示する観測結果に照らして予測を判定し、判定結果、判断を下した情報源の種類、その情報源への参照を記録します。calibration は、判定済みの一連の予測を採点します。

predict({ claim: "The p90 of the SQLite job is under 6 minutes",
          prediction: "a 20-minute budget leaves headroom", test: "21 attempts of 2026-09-16",
          confidence: 0.8 })
// → { prediction_id: 12, status: "open" }
resolve_prediction({ prediction_id: 12, verdict: "confirmed",
                     observed: "p90 348 s over 18 successes",
                     source_kind: "ci", source_ref: "cdeust/Cortex actions, 2026-09-16" })
// → { prediction_id: 12, verdict: "confirmed", resolved: true }
calibration()
// → { scored: 9, brier: 0.11, uninformative_brier: 0.25, confirmed: 7, refuted: 2,
//     reliability: [{ band: [0.6, 0.8], resolved: 4, mean_confidence: 0.78,
//                     observed_frequency: 0.75 }, ...] }

brier は、信頼度と結果の差の二乗の平均です。常に 0.5 と予測した場合のスコアは 0.25 なので、これを上回るスコアは、信頼度が何も言わない場合よりも有用な情報を持たなかったことを意味します。Cortex が証拠を自ら取得することはありません。判定結果、観測内容、情報源への参照は呼び出し元から渡されるため、どのリポジトリでも、どのようなレビュー規約の下でも、同じ契約を維持できます。

何が薄れていくか

記憶には熱量があり、再生によって強化されない限り減衰します。また、エピソード記憶の痕跡は意味記憶へと統合されることがあります。特定のデバッグセッションは、そこで得た原則に要約される場合があります。コマンドは薄れても、教訓は残ることがあります。このライフサイクルは、ストアの拡大に伴って有用性を保つことを目指していますが、サイズが一定に保たれることや、意味的な圧縮が確実に行われることを保証するものではありません。

使用感

これは、意思決定、以前の修正、ソースの確認が再び役立つようになるワークフローの一例です。

月曜日。 Webhook ハンドラーのデバッグに1時間かけた末、競合状態が原因だと判明します。認証チェックと権限の照会の間に TTL が切れていました。修正方法に合意して実装し、セッションを終了します。

木曜日。 別のセッションで、ユーザーからログアウトが断続的に発生すると報告されます。新しい作業内容と関連すると、Cortex は以前の分析、Redis に関する決定、TTL についての教訓を提示します。

3週間後。 セッションの内容は、認証と TTL ベースのキャッシュに関するパターンへと統合されます。詳細の一部は薄れても、原則は引き続き役立ちます。

Claude Code と Codex では、これらはすべて自動です。11個のライフサイクルフックが、セッション開始時にコンテキストを注入し、プロンプトごとに想起し、作業中に記録し、圧縮前にチェックポイントを作成し、自律的に管理される Wiki を運用します。それ以外の stdio MCP ホストでは、同じ57個のツールを自分で呼び出します。オプションの ai-architect-mcp-codebase と ai-architect-mcp-spec の統合がある場合は60個です。

検索は機能するのか

公開済みのベンチマークに照らして測定した、検索のみの結果です。LLM による読み取りは介在しません。問われるのは、モデルが適切な回答を書けるかではなく、適切な記憶が見つかるかどうかです。

LongMemEval：約40セッション分の履歴に埋もれた、500件の人手で精選された質問です。

どちらも単一実行の結果です。n=500、クリーンなデータベース、統合は無効、検索のみです。

v4.14.1、2026-07-14：アーティファクト JSON； コード SHA。検証のアブレーションキャンペーンは、この実行を基準に構成されました。

v4.20.0、2026-09-09：アーティファクト JSONとその マニフェスト；コード SHA、 dirty=false。LongMemEval-S の項目だけを単独で実行（benchmarks/reproduce.sh --only longmemeval --no-ablation）し、分離された一時 PostgreSQL コンテナー内で、リランカーをロードし、統合を無効にした結果です。v4.14.1 と比較すると、Recall@10 は0.4ポイント、MRR は0.012低下しています。実行時のフロアチェックでは、Recall@10 は7月のフロア（0.982）から許容範囲の0.005以内と報告され、MRR はフロア（0.914）を0.0093下回っています。スクリプトの設計上、これはブロッキング扱いにはなりません。docs/agent-guidance.mdには、main がこれらのフロアを満たさなくなったことと、リリースゲートが origin/main に対する --no-regression であることが記録されています。同じツリーには、LoCoMo または BEAM の数値はまだありません。

ライブストアに対して実行することなく、分離された一時コンテナー内で実行する benchmarks/reproduce.sh を使って再現できます。

Recall@10 は、回答を含むセッションが検索結果の上位10セッションに含まれる質問の割合です。MRR（平均逆順位）は、そのセッションを上位で見つけるほど高く評価します。これらの数値が示すのは検索のみであり、LLM が正しい回答を書くかどうかは測定していません。

検索では、ベクトル類似度、全文検索、トライグラム照合、注目度、最近性を融合した後、クロスエンコーダーで再ランキングします。PostgreSQL は各シグナルを加重和で組み合わせます。SQLite は加重逆順位融合を使い、トライグラムのシグナルはありません。LoCoMo と BEAM の結果、アブレーション、フロアゲートはbenchmarks/にあります。

ストレージ

デフォルトでは SQLite を使用します。macOS または Linux に新規インストールする場合は、プラグイン独自の PostgreSQL サーバーも使用できます（「インストール」を参照）。 ご自身の PostgreSQL を使う場合も、設定項目は 1 つだけです。非常に大規模なストアや、チームで共有するデータベースに適しています。

bash <plugin-dir>/scripts/install-plugin.sh --postgres

3 つのフックによる拡張機能は PostgreSQL 専用で、SQLite では何もせずに動作します。セッションバナー、自動リコール、自動キャプチャ、チェックポイント、およびすべてのメモリツールは、どちらでも動作します。

Codex と Claude Code での Cortex

どちらのプラグインも、メモリツールの完全なプロファイルを公開し、同じ 11 個の Cortex フックモジュールを使用します。同じストアに接続すると、プロジェクトに関連付けられたメモリを共有できます。そのため、Claude で保存した決定を Codex で呼び出せます。また、その逆も可能です。

ネイティブ Codex プラグインをインストールし、そのフックを信頼すると、Cortex は次の機能を提供します。

• セッション開始時にプロジェクトのコンテキストを復元し、プロンプトを送信するたびに関連するメモリを呼び出します。
• 重要なツールの結果を自動的に記録し、有用な作業内容をセッション間で利用できるようにします。
• コンパクションのチェックポイントと永続的なセッション終了時の記録により、セッションの状態を保持します。
• プロジェクトと役割のコンテキストをサブエージェントに提供します。
• 決定、教訓、Wiki ページ、ADR、予測、キャリブレーション、トリガー、ルール、コードベースの取り込みに対応する、完全なメモリツールセットを提供します。
• 両方のプラグインが同じストアとプロジェクトの関連付けを使用する場合、Claude Code とメモリを共有します。エージェントを切り替えて、もう一方が保存した内容を取得できます。

Claude Code でも、同じ Cortex メモリツールとフックモジュールを使用します。どちらのプラグインも、自律型 Wiki サイクル、SQLite ストレージ、オプションの PostgreSQL に対応しています。

インストール済みのホストで検証済み： Claude がランダムなテストペイロードを書き込み、Codex がそれを取得しました。次に Codex が別のペイロードを書き込み、新しい Claude セッションがそれを取得しました。どちらも、プロンプトから期待されるペイロードを読み取っていません。どちらのホストも、別のプロジェクトからメモリを呼び出す際にテストレコードを除外し、ネイティブの起動フックを通じて Cortex のコンテキストを提供しました。検証内容とツールのトレースを読む。

フックの信頼は Codex のセットアップ手順の一部です。インストール後、またはフック定義を変更した後に /hooks を確認し、新しいセッションを開始してください。イベントのマッピング、タスクコンテキストの処理、セッション終了時の配信については、Codex 統合ガイドに記載されています。認知プロファイルも共有されます。現在のプロファイルビルダーは Claude Code のセッションログからプロファイルを生成するため、どちらのホストでプロファイルを取得する場合も、その過去の入力データが必要です。

その他すべてのMCPホスト

stdio サーバーを起動できるホストであれば、SQLiteをデフォルトとし、PostgreSQLも選択できる完全なメモリツールプロファイルを利用できます。codex mcp addを含むMCPへの直接登録では、rememberツールとrecallツールを明示的に利用できます。自動的なライフサイクル動作は、ネイティブのClaude CodeまたはCodexプラグインで利用できます。Claude Desktopバンドルではフックなしでツールを利用できます。ChatGPTのウェブ版ではリモートデプロイが必要ですが、このリポジトリではローカルのstdioサーバーを提供しています。

すべてのホストで起動コマンドに使用するのはPyPIパッケージです。[sqlite]エクストラを有効にすると、sqlite-vecによるベクトル検索が使えます。有効にしない場合もストアは動作しますが、ベクトル検索は無効になります。

uvx --from "hypermnesia-mcp[sqlite]" hypermnesia-mcp

Gemini CLIは拡張機能として提供されています（このリポジトリにgemini-extension.jsonがあります）。

gemini extensions install https://github.com/cdeust/Cortex

CodexとChatGPTデスクトップには、完全なツールセットと、Claude Codeプラグインがインストールするものと同じ11個のライフサイクルフックを備えたネイティブプラグインがあります。このプラグインはClaude Codeランチャーと同じ保存済みバックエンド選択（~/.claude/methodology/backend.json）を読み取るため、両方のホストが1つのストアに書き込みます（4.23.0以降）。ただし、CORTEX_MEMORY_STORE_BACKEND、CORTEX_BACKENDまたはデータベースURLが明示されている場合は、そちらが優先されます。プラグイン初回のuvxハンドシェイクでPython環境のダウンロードに起動時間を費やさず、ローカルのuvキャッシュを再利用できるよう、あらかじめパッケージをインストールしてください。

uv tool install "hypermnesia-mcp[sqlite]"
codex plugin marketplace add cdeust/Cortex
codex plugin add hypermnesia-mcp-codex@cortex-codex-plugins

直接の代替手段では、プラグインを使わずに実行ファイルを登録します。

codex mcp add cortex --env CORTEX_MEMORY_STORE_BACKEND=sqlite -- hypermnesia-mcp

Cortexが意図的に主張していないホスト境界、実測された起動時間の上限、公開ディレクトリの要件については、docs/codex-plugin.mdを参照してください。

グリーンソフトウェアエンジニアリング

Cortexでは、検索機能の改善と同じエビデンス基準に基づき、継続的な効率化プログラムを実施しています。**根拠のない効率性の主張はリリースしません。**無駄は宣伝すべき美徳ではなく、再現可能な不具合として扱います。

測定ハーネス — および、そこからは立証できないこと

benchmarks/energy/ は、Green Software Foundation SCI 仕様を実装しています。運用時の排出量 O = E × I、内包排出量の割り当て M = TE × TS × RS を、機能単位あたりで報告します。埋め込み処理では、機能単位はモデル入力トークン 1000 個であり、文字数から推定するのではなく、トークナイザー自身の attention_mask に基づいてカウントします。

このハーネスの内容を引用する前に、benchmarks/energy/README.md を読んでください。最初の段落が重要です。自動フィクスチャは算術処理と失敗時の経路を検証するものであり、デバイスのエネルギーを測定するものではなく、エネルギーの改善を立証するものでもありません。 さらに、設計上、次の点に注意してください。

• デフォルトの炭素係数はありません。 --carbon-intensity（gCO2eq/kWh）と --embodied（gCO2eq/s、すでに割り当て済みの排出率）は、オペレーターが必ず入力する値で、モデルをインポートする前に検証されます。ハーネスは値と単位を記録しますが、その出所を保証するものではありません。地域、観測期間、ライフサイクルアセスメント、予約に関する前提は、オペレーターが指定します。
• 境界を明示しています。 raw_system_energy_j は、センサーによる CPU+GPU+ANE の合算推定値です。コンセントからの消費電力量でも、デバイス全体の SCI スコアでもありません。メモリ、ストレージ、画面、電源装置の損失、モデルのウォームアップ、トークンのカウントはすべて対象外です。
• 成果物がなければ、実施したことにはなりません。 実行が成功すると、results.json、コミットとソースのハッシュを記録した MANIFEST.json、および実際に解析した正確な powermetrics.txt のスナップショットが保存されます。

実際のベンチマーク実行で測定したエネルギーの結果は、benchmarks/results/energy/ にコミットされています。各結果には、未加工の powermetrics.txt、フェーズのタイムライン、マニフェストが含まれます。コミットされた数値は、あるオペレーターのマシン、地域、稼働サイクルにおける測定値であり、ソフトウェア自体の特性ではありません。常にその制約とともに引用してください。クエリあたりの実行全体の数値は上限値です（取り込み、埋め込み、データベース処理を含みます）。モデル側で消費されたエネルギーは主張していません。また、炭素強度はオペレーターが入力する値であり、出典とともに引用してください。benchmarks/energy/README.md のベンチマークのフェーズを参照してください。

実際にリリースされた内容

効率化の取り組みは、通常どおりレビューを経た PR として反映されています。2 つの取り組みがマージされました。

フックはすべてのツールイベントで実行されるため、フック関連の変更は特に重要です。 ハンドラーとストアのスタックを遅延させることで、フックの起動時間は 約 0.05 秒に抑えられます。レジストリー全体のインポートでは 約 0.6 秒かかります（2026-07-28 に計測。「定数を創作しない」という規則に従い、この定数は呼び出し箇所である mcp_server/hooks/auto_recall.py に記載されています）。

需要の削減が主要な手段です

LLM を活用するワークフローにおける効率性の最大の要因は、このサーバー自体の CPU 使用量ではありません。適切なコンテキストが最初に見つからなかったために、モデルが処理しなければならないトークンの量です。つまり、検索品質はエネルギー効率にも関わります。そのため、上記のベンチマーク表とこのセクションは同じプログラムの一部です。 response_budget.py はペイロードを制限し、ID を保持することで切り詰め後も再開できるようにします。再ランカーはモデルを取得する代わりに第 1 段階のスコアにフォールバックし、CORTEX_RERANKER_OFFLINE=1 はダウンロードを完全に拒否します。

この段落は設計上の根拠であり、測定結果ではありません。Cortex は、エンドツーエンドのエージェントセッションにおけるトークン削減量や CO2 排出量を公表していません。測定していないためです。

検証

上記の v4.14.1 の数値は、メカニズムごとのアブレーションキャンペーンに基づいています。n は完全なサンプル数で、シードは 1 つです。また、コード SHA、ダーティフラグ、マニフェスト、行ごとの JSON を保持しています。一方、v4.20.0 の数値は、そうした裏付けのない単一の測定値です。

• LongMemEval-S、17 行、n=500 — docs/benchmarks/e1-v3-results.md。較正済みの平衡状態におけるメカニズムごとの差分と、カテゴリー特化分析。
• LoCoMo、14 行、n=1986 — docs/benchmarks/e1-v3-locomo-results.md（修正前）と docs/benchmarks/e1-v3-locomo-results-post-fix.md（可塑性に関する結果形式の修正後）。2 つのベースライン設計（NO_CONSOLIDATION / WITH_CONSOLIDATION）。

メカニズムごとの完全なエビデンスは熱力学論文（§6.3）に記載されています。BEAM 減衰の用量反応（§6.4）では、ダーティなストアの交絡が発見され、原因が追跡された後に、範囲を再設定した負の結果を記録しています。熱力学的メモリと均一重要度ストアの比較（PDF、34 ページ） · ステージを考慮したコンテキストの組み立て（PDF、39 ページ）。

内部の仕組み

上記の仕組みは、エンコーディング、統合、検索、忘却にまたがる36のシステムメカニズムとして実装されています。それぞれに公開論文の引用があり、システムのライブ指標として公開されています。 bibliographyが照合元です。エントリー数はReferencesバッジに表示される数であり、両者が一致しない場合はゲートによってビルドが失敗します。

クリーンアーキテクチャの同心円状のレイヤー構成です：server → handlers → core ← shared、および infrastructure → shared。Coreは純粋で、モックなしでテストできます。 docs/agent-guidance.mdが全体像です。 docs/mcp-tools.mdはツールのリファレンスです。

Claudeの記憶の行き先では、記憶を取得するフックから、それを呼び戻す想起までの流れと、ADRファイルの決定から、それを読み込むセッションまでの流れをたどり、すべての主張をv4.22.0リリースの該当箇所にリンクしています（フランス語版）。

インストール前に知っておきたい制限事項

• 自動取得とコンテキスト注入は、ネイティブのClaude Codeプラグインと Codexプラグインが提供します。直接MCP接続する場合は、明示的なメモリツールを使用します。
• SQLiteの統合処理はプロセス内で行われ、インデックス化されません。個人規模であれば問題ありませんが、非常に大規模になると遅くなります。
• 上記の検索スコアは検索のみを評価したものです。回答の品質については示していません。
• 出典の評価はローカルで行われ、構造のみを確認します。参照先が解決できることは確認しますが、主張が正しいかどうかは確認しません。DOIやarXivのリンクが自動検証されることもありません。
• 上記の理由により、エネルギー消費量や炭素排出量の数値は公表していません。
• 初回使用時に、埋め込みモデルと再ランキングモデルの両方のファイルがダウンロードされます。オプションの連携機能、リモートPostgreSQL、OTLPテレメトリーによってネットワーク通信が発生するのは、明示的に設定した場合のみです。詳しくはPRIVACY.mdをご覧ください。

セキュリティ

100％ローカルで動作します。MCPはstdio経由で通信し、ストレージバックエンド（SQLiteファイルまたはlocalhost上のPostgreSQL）がマシンの外に出ることはありません（オプションのhypermnesia-mcp-viz連携ツールは、サーバーを127.0.0.1にバインドします）。データがマシンの外に出ることはありません。SafeSkillスキャン：94/100（コード97、コンテンツ88 — docs/safeskill-report.json）。

プライバシーポリシー

Cortexはローカルファーストです。記憶、会話、プロファイルはマシン上に保持されます。デフォルトではローカルのSQLiteデータベース（~/.claude/methodology/memory.db）に保存され、ユーザーが管理するPostgreSQLデータベースも使用できます。Cortexが記憶、コンテンツ、テレメトリーを作者、Anthropic、その他の第三者に送信することはありません。外向きのネットワーク通信は、Hugging Faceからオープンソースの埋め込みモデル／再ランキングモデルを一度だけダウンロードすること（モデルファイルのみ）と、明示的に設定した連携機能に限られます。ポリシー全文：PRIVACY.md。

サポート

• 問題とバグ報告： GitHub Issues
• セキュリティ上の問題の報告： SECURITY.mdをご覧ください
• 連絡先： [email protected]

開発

pytest                                # full suite; assets/badge-tests.svg carries the current count
ruff check . && ruff format --check . # lint and format, both enforced in CI
python scripts/check_doc_claims.py    # advertised counts must match the repo
python scripts/check_craftsmanship.py # file and method caps, layer whitelist, sourced constants

CONTRIBUTING.mdでは、変更が通過すべきゲートについて説明しています。 GOVERNANCE.mdでは、誰が決定するのか、メンテナーが活動を停止した場合にどうなるのかを説明しています。 docs/ROADMAP.mdではプロジェクトの今後の方向性を示し、 docs/ASSURANCE-CASE.mdではセキュリティ上の論拠とその限界を述べています。 CHANGELOG.mdには完全なリリース履歴が記載されています。

ライセンス

MIT — LICENSE をご覧ください。

このソフトウェアは、Clément Deust による独立した成果です。雇用関係の外で開発されており、過去または現在のいかなる雇用主とも提携関係になく、承認も所有もされていません。ai-architect エコシステムの一部です （zetetic-team-subagents、 ai-architect-mcp-codebase、 ai-architect-mcp-spec）。

このソフトウェアに実装された神経科学および情報検索のアルゴリズムは、 docs/papers/bibliography.md に引用された公開済みの学術研究、およびソース内の # source: アノテーション（Friston の予測符号化、Anderson & Lebiere のレート歪み忘却、Nader et al. の検索誘発性不安定性、McClelland et al. の固定化など）に基づいています。MIT ライセンスが適用されるのはこの実装であり、その基盤となるメカニズムの所有権を主張するものではありません。それらの権利は、引き続き原著者および出版物に帰属します。

引用

main ブランチ上の論文 PDF が正式な資料です（arXiv ID は後日公開予定、推薦手続き中）：

@software{cortex2026,
  title={Cortex: Persistent Memory for Claude Code},
  author={Deust, Clement},
  year={2026},
  url={https://github.com/cdeust/Cortex}
}

@unpublished{deust2026thermodynamic,
  title={Thermodynamic Memory vs. Flat-Importance Stores:
         Why Long-Term Retrieval Collapses Without Decay},
  author={Deust, Clement},
  year={2026},
  note={arXiv ID forthcoming, endorsement in progress},
  url={https://github.com/cdeust/Cortex/blob/main/docs/arxiv-thermodynamic/main.pdf}
}

@unpublished{deust2026context,
  title={Stage-Aware Context Assembly for Long-Context Memory Retrieval},
  author={Deust, Clement},
  year={2026},
  note={arXiv ID forthcoming, endorsement in progress},
  url={https://github.com/cdeust/Cortex/blob/main/docs/arxiv-context-assembly/main.pdf}
}