Hypermnesia MCP Viz

Hypermnesia MCP Viz

Hypermnesia MCP Viz is published as `hypermnesia-mcp-viz` everywhere: Python, MCP Registry, Claude Code, Codex, Gemini, and the console command.

The cross-platform visualization layer for [Cortex](https://github.com/cdeust/Cortex). Codex, Gemini CLI, Claude Code, and any stdio MCP host can launch the same read-only server and browser UI. It turns Cortex's memory store, a host-neutral live activity stream, Claude Code's historical session archive, and your codebase graph into six live reading angles: a project galaxy, a 3D anatomical brain, an execution trace, a consolidation kanban, a curated knowledge browser, and a wiki. It never writes a memory: it renders, it never remembers. (It does keep its own derived graph/layout caches in the Cortex database, listed under Boundary.)

Launch with the open_visualization tool (or /cortex-visualize). One launcher opens six reading angles; the default landing view is Trace.

The whole UI ships on the AI Architect design system: a paper-first reading surface with a persistent ink (night) toggle, greyscale chrome, and a data palette resolved from design tokens at runtime, flipping the surface re-inks every view in place without disturbing a settled layout, and every count on screen is exact and streamed, never rounded.

---

Getting Started

Python 3.11 or newer is required. Upgrade Python 3.10 installations before updating: the fixed Pillow 13 release requires Python 3.11.

Claude Code users can install Hypermnesia MCP Viz from the same cortex-plugins marketplace as Cortex:

claude plugin marketplace add cdeust/Cortex

claude plugin install hypermnesia-mcp-viz@cortex-plugins

This install name becomes available in the Cortex marketplace only when this repository and the matching marketplace change in cdeust/Cortex#351 are released together. Maintainers must not publish either half of the rename on its own.

Migrating from cortex-viz

Existing Claude Code installs are not aliases for the new plugin identity. Remove the old install, refresh the marketplace after the coordinated release, and install the canonical plugin:

claude plugin uninstall cortex-viz@cortex-plugins

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

Claude composes plugin tool names from the plugin manifest name, the mcpServers key, and the tool name. Update both old full names wherever they appear in permission allowlists, hooks, skills, or agents:

• mcp__plugin_cortex-viz_cortex-viz__open_visualization becomes mcp__plugin_hypermnesia-mcp-viz_hypermnesia-mcp-viz__open_visualization.
• mcp__plugin_cortex-viz_cortex-viz__get_methodology_graph becomes mcp__plugin_hypermnesia-mcp-viz_hypermnesia-mcp-viz__get_methodology_graph.

The removed cortex-viz console command is not retained as an alias, so Cursor, Windsurf, VS Code, and other direct-process configurations must invoke hypermnesia-mcp-viz instead.

Hypermnesia MCP Viz is a companion to [Cortex](https://github.com/cdeust/Cortex) that never writes a memory. Install Cortex first (claude plugin install hypermnesia-mcp@cortex-plugins): the visualizer reads its shared PostgreSQL store, and writes only its own derived caches there (Boundary). Point both at the same database: the database_url plugin setting defaults to postgresql://127.0.0.1:5432/cortex; set it to the same value you gave Cortex.

Restart your Claude Code session, then launch the visualizer:

/cortex-visualize

Codex, Gemini CLI, and other MCP hosts launch the same server as a plain stdio process; see Other MCP hosts for the exact configuration.

One launcher opens all six reading angles (Graph · Brain · Trace · Knowledge · Wiki · Board) in the browser, served live from the Cortex store, your session JSONL, the code graph, and git.

Works without Cortex

No Cortex, no PostgreSQL, no setup: Hypermnesia MCP Viz is still useful on its own. The Trace view (the default landing view) reads only ~/.claude/projects/*.jsonl and your local git: every Claude Code session becomes a navigable domain → session → prompt → action → file chain, with per-file diffs and commit history. If you use Claude Code, the data is already on your disk.

• Just install the plugin and run /cortex-visualize. When Cortex's database isn't reachable, the server logs one line and starts in no-DB mode automatically: Trace is fully live; the five DB-backed views (Graph, Brain, Knowledge, Wiki, Board) appear greyed out with an install pointer instead of erroring.
• To skip the database probe entirely, set CORTEX_VIZ_NO_DB=1 (or pass --no-db when running the standalone server directly).

Installing Cortex later lights up the other five views against the same UI (no reconfiguration).

More options (Clone, manual run)

Clone + run from source:

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

---

The views

Graph: the Claude workflow map

Each project becomes a cloud of nodes around one gold domain hub. Inside every cloud, nodes sit in six concentric levels by the Claude surface (or the code itself) that produced them:

Why L6 matters. L5 and below tell you *what Claude did*; L6 tells you *what the code is*. Three things become visible for free: shared code (any symbol referenced by two projects drifts into the inter-project gap), impact (clicking a symbol surfaces every caller, importer, and member: "what breaks if I change this?" is a graph neighbourhood, not a grep), and the shape of the codebase itself (a dense petal around a file means a fat internal API; a thin one means a leaf module). A grouped filter (L1–L6 / by kind / by AST edge kind / Cross-domain) isolates any slice.

Brain: the galaxy inside a real cortex

The same graph, on a second surface: every node placed inside an anatomical cortical mesh by the neuroscience of memory systems rather than by force-direction. Episodic memories sit in the medial temporal lobe and migrate outward to neocortex along a hot→consolidated depth gradient (the complementary-learning-systems consolidation model); semantic entities in temporal neocortex; code symbols in association cortex; procedural skills in the striatum and cerebellum; domains at the connectome's rich-club hubs. Region centres are registered from real MNI152 atlas coordinates (affine fit, not vertex-exact; the mesh is a single unlabeled surface). Every synapse routes along a major white-matter tract (fornix, uncinate, SLF, corpus callosum). Node colour is the same semantic palette as the galaxy (memories by consolidation stage, entities/symbols by type), and a live Memory science panel mirrors the store's system vitals (consolidation pipeline, skills, source-monitoring, extinction, sleep phases, and every mechanism Cortex exposes).

Because the full graph (278k+ nodes, 5.5M edges) is far larger than a browser can take in one payload, the brain streams it in progressively through a bounded-queue, frame-budgeted NDJSON loader: the cloud fills in as you watch. Clicking any node opens the same rich detail card as the galaxy (content, tags, live heat, relations, git diff, impact). Open it from the Brain button in the view bar, directly at /brain, or programmatically via open_visualization(view="brain").

Board: consolidation as a kanban

Five columns by consolidation stage (labile · early_ltp · late_ltp · consolidated · reconsolidating). Each header states the stage's live count (server-side truth, not the loaded page) above its reference stage physics (decay ×, vulnerability %, plasticity %) and the stage's advancement rule (e.g. replays ≥ 1 or imp > 0.3 at `lab