Skip to content

Visual Editor

Jump to bottom
Claude edited this page Oct 9, 2026 · 9 revisions

Visual Editor

A browser view of your memory: a D3.js force-directed graph with search, score explanations and editing. It runs as a small local web server (FastAPI) that forwards every request to the memory server. It stores no data of its own.

Architecture

Browser (http://localhost:8766)
    │
    ├── HTTP → Visual Editor (FastAPI, port 8766)
    │              │
    │              ├── HTTP → memory server REST API  (MCP_SERVER_URL/api/*)
    │              │
    │              └── WS proxy → memory server WebSocket (MCP_SERVER_URL/ws)
    │                             (live graph updates)
    │
    └── D3.js force-directed graph + three-panel UI

MCP_SERVER_URL defaults to http://127.0.0.1:8765. Both the REST requests and the live-update socket follow it, so an editor started for a server on another port talks only to that server. Search runs kg_search's ranking on a read-only snapshot of the selected graph, and score explanations come from the memory server's live scorer.

The editor is for your own machine. It binds to 127.0.0.1 by default, only answers requests addressed to localhost, 127.0.0.1 or [::1], and refuses requests a browser marks as cross-site, so another web page cannot use it to read or change your memory. There is no login: anything running on your machine can reach it.

Getting Started

kg editor        # starts the memory server and the editor if needed
kg editor stop   # stops the editor (the memory server keeps running)

kg editor prints the address (http://localhost:8766) and, when run in a terminal, opens it in your browser. The editor runs in the background until you stop it.

  • Log: ~/.local/state/knowledge-graph/visual_editor.log. When the memory server uses another KG_HTTP_PORT, the log is in port-<N>/ inside that directory, and kg editor points the editor at that server.
  • Another editor port: set EDITOR_PORT (default 8766) in the environment of kg editor. See Configuration for EDITOR_HOST and MCP_SERVER_URL.
  • Internet access: the page loads the D3 library from d3js.org, so the browser needs to reach that site.

Layout

The editor has three resizable panels:

┌──────────────┬─────────────────────────────┬──────────────────┐
│  GRAPHS      │         GRAPH               │   DETAILS        │
│  (left)      │      (center)               │  (right)         │
│              │                             │                  │
│  User Graph  │   D3 force-directed         │  Identity        │
│  ─────────── │   canvas                    │  Description     │
│  project-a   │                             │  Archival score  │
│  project-b   │                             │  Notes           │
│  project-c   │                             │  Files           │
│              │                             │  Connections     │
└──────────────┴─────────────────────────────┴──────────────────┘

Drag the thin divider bars between panels to resize them. The header shows which graph is open, a Refresh button and the connection status.

Selecting a Graph

Click an entry in the left panel:

  • User Graph: cross-project knowledge (preferences, patterns, principles).
  • Project entries: one per project graph, with node and edge counts (12N · 30E).

The selected entry is highlighted with a blue left border.

Projects come from the memory server's stored graphs and the project path each graph records, so projects used only by Codex or Antigravity appear too. A project whose folder no longer exists is marked folder removed; its graph can still be opened. An old graph with no project path on record is marked path unknown and cannot be opened from the editor. Only when the memory server is unreachable or too old to list projects does the editor fall back to scanning Claude Code's history in ~/.claude/projects/.

Node Interaction

Viewing Details

Click a node to open its details in the right panel:

Section Contents
Identity ID (read-only) and status badges (level, archived, orphaned)
Description The gist, the one-line summary
Archival score Total score, factor ranks and contributions, and an expandable raw calculation
Notes Detailed notes, one per entry
Files & Artifacts Touches: related file paths
Connections All edges: outgoing (→) and incoming (←)

Click a peer name under Connections to move the selection to that node. Viewing details does not change the node.

Archival Score

The card uses the memory server's live scorer. Its three factors are recency (25%), connectedness (40%) and usefulness (35%). Each factor is ranked within the eligible pool in this graph, and equal raw values share a percentile. The weighted contributions add up to a score from 0 to 1. Higher scores stay active longer; when archival and refill happen also depends on the graph's size budget.

Expand Raw values and calculation to see:

  • the latest write, read and credit times (recency is the latest of the three; an endorsement, a repeat or a maintenance credit counts as a credit),
  • incoming and outgoing connection counts and their weights, and the hub floor,
  • explicit endorsements and their 90-day decay half-life.

Active nodes show the score used for archival among eligible active nodes. Archived nodes show the score used for refill among eligible active and archived nodes. Nodes in the fresh tier (the newest work, up to 30% of the level's budget) are not scored yet; their card shows a marked preview of the score they will have once newer work pushes them out. Orphaned nodes show a preview as if recalled to active. The card names its comparison pool, and looking at it never recalls a node.

Inline Editing

Hover over the Description, Notes or Files & Artifacts section header and a pen icon (✎) appears. Click it to edit in place:

  • Gist: a text box with a live character counter. The server's target is 300 characters. Longer gists can still be saved; the counter turns red and says "over target". The target comes from the server, and the count matches the server's Unicode counting.
  • Notes: one note per line.
  • Touches: one file path per line.

Click Save to write the change immediately, or Cancel to discard it.

The ID and status cannot be edited here. To rename a node, ask the agent to use kg_rename_node, which carries its edges, history and references in other graphs along. Archival and orphaning are managed by the memory server; use Recall to bring a node back.

Context Menu (Right-Click)

Right-click a node:

  • Edit Node: a form with all fields (the ID is read-only).
  • Delete Node: asks for confirmation, then removes the node and all its edges. There is no undo.
  • Recall: brings an archived or orphaned node back to active. This is a real read by ID, the same promotion kg_read with ids performs.
  • Create Edge: starts an edge from this node to another.

Views and Search

The Visible nodes and All nodes buttons sit above the canvas:

  • Visible nodes is the default: active nodes and their immediate neighbors. Archived neighbors appear dimmed. Include orphaned adds every orphaned node to this view.
  • All nodes shows every stored node, including archived and orphaned ones.

The footer reports how many nodes are shown. Edges are counted as drawn, hidden, or dangling when an endpoint is not in this graph.

Type in the search field and press Search (or Enter). Ctrl+K (⌘K on a Mac) focuses the field. Search uses kg_search's matching and ranking over IDs, descriptions, notes and file references. It covers every tier of the selected graph, whatever the current view.

The right panel lists matches in ranked order with the matching text highlighted. The canvas shows the top five matches, numbered, and the nodes that connect them. Show all matches adds the remaining hits to the canvas (Show top 5 goes back). Select a result to reveal it and see its details, including a node hidden by the default view. Search, selection, view changes and score inspection change nothing in memory.

Clear, or Escape in the search field, returns to the previous view. Choosing Visible nodes or All nodes also ends the search. Switching graphs clears the query, so results always belong to the open graph.

Creating Nodes

Click New Node in the graph toolbar and fill in:

  • Node ID: lowercase letters, digits and hyphens, starting and ending with a letter or digit (for example my-concept). Aim for three to five words naming the subject; the server refuses a new ID of seven words or more.
  • Description (Gist): a short summary, ideally within the server's 300-character target. The form warns above the target and still allows saving.
  • Notes: optional, one per line.
  • Touches: optional file paths, one per line.

If the ID already exists in this graph, saving updates that node instead of creating a new one.

Creating Edges

  1. Right-click a node and choose Create Edge.
  2. Enter the target node ID and a relationship label (for example depends-on).
  3. Optionally add notes.
  4. Click Create.

The target ID is not checked when you save. A typo creates an edge to a node that does not exist; it shows as dangling and is removed the next time the graph is loaded from disk. A project-graph edge may point to a user-graph node; that cross-level edge is kept.

Common relationship labels: depends-on, implements, extends, uses, instance-of, related-to, documents, fixes. An instance-of edge from a newer node to an older principle counts as evidence that the principle was needed again, and credits it.

Navigation

Action How
Select a node Left-click
Pan Click and drag on the background
Zoom Scroll wheel, or the zoom-in and zoom-out buttons
Reset zoom The Reset zoom button (circular arrow)
Context menu Right-click a node
Move a node (until the next layout) Drag it

Connection Status

The indicator in the top-right corner shows the editor's link to the memory server:

  • Live (green): connected and subscribed to the graph on screen. Changes an agent makes to the user graph, or to the project you are viewing, appear automatically with a short notice. Changes to other projects never reach this page; they show when you select that project.
  • Connected (green): connected to a memory server too old for project subscriptions. User-graph changes arrive live; press Refresh for project-graph changes.
  • Offline (red): the socket dropped. The editor reconnects every 5 seconds and reloads the graph on screen once it is back, so changes made meanwhile are not missed.
  • Server down or Unreachable (red): the editor cannot reach the memory server, so reads and writes fail.

If Offline or Server down persists, run kg status, and kg start if the server is not running.

Node States

Appearance Meaning
Green fill Active
Dark grey, dashed border, 50% opacity Archived (kept on disk, shown in reads only as an anchor)
Hollow, dotted border, 60% opacity Orphaned (reachable only through search; may still have stored edges)
Gold ring Selected

Node size grows with the number of connections, so hub nodes appear larger.

Troubleshooting

"Cannot connect to MCP server"

kg status
kg start   # if not running

Persistent Offline indicator

kg restart

Then reload the browser tab.

The editor does not start

Read ~/.local/state/knowledge-graph/visual_editor.log (or port-<N>/visual_editor.log). A common cause is another program already using port 8766; set EDITOR_PORT to use another port.

Graph not loading, or empty

  • Check that you selected a graph in the left panel.
  • For a project graph, the agent has to capture some project memory first. A project listed with path unknown cannot be opened from the editor.
  • Check the log named above.

Changes not appearing

  • Check the connection status indicator.
  • Press Refresh in the header.
  • When the status is Live, changes to the user graph and to the project on screen arrive automatically; when it reads Connected, the memory server is older and project-graph changes need Refresh.

A dialog won't close

Press Escape, click the ✕ button or Cancel, or click the dark area behind the dialog.

Known Limitations

  • Edges: you have to type the target node ID (no click-to-connect), and edges cannot be deleted from the editor. Ask the agent to use kg_delete_edge.
  • Renames: node IDs cannot be changed in the editor.
  • No undo: every operation is immediate.
  • Single selection: you cannot select several nodes at once.
  • Live updates cover the user graph and the selected project; another project's changes show when you select it.
  • Desktop only: the page requires a window at least 1366 pixels wide.

Requirements

  • A browser window at least 1366 pixels wide
  • A current browser with WebSocket support (Chrome, Firefox, Safari)
  • Access to d3js.org, where the page loads its D3 library
  • The memory server running (kg editor starts it if needed)

Clone this wiki locally