Skip to content

Visual Editor

Jump to bottom
Maxim Mironenko edited this page Feb 6, 2026 · 4 revisions

Visual Editor

A web-based D3.js graph visualization with read/write capabilities. Runs as a separate FastAPI server that proxies to the MCP server.

Architecture

Browser (localhost:3000)
    │
    ├── HTTP → Visual Editor (FastAPI)
    │              │
    │              ├── HTTP → MCP Server (localhost:8765)
    │              │           (proxied REST API calls)
    │              │
    │              └── WS → MCP Server WebSocket
    │                       (real-time updates)
    │
    └── D3.js force-directed graph rendering

The visual editor is a proxy — it doesn't store data itself. All reads and writes go through the MCP server.

Setup

# 1. Start MCP server (if not running)
kg-memory start

# 2. Start visual editor
cd memory-plugin/visual-editor
./start.sh
# OR manually:
cd backend
../venv/bin/python server.py

Opens at http://localhost:3000 (or 3001/3002 if port taken).

The start script:

  • Checks MCP server is running
  • Creates venv and installs deps if needed
  • Checks port availability
  • Launches the FastAPI server

Features

Viewing

  • User graph / Project graph toggle via radio buttons
  • Project selector dropdown (discovers projects from ~/.claude/projects/)
  • Force-directed layout — nodes repel, edges attract, auto-arranges
  • Zoom/pan — Mouse wheel or +/- buttons, drag to pan
  • Click node — Details panel shows ID, level, gist, notes, touches, status badges
  • Node colors:
    • Purple: user-level node
    • Cyan: project-level node
    • Dark grey (60% opacity): archived
    • Light grey (40% opacity): orphaned

Editing

  • Right-click node → Edit — Modify gist, notes, touches (ID is read-only)
  • Right-click node → Delete — Removes node + connected edges (permanent, no undo)
  • Right-click node → Create Edge — Create relationship from this node to another (type target ID manually)
  • Right-click node → Recall — Unarchive an archived node
  • "+ New Node" button — Create node with ID, gist, notes, touches

Real-time Updates

  • WebSocket connection to MCP server (via proxy)
  • Toast notifications when other sessions modify the graph
  • Auto-reconnect on disconnect (5-second retry)
  • Connection status dot in header (green = connected)

Project Discovery

The /api/projects endpoint discovers Claude Code projects by:

  1. Scanning ~/.claude/projects/ directories
  2. Decoding project paths from .cwd field in session files (reliable method)
  3. Falling back to directory name decoding (ambiguous for paths with hyphens)
  4. Loading graph stats (node/edge counts) from each project's .claude/knowledge/graph.json

Projects are sorted by last used (most recent first) and show node/edge counts in the dropdown.

Configuration

Env Variable Default Description
EDITOR_PORT 3000 Visual editor port
EDITOR_HOST 127.0.0.1 Host binding
MCP_SERVER_URL http://127.0.0.1:8765 MCP server URL

Limitations

  • Desktop only — Minimum 1366px screen width (graph needs space)
  • No undo — Deletes are permanent
  • Edge creation — Must type target node ID (no click-to-connect)
  • Single selection — Can't multi-select nodes
  • No authentication — Anyone with localhost access can read/write
  • Context menu — May clip at screen edges
  • No search — Browse-only within the visual graph

Troubleshooting

"Cannot connect to MCP server"

kg-memory status
# If not running:
kg-memory start

Graph not loading

  • Check browser console (F12) for errors
  • Verify MCP server returns data: curl http://127.0.0.1:8765/api/graph/read
  • Check you're on the right level (user vs project)

Empty graph

  • No nodes created yet — use Claude Code to capture some knowledge first
  • For project graph: make sure you've selected a project from the dropdown

WebSocket disconnected (red dot)

  • Editor auto-reconnects every 5 seconds
  • Manual refresh: click the Refresh button
  • If persistent, restart the MCP server

Clone this wiki locally