hypermnesia-mcp-viz

Hypermnesia MCP Viz

Hypermnesia MCP Viz は、Python、MCP Registry、Claude Code、Codex、Gemini、コンソールコマンドのすべてで、hypermnesia-mcp-viz として公開されています。

Cortex 向けのクロスプラットフォーム・ビジュアライゼーションレイヤーです。 Codex、Gemini CLI、Claude Code、および任意の stdio MCP ホストから、同じ読み取り専用サーバーとブラウザー UI を起動できます。Cortex のメモリストア、ホストに依存しないリアルタイムのアクティビティストリーム、Claude Code の過去のセッションアーカイブ、コードベースのグラフを、プロジェクトの銀河、3D の解剖学的な脳、実行トレース、統合カンバン、厳選されたナレッジブラウザー、Wiki という6つのリアルタイムな視点で表示します。メモリを書き込むことはありません。表示するだけで、記憶することはありません。（ただし、Cortex のデータベースには、独自の派生グラフ／レイアウトキャッシュを保持します。詳細は境界を参照してください。）

open_visualization ツール（または /cortex-visualize）で起動します。1つのランチャーで6つの視点が開き、デフォルトのランディングビューは Trace です。

UI 全体で AI Architect デザインシステムを採用しています。紙面を基調とした読み取り画面に、常時表示される インク（ナイト）切り替え、グレースケールのクローム、実行時にデザイントークンから解決されるデータパレットを備えています。画面を切り替えると、確定済みのレイアウトを崩すことなく、すべてのビューがその場で再着色されます。画面上のすべての数値は正確な値でストリーミング表示され、丸められることはありません。

はじめに

Claude Code ユーザーは、Cortex と同じ cortex-plugins マーケットプレイスから Hypermnesia MCP Viz をインストールできます。

claude plugin marketplace add cdeust/Cortex
claude plugin install hypermnesia-mcp-viz@cortex-plugins

このインストール名は、このリポジトリと、対応するマーケットプレイスの変更である cdeust/Cortex#351が同時にリリースされた場合に限り、Cortex マーケットプレイスで利用可能になります。メンテナーは、名称変更のどちらか一方だけを公開してはいけません。

cortex-viz からの移行

既存の Claude Code インストールは、新しいプラグイン ID のエイリアスではありません。 古いインストールを削除し、連携リリース後にマーケットプレイスを更新してから、 正式なプラグインをインストールしてください。

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

Claude は、プラグインマニフェスト名、mcpServers キー、ツール名を組み合わせてプラグインツール名を作成します。権限の許可リスト、フック、スキル、エージェントに旧形式の完全名が含まれている場合は、すべて更新してください。

• 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-viz コンソールコマンドはエイリアスとして残されないため、 Cursor、Windsurf、VS Code、その他の直接プロセス構成では、 代わりに hypermnesia-mcp-viz を呼び出す必要があります。

Hypermnesia MCP Viz は、メモリに書き込むことのない Cortex のコンパニオンです。 まず Cortex をインストールしてください（claude plugin install hypermnesia-mcp@cortex-plugins）。ビジュアライザーは共有 PostgreSQL ストアを読み取り、そこには独自の派生キャッシュのみを書き込みます（境界）。両方を同じデータベースに接続してください。プラグイン設定 database_url のデフォルト値は postgresql://127.0.0.1:5432/cortex です。Cortex に設定した値と同じものを指定してください。

Claude Code のセッションを再起動してから、ビジュアライザーを起動してください。

/cortex-visualize

Codex、Gemini CLI、その他の MCP ホストでは、同じサーバーを通常の stdio プロセスとして起動します。正確な構成については、その他の MCP ホストを参照してください。

1 つのランチャーで、6 つすべての閲覧ビュー（Graph・Brain・Trace・Knowledge・Wiki・Board）をブラウザーで開きます。Cortex ストア、セッション JSONL、コードグラフ、git からリアルタイムに配信されます。

Cortex がなくても使えます

Cortex も PostgreSQL もセットアップも不要です。Hypermnesia MCP Viz は単体でも役立ちます。デフォルトのランディングビューである Trace ビューは、~/.claude/projects/*.jsonl とローカルの git のみを読み取ります。Claude Code のすべてのセッションが、ドメイン → セッション → プロンプト → アクション → ファイルの、たどることのできる一連の流れとして表示され、ファイルごとの差分とコミット履歴も確認できます。Claude Code を使っていれば、必要なデータはすでにディスク上にあります。

• プラグインをインストールして、/cortex-visualize を実行するだけです。Cortex のデータベースに接続できない場合、サーバーはログに 1 行出力して、自動的に DB なしモード で起動します。Trace は完全にリアルタイムで表示されます。DB を必要とする残り 5 つのビュー（Graph、Brain、Knowledge、Wiki、Board）は、エラーになる代わりに、インストール方法を示す案内とともにグレーアウトして表示されます。
• データベースの接続確認を完全にスキップするには、CORTEX_VIZ_NO_DB=1 を設定するか、スタンドアロンサーバーの直接実行時に --no-db を渡してください。

後から Cortex をインストールすると、再構成なしで同じ UI から残り 5 つのビューも利用できるようになります。

git clone https://github.com/cdeust/cortex-viz.git && cd cortex-viz
pip install -e .
DATABASE_URL=postgresql://127.0.0.1:5432/cortex python3 -m cortex_viz
# Without Cortex/Postgres (Trace view only):
CORTEX_VIZ_NO_DB=1 python3 -m cortex_viz

ビュー

グラフ：Claude のワークフローマップ

各プロジェクトは、1 つのゴールドのドメインハブを中心としたノードの雲になります。それぞれの雲の中では、ノードは、それを生み出した Claude のサーフェス（またはコード自体）に応じて、6 つの同心レベルに配置されます。

L6 が重要な理由。 L5 以下ではClaude が何をしたかがわかりますが、L6 ではコードが何であるかがわかります。3 つのことがすぐに見えるようになります。共有コード（2 つのプロジェクトから参照されているシンボルは、プロジェクト間の隙間に現れます）、影響範囲（シンボルをクリックすると、すべての呼び出し元、インポーター、メンバーが表示されます。「これを変更したら何が壊れるか？」は grep ではなく、グラフの近傍です）、そしてコードベース自体の形状（ファイルの周りに密な花弁があれば内部 API が大きく、薄ければリーフモジュールです）。グループ化フィルター（L1–L6 / 種類別 / AST エッジの種類別 / Cross-domain）を使うと、任意の部分を切り分けられます。

Brain：実際の皮質の中に広がる銀河

同じグラフを、今度は別の表面に表示します。力の向きではなく、記憶システムの神経科学に基づいて、各ノードを解剖学的な皮質メッシュの内側に配置します。エピソード記憶は内側側頭葉に位置し、熱い状態から定着した状態へと向かう深度勾配に沿って新皮質へ移動します（相補的学習システムの固定化モデル）。意味エンティティは側頭新皮質に、コードシンボルは連合皮質に、手続きスキルは線条体と小脳に、ドメインはコネクトームのリッチクラブハブに配置されます。領域の中心座標は、実際のMNI152 アトラス座標から登録されています（アフィンフィットであり、頂点単位での正確な位置合わせではありません。メッシュはラベルのない単一のサーフェスです）。すべてのシナプスは、主要な白質路（脳弓、鉤状束、SLF、脳梁）に沿って経路をたどります。ノードの色は銀河と同じセマンティックパレットを使用し（記憶は固定化段階別、エンティティ／シンボルは種類別）、ライブのMemory scienceパネルには、ストアのシステム状態（固定化パイプライン、スキル、ソースモニタリング、消去、睡眠段階、Cortex が公開するすべてのメカニズム）が反映されます。

グラフ全体（ノード 278k 以上、エッジ 5.5M）は、ブラウザーが一度に受け取れるペイロードよりもはるかに大きいため、脳の表示では、キューの上限とフレーム予算を設けた NDJSON ローダーを使って段階的にストリーミングします。見ている間にクラウドが埋まっていきます。任意のノードをクリックすると、銀河と同じ詳細カード（内容、タグ、ライブの熱度、関連項目、git diff、影響度）が開きます。ビューのバーにあるBrainボタンから開くほか、/brain に直接アクセスするか、open_visualization(view="brain") をプログラムから呼び出して開けます。

統合段階ごとに5つの列があります（labile · early_ltp · late_ltp · consolidated · reconsolidating）。各ヘッダーには、段階ごとの現在の件数（読み込まれたページの数ではなく、サーバー側の正確な件数）が、その段階の基準となる物理特性（減衰 ×、脆弱性 %、可塑性 %）と、次の段階へ進む条件（例：labile では replays ≥ 1 or imp > 0.3、early_ltp では replays ≥ 3）とともに表示されます。物理特性の行と進行条件は DD-02 の段階仕様で定められた定数であり、バケットごとの中央値をリアルタイムに再計算したものではありません。カードには、現在の活性度、重要度、意外性、感情価、覚醒度と、その記憶を作成した正確なツールが表示されます。

詳細パネル：すべての測定値を解説します。 ノードをクリックすると、パネルが開き、生の値と、わかりやすい言葉での一行説明が表示されます。統合段階、活動度（活性度）、重要度、意外性、感情的なトーンと強度、確信度、可塑性、安定性が、それぞれラベル付きのバーと、「記憶が届いたとき、どれほど意外だったかを示します。意外な出来事は、日常的な出来事よりも記憶に残りやすいものです。」といった説明文とともに表示されます。

• トレース (デフォルト)：ライブ実行トレースを詳しく確認できます。折りたたまれたドメインハブ → セッション → 実際に起きたことを示す、プロンプト → アクション → ファイルの順序付きチェーン → ファイルの AST シンボル、影響範囲、Git 履歴をたどれます。ディスカッションと Cortex の remember／recall 操作もチェーンに織り込まれています。各リクエスト時にセッション JSONL、コードグラフ、Git からライブで提供されるため、スナップショットはなく、常に最新の状態です。
• ナレッジ：厳選されたメモリーカードを表示します。感情（単語と符号付きの快感度／覚醒度。色だけで表すことはありません）、MEANING の行と原文の抜粋、ステージ／ドメイン／HOT バッジ、固定順の4つの測定メーター（熱量 · 重要度 · 快感度 · 覚醒度）が表示されます。ゼロの場合は空のトラックが表示され、隠れることはありません。ドメイン、ステージ、感情で絞り込み、各ファセットの正確な件数を確認できます。
• Wiki：プロジェクトごとのナレッジベースを、プロジェクト → 種類 → ページのツリーで閲覧できます。書類ファイル風のページリーダーには、番号付きのセクション見出しと等幅フォントの識別子チップを使ったセリフ体の文章、枠付きのステータスと種類のバッジ、日付付きの来歴、Edit · PDF · TEX · DOCX · HTML のエクスポートバーが表示されます。Edit の背後には、ライブプレビュー付きの CodeMirror 分割ペインエディターがあります。（Wiki のコンテンツは Cortex が自律的に作成します。Hypermnesia MCP Viz は閲覧と編集のための画面です。）Cortex がリポジトリ内の wiki/ に公開したページ（project_root モードで、wiki/manifest.json により認識）は、そのプロジェクトの配下に @<project>/ のパス接頭辞付きで表示されます。Cortex は各ページをマニフェストおよび docs/adr ミラーとともに公開するため、ここでは読み取り専用です。

インストール

Hypermnesia MCP Viz は、Claude Code プラグインを備えたクロスプラットフォーム対応の MCP サーバーです。Cortex のインストール環境と同じデータベースを指定してください。そのストアから Cortex の記憶を読み込みますが、書き込みは一切行いません。

プラグインとして使用する場合：MCP サーバー、/cortex-visualize スキル、ライブのセッションアクティビティフックが含まれています。同梱の scripts/launcher.py は初回起動時に依存関係を自動でセットアップします（手動での pip は不要です）。プラグインのユーザー設定にある database_url でデータベースを設定します（デフォルトは postgresql://127.0.0.1:5432/cortex です）。

通常の MCP として使用する場合（v3.1.0 以降）：

pip install "hypermnesia-mcp-viz[data,viz-tile]"   # optional PG and large-graph extras
hypermnesia-mcp-viz                 # or: python -m cortex_viz (stdio MCP transport)

公開された 2.8.0 の hypermnesia-mcp-viz ディストリビューションには、従来の cortex-viz コンソール用シムが含まれていました。この名前の独立した Python ディストリビューションは存在しませんでした。これをインストールしたときと同じインタープリター／環境を使ってアップグレードしてください。インストーラーは 3.1.0 のインストール時に、古いディストリビューション所有のシムを削除します（シムを削除するディストリビューションの ID 変更は 3.0.0 としてツリーに取り込まれましたが、このバージョンはタグ付けも公開もされていません。CHANGELOG の [3.0.0] エントリーを参照してください。そのため、これを含む最初の公開リリースは 3.1.0 です）。

python3 -m pip install --upgrade "hypermnesia-mcp-viz>=3.1.0"

cortex-viz がまだ解決される場合は、まずすべてのシムを探し、そのコンソールエントリーポイントを所有するインストール済みディストリビューションを Python に確認してください。

type -a cortex-viz
python3 - <<'PY'
from importlib import metadata

owners = []
for distribution in metadata.distributions():
    if any(
        entry.group == "console_scripts" and entry.name == "cortex-viz"
        for entry in distribution.entry_points
    ):
        owners.append((distribution.metadata["Name"], distribution.version))
print(owners or "no Python distribution owns cortex-viz in this interpreter")
PY

報告されたディストリビューションを同じインタープリターでアンインストールしてください。どのディストリビューションも所有していない場合は、手動でインストールしたシェル／ファイルのシムを、作成したツールで削除してください。実行ファイルからディストリビューション名を推測しないでください。

DATABASE_URL に、共有 Cortex データベースを設定してください。open_visualization はブラウザーで銀河 UI を起動し、127.0.0.1 にバインドします。

その他の MCP ホスト

任意の MCP ホストからサーバーを起動できます。これは通常の stdio プロセスです。pip install hypermnesia-mcp-viz でインストールし、ホストの MCP 設定で hypermnesia-mcp-viz をサーバー名とコマンドの両方に登録してください（Gemini CLI の ~/.gemini/settings.json、Cursor の .cursor/mcp.json、Windsurf の ~/.codeium/windsurf/mcp_config.json、VS Code の "servers" 以下の .vscode/mcp.json、または Codex CLI の codex mcp add hypermnesia-mcp-viz -- hypermnesia-mcp-viz）。同等の Python モジュール形式は python3 -m cortex_viz です。open_visualization ツールはブラウザーで UI を開きます。過去の Trace アーカイブは引き続き ~/.claude/projects/ 以下の Claude Code JSONL を読み込みますが、ライブアクティビティはホストに依存しません。Codex、Gemini、または汎用 MCP アダプターは、バージョン管理された以下のスキーマをローカルの /api/activity エンドポイントに POST できます。銀河／脳／ナレッジ／Wiki／ボードの各ビューで読み込むには、引き続き Cortex ストアが必要です。

ホストに依存しないライブアクティビティ

POST /api/activity は、既存の Claude フックペイロードに加え、 docs/host-event-v1.schema.json に定義された JSON Schema 契約を受け付けます。イベントの送信元はホストを明示します。 ツール名は送信元情報として扱われ、Claude のツールとして再解釈されません。

{
  "schema_version": "1",
  "host": "codex",
  "session_id": "01J...",
  "timestamp": "2026-08-02T12:34:56Z",
  "event": "tool_call",
  "tool": "read_file",
  "input_summary": "Read the authentication module",
  "artifact": "src/auth.ts",
  "result": "success",
  "cwd": "/workspace/project"
}

このエンドポイントは、イベントを Claude アクティビティと同じセッション／アクション／対象のグラフに正規化します。 送信元は、プロンプト、ツール、ファイル、ターミナルコマンド、スキル、サブエージェント、ウェブアクセスに加えて、mcp_call、api_call、db_read、db_write を明示的に報告できます。API／データベースの対象は送信元の artifact から取得されます。入力／結果の要約は観測されたとおりに表示され、ツール名から推測されることはありません。ホスト固有のフックやテレメトリーアダプターは、グラフやデータベーススキーマを変更せずに個別に追加できます。

境界

Hypermnesia MCP Viz は、Cortex のディスク上のアーティファクトと PostgreSQLを利用し、Cortex の実行中の Python オブジェクトは利用しません。

cortex_viz/ 内では、どこであっても import mcp_server.* は許可されません。この不変条件が、抽出の正しさを確認するチェックです。

MCP ツール

open_visualization（ブラウザー UI を起動します。3D の解剖学的脳を表示するには view="brain" を渡し、2D グラフを表示するには view="galaxy" を渡すか、省略します）と、get_methodology_graph（グラフデータ）を利用できます。6 つのビューは、サーバーが open_visualization の起動時に提供する HTTP 経由で表示されます。ライブのセッションアクティビティストリーム（すべてのツール呼び出し、MCP 呼び出し、ファイルアクセス、スキル、コマンド）が、アクティビティキャプチャフックを介してグラフにリアルタイムで反映されます。

プロジェクト

実績

• OpenSSF Best Practices Silver：project 13846 は 2026-08-03 に Silver を獲得しました。合格および Silver の各基準への回答はすべて .bestpractices.json にコミットされ、コピーではなく、このリポジトリに照らして監査されています。
• OpenSSF Scorecard：毎週実行されます（scorecard.yml）。現在のスコアは 7.4（2026-08-03）で、Silver バッジを取得し、既知の脆弱性はゼロです。
• ビルドの来歴：v2.8.0 の 4 つのアーティファクト（wheel、ソースアーカイブ、CycloneDX SBOM、UI マニフェスト）すべてに、個別に検証済みの Sigstore ベースのアテステーションが付与されています。ダウンロードしたアーティファクトは、gh attestation verify <file> --repo cdeust/cortex-viz を実行して検証できます。

ステータス

可視化スタックは、グラフィックスを独立してリリースし、スケールできるよう、Cortex（現在はメモリエンジンに特化）から抽出されました。スタンドアロンの MCP は stdio 経由で起動し、6 つのビューすべてがライブデータに接続されています。galaxy はエンドツーエンドで 75k 以上のノードを構築し、3D の脳はグラフ全体を皮質メッシュにストリーミングします。UI 全体は AI Architect デザインシステム（ペーパー／インクのサーフェス、トークンで解決されるパレット）に準拠しており、テストスイートも合格しています。