@mnemoverse/memory-viz

Interactive 3D visualization of AI memory systems. Explore memory atoms, Hebbian links, clusters, and consolidation dynamics in real-time.

Built for Mnemoverse — spatial AI memory with geometric knowledge landscapes.

What it looks like

A 3D force-directed graph where:

• 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 [email protected]: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