hypermnesia-mcp-viz

Hypermnesia MCP Viz

Hypermnesia MCP Viz 在所有平台上的发布名称均为 hypermnesia-mcp-viz： Python、MCP Registry、Claude Code、Codex、Gemini 和控制台命令。

适用于 Cortex 的跨平台可视化层。 Codex、Gemini CLI、Claude Code 和任何 stdio MCP 主机都可以启动同一个只读服务和浏览器 UI。它将 Cortex 的记忆存储、与主机无关的实时活动流、Claude Code 的历史会话存档以及代码库图谱，转化为六种实时浏览视角：项目星系、3D 解剖大脑、执行追踪、整合看板、精选知识浏览器和 Wiki。它绝不会写入记忆：只负责呈现，从不记忆。（它会在 Cortex 数据库中保留自己的派生图谱／布局缓存，详见边界。）

使用 open_visualization 工具（或 /cortex-visualize）启动。一个启动器即可打开六种浏览视角；默认首页视图为 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 安装不会自动成为新插件身份的别名。 协调发布后，请移除旧安装、刷新市场，然后安装规范插件：

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

Claude 会根据插件清单名称、mcpServers 键和工具名称组合生成插件工具名称。请在权限允许列表、钩子、技能或 Agent 中出现旧的完整名称时，将这两个名称都更新：

• 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）：可视化工具会读取 Cortex 共享的 PostgreSQL 存储，只会在其中写入自己的派生缓存（边界）。请将两者指向同一个数据库：插件设置 database_url 默认为 postgresql://127.0.0.1:5432/cortex；请将其设为与 Cortex 相同的值。

重启 Claude Code 会话，然后启动可视化工具：

/cortex-visualize

Codex、Gemini CLI 和其他 MCP 主机以普通的 stdio 进程启动同一服务；确切配置请参阅其他 MCP 主机。

一个启动器即可在浏览器中打开全部六种查看视角（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 数据库时，服务会记录一行日志，并自动以无数据库模式启动：Trace 完全可用；五个由数据库支持的视图（Graph、Brain、Knowledge、Wiki、Board）会显示为灰色，并提供安装提示，而不会报错。
• 若要完全跳过数据库探测，请设置 CORTEX_VIZ_NO_DB=1（或者直接运行独立服务时传入 --no-db）。

之后安装 Cortex，即可在同一界面中启用其他五种视图（无需重新配置）。

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

各视图

Graph：Claude 工作流地图

每个项目都会围绕一个金色的领域枢纽，形成一片节点云。每片云中的节点按生成它们的 Claude 界面（或代码本身）分布在六个同心层级中：

L6 为何重要。 L5 及以下告诉你 Claude 做了什么；L6 则告诉你 代码是什么。有三件事会自然显现：共享代码（任何被两个项目引用的符号都会延伸到项目间的空隙中）、影响范围（点击符号即可查看所有调用者、导入者和成员；“如果我改动它，什么会出问题？”会成为图中的邻域，而不是一次 grep），以及代码库本身的形态（文件周围密集的花瓣意味着内部 API 臃肿；稀疏则意味着它是一个叶子模块）。分组筛选器（L1–L6 / 按类型 / 按 AST 边类型 / Cross-domain）可隔离任意切片。

大脑：真实皮层中的星系

同一张图谱，呈现在第二个表面上：依据记忆系统神经科学，而非力的方向，将每个节点放置在解剖学的皮层网格中。情景记忆位于内侧颞叶，并沿着由活跃到已巩固的深度梯度向外迁移至新皮层（互补学习系统巩固模型）；语义实体位于颞叶新皮层；代码符号位于联合皮层；程序性技能位于纹状体和小脑；领域位于连接组的富俱乐部枢纽。区域中心根据真实的 MNI152 图谱坐标配准（仿射拟合，并非精确到顶点；网格是单一的无标签表面）。每个突触都沿着主要的白质束（穹隆、钩束、上纵束、胼胝体）传递。节点颜色与星系视图使用相同的语义调色板（记忆按巩固阶段着色，实体／符号按类型着色），实时的 Memory science 面板则映射存储区的系统状态指标（巩固流水线、技能、来源监控、消退、睡眠阶段，以及 Cortex 提供的所有机制）。

由于完整图谱（超过 278k 个节点、550 万条边）远超浏览器单次可接收的数据量，大脑视图通过有界队列、按帧预算的 NDJSON 加载器分批流式传输：云团会在你观看时逐渐显现。点击任意节点，即可打开与星系视图相同的丰富详情卡片（内容、标签、实时热度、关系、git 差异、影响）。可通过视图栏中的 Brain 按钮打开，也可直接访问 /brain，或通过 open_visualization(view="brain") 以编程方式打开。

按巩固阶段划分为五列（labile · early_ltp · late_ltp · consolidated · reconsolidating）。每个列标题上方显示该阶段的实时数量（以服务端数据为准，而非已加载页面的数据），下方显示该阶段的参考物理参数（衰减 ×、脆弱性 %、可塑性 %）以及阶段推进规则（例如，labile 阶段为 replays ≥ 1 or imp > 0.3，early_ltp 阶段为 replays ≥ 3）。这些物理参数和推进规则是 DD-02 阶段规范中的常量，并非实时重新计算的每个记忆桶中位数。卡片显示实时活跃度、重要性、意外度、效价、唤醒度，以及创建该记忆的确切工具。

详情面板：解释每项测量数据。 点击任意节点都会打开一个面板，其中显示原始值和一句通俗易懂的说明。巩固阶段、活跃度（热度）、重要性、意外度、情绪基调和强度、置信度、可塑性、稳定性：每项都以带标签的条形图显示，并附上一句说明，例如 “这条记忆出现时有多出乎意料。意外事件比日常事件更容易留存。”

• Trace （默认）：实时执行轨迹钻取：折叠的领域中心 → 会话 → 按顺序排列的提示词 → 操作 → 文件链，还原实际发生的情况 → 文件的 AST 符号、影响范围和 git 历史。讨论以及 Cortex remember/recall 操作也编织在这条链中。每次请求都会从会话 JSONL、代码图谱和 git 中实时提供（无快照，始终保持最新）。
• Knowledge：精选记忆卡片，包含情感（词语 + 带符号的效价/唤醒度，绝不只用颜色表示）、MEANING 行和逐字摘录、阶段/领域/HOT 徽标，以及按固定顺序排列的四个测量刻度（热度 · 重要性 · 效价 · 唤醒度；为零时显示空轨道，绝不隐藏）；可按领域、阶段或情感筛选，并显示精确的分类计数。
• Wiki：每个项目的知识库，以可浏览的 Project → Kind → Pages 树展示，并配有档案式页面阅读器：衬线字体正文、带编号的章节标题和等宽字体标识符标签、方框状态和类型徽标、带日期的来源信息，以及 Edit · PDF · TEX · DOCX · HTML 导出栏。点击 Edit 可进入带实时预览的 CodeMirror 分栏编辑器。（Wiki 内容由 Cortex 自主编写；Hypermnesia MCP Viz 提供阅读和编辑界面。）Cortex 发布到仓库自身 wiki/（其 project_root 模式，由 wiki/manifest.json 识别）中的页面，会列在该项目下，并带有 @<project>/ 路径前缀；这些页面在此处为只读，因为 Cortex 会为每个页面发布对应的 manifest 和 docs/adr 镜像。

安装

Hypermnesia MCP Viz 是跨平台 MCP 服务，并提供 Claude Code 插件。将其指向与 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 分发包。请使用安装它的同一 Python 解释器／环境进行升级，安装程序会在安装 3.1.0 时移除旧的、由分发包提供的垫片（移除垫片的分发包身份重命名被合并到代码库的 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

使用同一个解释器卸载报告的分发包；如果没有分发包拥有它，则通过创建该垫片的工具移除手动安装的 shell／文件垫片。不要根据可执行文件猜测分发包名称。

将 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 适配器可以将下方的版本化架构 POST 到本地 /api/activity 端点。星系／大脑／知识／维基／看板视图仍需要读取 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 活动相同的会话／操作／目标图。除了提示词、工具、文件、终端命令、技能、子 Agent 和网页访问外，生产方还可以明确报告 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：传入 view="brain" 可查看 3D 解剖脑图，传入 view="galaxy" 或省略则显示 2D 图）和 get_methodology_graph（图数据）。六种视图由 open_visualization 启动的服务通过 HTTP 提供；实时会话活动流（每次工具调用、MCP 调用、文件访问、技能和命令）通过活动捕获钩子实时馈入图中。

项目

成就

• OpenSSF 最佳实践银级认证：项目 13846 于 2026-08-03 获得银级认证。每项已通过及银级标准的答案均已提交至 .bestpractices.json，并根据此仓库进行审计，而非照搬。
• OpenSSF Scorecard：每周运行一次（scorecard.yml）。当前得分为 7.4（2026-08-03），并获得银级徽章，且没有已知漏洞。
• 构建来源证明：所有四个 v2.8.0 产物——wheel、源代码归档、CycloneDX SBOM 和 UI 清单——均具有经过独立验证的 Sigstore 支持证明。使用 gh attestation verify <file> --repo cdeust/cortex-viz 验证任何已下载的产物。

状态

可视化技术栈已从 Cortex（现为专注于记忆的引擎）中提取出来，因此图形功能可独立发布并扩展。独立 MCP 通过 stdio 启动；六种视图均已接入实时数据；星系图可端到端构建，支持 75k+ 个节点；3D 脑图可将完整图数据流式传输至皮层网格；整个 UI 均采用 AI Architect 设计系统（纸张/墨水表面、由令牌解析的调色板）；测试套件全部通过。