Nodes = memory atoms (sized by importance, colored by category, shaped by outcome)
Edges = Hebbian links (weighted co-activation connections)
Clusters = groups of similar atoms found by HDBSCAN consolidation
Timeline = snapshots showing memory evolution across tasks

Visual encoding

Property	Visual
Category (pattern/color/spatial/logic/object)	Node color
Importance [0, 1]	Node size
Outcome (success/failure/unknown)	Node shape (sphere/octahedron/cube)
L2 drift (core-shell divergence)	Orange ring around node
Prototype (consolidated atom)	Outer glow
Valence (+/-)	Green/red inner glow
Hebbian weight	Edge thickness + opacity
Cluster membership	Force clustering + spatial grouping

Rendering architecture

Default mode: NodeBlob (single THREE.Points for all nodes)
Fallback mode: Legacy per-node mesh LOD (disabled by default)

Fallback policy and usage are documented in: /Users/eduardizgorodin/Projects/mnemoverse/mnemoverse-memory-viz/docs/RENDERING_MODES.md

Quick start

# Clone and install
git clone git@github.com:mnemoverse/mnemoverse-memory-viz.git
cd mnemoverse-memory-viz
pnpm install

# Run demo (needs sample-data.json in demo/)
pnpm dev
# open http://localhost:5173

Generate data from ARC experiments

# From the ARC experiment directory
cd ~/Projects/mnemoverse-workspace/cognitive-kdm/experiments/arc_v2

# Export latest experiment run
python analysis/export_memory_graph.py --latest

# Or specify a run directory
python analysis/export_memory_graph.py --run-dir results/main_L1+L2+L4+L5_0212_1507

# Copy output to demo
cp memory_graph.json ~/Projects/mnemoverse/mnemoverse-memory-viz/demo/sample-data.json

Usage as a library

Install in your project:

pnpm add @mnemoverse/memory-viz

import { MemoryGraph } from "@mnemoverse/memory-viz";
import type { MemoryGraphData } from "@mnemoverse/memory-viz";

function App() {
  const [data, setData] = useState<MemoryGraphData | null>(null);

  // Load your data...

  return (
    <MemoryGraph
      data={data}
      showDetailPanel    // Right sidebar on atom click
      showTimeline       // Snapshot slider (if multiple snapshots)
      showControls       // Top control bar
      showClusters       // Force-cluster grouping
      backgroundColor="#0a0f19"
      onAtomClick={(atom) => console.log("Clicked:", atom.id)}
    />
  );
}

Props

Prop	Type	Default	Description
`data`	`MemoryGraphData`	required	Graph data with snapshots
`width`	`number`	container width	Canvas width in px
`height`	`number`	container height	Canvas height in px
`showClusters`	`boolean`	`true`	Enable cluster force grouping
`showDetailPanel`	`boolean`	`true`	Show detail panel on click
`showTimeline`	`boolean`	`true`	Show timeline slider
`showControls`	`boolean`	`true`	Show control bar
`backgroundColor`	`string`	`#0a0f19`	Scene background color
`showParticles`	`boolean`	`false`	Enable directional particles on active links
`activeAtomIds`	`Set<string>`	-	Restrict link activation visuals to links touching these atoms
`activationStrength`	`number`	`0..1`	Intensity of link activation pulse and particle boost
`onAtomClick`	`(atom) => void`	-	Atom click callback
`onLinkClick`	`(link) => void`	-	Link click callback
`initialSnapshot`	`number`	last	Initial snapshot index

Exported components

import {
  MemoryGraph,    // Main 3D graph
  DetailPanel,    // Atom inspector sidebar
  Controls,       // Timeline + filters bar
  theme,          // Aurora glass-ui tokens
  CATEGORY_STYLES // Category color palette
} from "@mnemoverse/memory-viz";

Data format

The component expects a MemoryGraphData JSON object:

interface MemoryGraphData {
  label: string;           // Experiment name
  laws: string;            // Active laws, e.g. "L1+L2+L4+L5"
  snapshots: GraphSnapshot[];
}

interface GraphSnapshot {
  task: number;            // Task counter (e.g. 100, 200, 300)
  nAtoms: number;
  nLinks: number;
  atoms: MemoryAtom[];
  links: HebbianLink[];
  clusters?: Cluster[];
}

interface MemoryAtom {
  id: string;
  taskId: string;
  content: string;         // Human-readable insight
  category: string;        // e.g. "root/spatial/rotation"
  topCategory: string;     // "pattern" | "color" | "spatial" | "logic" | "object"
  importance: number;      // [0, 1]
  valence: number;         // [-1, +1]
  feedbackScore: number;
  timestamp: number;
  accessCount: number;
  isSuccessful: boolean | null;
  isPrototype: boolean;
  sourceAtoms: string[];
  drift: number;           // Core-shell cosine distance
  poincareRadius: number;  // Position in hierarchy
  clusterId: number;       // -1 = outlier
  x?: number;              // Pre-computed 3D position
  y?: number;
  z?: number;
}

interface HebbianLink {
  source: string;
  target: string;
  weight: number;          // [0, 1+]
}

Interactions

Hover a node to highlight its neighbors and connections
Click a node to open the detail panel with all properties
Orbit mode (default): scroll to zoom, right-drag to pan, left-drag to rotate, click focuses camera on node
Explorer mode: W/A/S/D move, Q/E up/down, Shift boost, hold RMB to look around, Esc returns to Orbit
Timeline dots switch between memory snapshots (task 100, 200, 300...)
Category filter buttons show/hide atom types
Search filters atoms by content, category, or task ID
Aa toggle shows text labels on large nodes
Cluster toggle enables/disables cluster force grouping

Design system

Follows the glass-ui Aurora theme for visual consistency across Mnemoverse products:

Deep polar night background (#0a0f19)
Ethereal mint primary (#4dd0b5)
Soft aurora violet secondary (#a78bfa)
Glassmorphism panels (blur(16px) saturate(180%))
Apple-style border radius (16px)

Tech stack

react-force-graph-3d — 3D force-directed graph (Three.js + d3-force-3d)
Three.js — WebGL rendering
tsup — Library bundling
Vite — Demo dev server

Development

pnpm dev          # Start demo at localhost:5173
pnpm build        # Build library to dist/
pnpm type-check   # TypeScript validation

License

MIT

FAQs

What is @mnemoverse/memory-viz?

Is @mnemoverse/memory-viz popular?

Is @mnemoverse/memory-viz well maintained?

Package last updated on 31 May 2026

@mnemoverse/memory-viz