Skip to content

Visual Editor

Jump to bottom
Maxim Mironenko edited this page May 18, 2026 · 3 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, port 3000)
    │              │
    │              ├── HTTP → MCP Server REST API (localhost:8765/api/*)
    │              │
    │              └── WS proxy → MCP Server WebSocket (localhost:8765/ws)
    │                            (real-time graph update push)
    │
    └── D3.js force-directed graph + three-panel UI

The visual editor is a proxy — it stores no data. All reads/writes go through the MCP server.

Setup

kg-memory start   # start MCP server (if not running)
kg-visual start   # start visual editor

Opens at http://localhost:3000.

Management

kg-visual start | stop | restart | status | logs

Layout

Three resizable panels — drag dividers to resize:

Panel Default width Contents
Left ~200px (min 140, max 320) Project selector list
Center flex (all remaining) D3 force-directed graph
Right ~360px (min 240, max 600) Node details

Features

Graph Selection (Left Panel)

Vertical list — click to activate:

  • User Graph — global cross-project knowledge
  • Project entries — per-project knowledge, shows N·E counts

Active entry has a blue left border. Projects with no graph show "no graph".

Graph Visualization (Center)

  • Force-directed layout — nodes repel, edges attract
  • Zoom/pan — scroll wheel, drag background, or toolbar buttons
  • Node size scales with connection count (hub nodes larger)
  • Click node — loads details in right panel
  • Right-click node — context menu

Node states:

Style Meaning
Green filled Active
Dark grey dashed, 50% opacity Archived
Hollow dotted, 60% opacity Orphaned (no edges)
Gold ring Selected

Node Details (Right Panel)

Sections shown for the selected node:

  • Identity — ID (read-only), level/archived/orphaned badges
  • Description — Gist with inline pen-icon editing
  • Notes — List of notes with inline pen-icon editing
  • Files & Artifacts — Touches with inline pen-icon editing
  • Connections — All edges: → rel peer (outgoing) and ← rel peer (incoming); click peer to jump selection

Inline Editing

Hover any section label in the details panel — a pen icon (✎) appears. Click it to edit in place:

  • Gist: ≤120 character hard limit enforced; counter turns red if over, Save blocked
  • Notes: one note per line (blank lines ignored)
  • Touches: one file path per line

Save → POST /api/nodes upsert → optimistic in-memory update → background graph reload.

ID, level, status are read-only — renaming an ID would orphan all edges that reference it; status is compactor-managed.

Context Menu (Right-Click)

  • Edit Node — full modal editor
  • Delete Node — permanent, removes node + all edges
  • Recall — unarchive an archived node
  • Create Edge — create outgoing edge (type target ID)

Real-Time Updates (Connection Status)

Top-right indicator:

State Meaning
● Live (green) WebSocket open — graph auto-refreshes when Claude writes memory
● Offline (red) WebSocket dropped — auto-reconnects every 5s
● Server down (red) MCP server unreachable — kg-memory start

The WebSocket path is /ws on the MCP server (port 8765), proxied through the Express layer. Fixed in v0.9.7 — was permanently Offline before due to a missing ASGI route branch.

Project Discovery

/api/projects scans ~/.claude/projects/ directories, decodes project paths from .cwd fields in session files, and loads graph stats from ~/.knowledge-graph/projects/<slug>/graph.json. Sorted by last used.

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
  • No undo — deletes are permanent
  • Edge creation requires typing target node ID (no click-to-connect)
  • Single node selection only
  • No search / filter within graph

Troubleshooting

"Cannot connect to MCP server"

kg-memory status
kg-memory start

Persistent Offline indicator

kg-memory restart
# then reload browser tab

Graph not loading

  • Select a graph in the left panel first
  • Check logs: kg-visual logs, kg-memory logs
  • Raw data check: curl http://127.0.0.1:8765/api/graph/read?reload=true

Empty project graph

  • Project needs at least one node — use Claude to capture knowledge first

Clone this wiki locally