mempalace-viz

The visual explorer for mempalace.
See your AI memory as a force-directed graph. Search it, browse it, understand it.

Live Demo · Quick Start · Components · Theming · API · Development

---

---

What is this?

mempalace stores your AI conversation history as a searchable knowledge base in ChromaDB, organized into a palace hierarchy: Wings (projects), Rooms (knowledge types), Closets (conversations), and Drawers (distilled knowledge items). It achieves 96.6% recall on LongMemEval benchmarks at a fraction of the cost of full-context approaches.

mempalace-viz is the visual layer. It renders that palace as a live, interactive force-directed graph. Wings orbit the center. Rooms cluster around their wing. Closets emerge as you zoom in. Everything is searchable, clickable, and themeable.

The library ships as three entry points so you can use exactly what you need:

mempalace-viz          -- everything (React + core + CSS)
mempalace-viz/core     -- framework-agnostic (types, simulation, colors)
mempalace-viz/react    -- React components, provider, hooks

Features

Visualization

• Force-directed layout with tunable physics (charge, gravity, link distance, collision radius, alpha/velocity decay)
• Canvas-rendered nodes with radial gradients, glow halos, and hover highlights
• Semantic zoom -- closets fade in as you approach, labels scale with distance
• Smooth performance with thousands of nodes

UI

• Sidebar navigation tree for browsing wings and rooms
• Global search with keyboard navigation (Ctrl+K)
• Detail panels for wings, rooms, and closets with stats and charts
• Animated view transitions

Explore wings and rooms

Browse and drill down

Inspect individual drawers

Search across everything

Library

• Fully scoped CSS -- all styles namespaced under [data-mempalace], zero leakage
• Theme customization via --mpv-* CSS variables
• Tree-shakeable ESM with subpath exports
• TypeScript declarations included
• 23 unit tests covering the force simulation engine

Install

npm install github:stephengardner/mempalace-viz

Quick start

mempalace-viz needs a running API that serves your palace data. The included api/main.py reads directly from a mempalace ChromaDB store:

# Start the API server (requires a mined palace)
cd api && pip install -r requirements.txt
MEMPALACE_PALACE_PATH=~/.mempalace/palace uvicorn main:app --port 8787 --reload

Then point the provider at your API:

import { MemPalaceProvider, PalaceGraph } from 'mempalace-viz'
import 'mempalace-viz/style.css'

function App() {
  return (
    <MemPalaceProvider baseUrl="http://localhost:8787">
      <PalaceGraph
        width={800}
        height={600}
        onSelectWing={(wing) => console.log(wing)}
        onSelectRoom={(wing, room) => console.log(wing, room)}
      />
    </MemPalaceProvider>
  )
}

If you proxy /api to your API server (e.g. via Vite's server.proxy), you can use baseUrl="/api" instead.

Using the core without React

Build your own UI in Vue, Svelte, or vanilla JS:

import {
  ForceSimulationService,
  createFetchAdapter,
  getWingPalette,
} from 'mempalace-viz/core'

const adapter = createFetchAdapter('https://my-api.example.com')
const graph = await adapter.fetchGraph()
const service = new ForceSimulationService()

// Attach to any force-graph instance and tune physics
service.attach(forceGraphInstance)
service.updateParam('charge', -80)
service.updateParam('centerGravity', 0.15)

Components

All React components are exported from mempalace-viz/react (or the root).

Component	Description
MemPalaceProvider	Context wrapper. Accepts baseUrl (string) or a custom adapter. All components below must be descendants.
PalaceGraph	The main canvas. Force-directed graph with zoom controls, hover tooltips, and a settings panel for tuning physics in real time.
Sidebar	Collapsible navigation tree. Lists wings with room counts, expandable to show rooms.
StatsBar	Horizontal bar showing palace-wide totals (wings, rooms, closets, drawers).
SearchPanel	Full-screen modal. Fuzzy search across all drawers with keyboard navigation and result highlighting.
WingDetail	Drilldown view for a single wing. Room table with drawer/closet counts and a distribution chart.
RoomDetail	Drilldown view for a room. Lists closets sorted by size with average value scores.
ClosetDetail	Slide-in panel showing all drawers inside a closet with tags and content previews.

Core exports

Importable via mempalace-viz/core. No React required -- use these to build wrappers in Vue, Svelte, or vanilla JS.

Export	Description
ForceSimulationService	Wraps d3-force. Manages simulation lifecycle, parameter updates, reheat, and reset.
DEFAULT_FORCE_PARAMS	The default parameter values for every tunable knob.
FORCE_PARAM_CONFIGS	Metadata array (label, min, max, step, group, info) for building settings UIs.
createFetchAdapter(baseUrl?)	Returns a PalaceDataAdapter that fetches from REST endpoints.
getWingPalette(wing)	Deterministic { core, glow } color pair for any wing name. Known names get curated colors; unknown names get a stable hash-derived hue.
getWingColor(wing)	Shorthand -- returns just the core color string.
hexToRgba(color, alpha)	Converts hex or HSL strings to rgba/hsla with a given alpha.
cn(...classes)	Tailwind-merge utility for conditional class merging.

Theming

All styles live inside [data-mempalace] and reference --mpv-* CSS custom properties. Override any token to reskin the entire library:

[data-mempalace] {
  /* Surfaces */
  --mpv-background: #1a1a2e;
  --mpv-card: #16213e;
  --mpv-border: #2a2a4a;

  /* Text */
  --mpv-foreground: #eee;
  --mpv-muted-foreground: #888;

  /* Accent */
  --mpv-primary: #e94560;
  --mpv-accent: #0f3460;
  --mpv-ring: #e94560;

  /* Sidebar */
  --mpv-sidebar: #0f0f23;
  --mpv-sidebar-foreground: #ccc;
  --mpv-sidebar-border: #1a1a3e;

  /* Radius */
  --mpv-radius: 0.375rem;
}

The default theme uses a GitHub Dark color palette. Every Tailwind utility class in the library is scoped under [data-mempalace], so nothing leaks into your app.

API contract

MemPalaceProvider accepts a baseUrl and constructs a fetch-based data adapter. Your server needs to implement these endpoints:

Method	Path	Response type	Description
GET	/palace	PalaceOverview	Full hierarchy with wing/room/closet counts
GET	/wing/:name	WingDetail	Single wing with rooms and top closets
GET	/room/:wing/:room	RoomDetail	Single room with closet list
GET	/closet/:wing?name=<name>	ClosetDetail	Closet contents (all drawers)
GET	/graph	GraphData	Nodes and links for the force graph
GET	/search?q=<query>	{ results: SearchResult[] }	Semantic search (optional wing, room filters)

All types are exported from mempalace-viz/core so you can type your server responses.

A reference implementation is included in api/main.py -- a FastAPI server that reads directly from a mempalace ChromaDB store and serves all six endpoints.

Architecture

src/
  index.ts          -- root entry (re-exports react, imports CSS)
  core.ts           -- framework-agnostic entry
  react.ts          -- React entry (re-exports core)
  types/            -- shared TypeScript interfaces
  lib/
    ForceSimulationService.ts   -- d3-force wrapper with parameter management
    ForceSimulationService.test.ts  -- 23 tests including root-cause regression tests
    MemPalaceProvider.tsx       -- React context + data-mempalace scope boundary
    PalaceDataAdapter.ts        -- fetch adapter interface + implementation
    colors.ts                   -- deterministic wing color system
    useForceSimulation.ts       -- React hook for simulation state
    utils.ts                    -- cn() helper
  components/       -- React UI components
  lib.css           -- library stylesheet (scoped, no global resets)
  index.css         -- dev app stylesheet (global resets, extends lib.css)

The library build produces three chunks:

• core-*.js (~44 kB) -- types, simulation, colors, adapter
• react-*.js (~49 kB) -- components, hooks, provider
• style.css (~34 kB / 6 kB gzip) -- fully scoped styles

Development

Requires a mempalace installation with at least one mined palace.

# Install dependencies
npm install

# Start the API server (reads from your mempalace ChromaDB store)
cd api && pip install -r requirements.txt
MEMPALACE_PALACE_PATH=~/.mempalace/palace uvicorn main:app --port 8787 --reload

# Start dev server (proxies /api to localhost:8787)
npm run dev

# Run tests
npm test

# Build the library
npm run build:lib

Peer dependencies

React components require these in your project:

Package	Version
react	^18.0.0 or ^19.0.0
react-dom	^18.0.0 or ^19.0.0
d3-force	^3.0.0
react-force-graph-2d	^1.29.0
framer-motion	^12.0.0
lucide-react	^1.0.0
recharts	^3.0.0 (optional -- only needed for WingDetail charts)

The /core entry point has no peer dependencies.

License

MIT