Visual Editor

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 (with reload=true to always show latest disk data).

Setup

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

# 2. Start visual editor (recommended)
kg-visual start

# OR manually:
cd knowledge-graph/visual-editor/backend
../venv/bin/python server.py

Management Commands

After running install_command.sh, the kg-visual command is available:

kg-visual start     # Start the visual editor (detached)
kg-visual stop      # Stop the visual editor
kg-visual restart   # Stop + start
kg-visual status    # Check if running
kg-visual logs      # tail -f /tmp/visual_editor.log

Opens at http://localhost:3000.

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 from centralized storage at ~/.knowledge-graph/projects/<slug>/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?reload=true
• 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