Skip to content

Server Management

Jump to bottom
Maxim Mironenko edited this page May 20, 2026 · 10 revisions

Server Management

The plugin's MCP server is a shared HTTP service on port 8765 used by all Claude Code sessions simultaneously. It is started manually (or by your init system) and stays running across sessions — not spawned per session.

Heads up: the optional install_command.sh step (one-time after /plugin install) is what creates the kg-memory and kg-visual shell commands referenced below. See Installation → Optional shell commands. Without it, you can still run the underlying scripts directly — see the "Without global commands" subsection.

Commands

Once install_command.sh has been run, two commands are available globally:

kg-visual — Visual Editor

kg-visual start     # Start visual editor at http://localhost:3000
kg-visual stop      # Stop the editor
kg-visual restart   # Restart
kg-visual status    # Check if running
kg-visual logs      # tail -f editor logs

The visual editor is optional — it's a browser-based graph explorer. The MCP server (kg-memory) must be running for the editor to connect.

kg-memory — MCP Server

kg-memory start      # Start the server (detached via setsid)
kg-memory stop       # Stop the server (SIGTERM with PID validation)
kg-memory stop-port  # Stop by finding process on port (fallback)
kg-memory restart    # Stop + start (safe from within Claude Code)
kg-memory status     # Check PID + hit /health endpoint
kg-memory logs       # tail -f /tmp/mcp_server.log
kg-memory commit     # Force git commit of ~/.knowledge-graph/
kg-memory migrate    # Run legacy data migration

Without global commands (if you skipped the optional setup script):

"$(find ~/.claude/plugins/cache/maxim-plugins/knowledge-graph -name manage_server.sh | sort -V | tail -1)" start
"$(find ~/.claude/plugins/cache/maxim-plugins/knowledge-graph -name manage_visual.sh | sort -V | tail -1)" start

The path resolves to the current installed plugin version automatically.

What Happens on Start

  1. Script checks PID file — if server already running, exits
  2. Runs auto-migration if centralized storage is empty but legacy data exists
  3. Launches mcp_streamable_server.py via setsid (fully detached from calling process)
  4. PID written to .mcp_server.pid, process disowned from shell
  5. Waits for /health endpoint to respond (up to 10s)
  6. Server loads user graph from ~/.knowledge-graph/user.json
  7. Starts background maintenance thread (compaction, orphan pruning every 30s)
  8. Listens on http://127.0.0.1:8765/

Safe Restart

The server is safe to restart from within Claude Code sessions:

  • setsid launches the new server in its own process session — no signal propagation to Claude Code
  • disown removes it from the shell's job table
  • PID validation before kill — verifies the PID belongs to mcp_streamable_server before sending SIGTERM. If the PID was recycled to another process, it refuses to kill and falls back to port-based stop
  • Graceful SIGTERM — sets uvicorn.should_exit = True for proper connection draining instead of abrupt sys.exit()
  • Port-free wait — ensures the port is released before starting the new server

Endpoints

Endpoint Purpose
POST / MCP Streamable HTTP (tool calls from Claude Code)
GET /health Simple health check with version, session count
GET /api/health Detailed health for visual editor
GET /api/graph/read REST read (visual editor). Supports reload=true to force disk re-read
POST /api/nodes REST create/update node
DELETE /api/nodes/{level}/{id} REST delete node
POST /api/edges REST create/update edge
DELETE /api/edges/{level}/{from}/{to}/{rel} REST delete edge
POST /api/nodes/{level}/{id}/recall REST recall archived node
GET /api/progress/{task_id} REST get task progress
POST /api/progress REST set task progress
GET /api/sessions/{id}/stats REST session stats
WS /ws WebSocket for visual editor real-time updates

File Locations

<plugin-dir> below resolves to ~/.claude/plugins/cache/maxim-plugins/knowledge-graph/<version>/ — the version-stamped cache dir. You normally don't need to navigate there yourself; the commands above handle it.

File Location
Server script <plugin-dir>/server/mcp_streamable_server.py
PID file <plugin-dir>/server/.mcp_server.pid
Logs /tmp/mcp_server.log
Python venv <plugin-dir>/server/venv/
MCP config <plugin-dir>/.mcp.json (don't edit — overwritten on update)
Graph data ~/.knowledge-graph/

Systemd Service (Optional, Linux Only)

For auto-start on boot and auto-restart on crashes:

# Copy service file (don't symlink — plugin cache path changes on update)
mkdir -p ~/.config/systemd/user
cp "$(find ~/.claude/plugins/cache/maxim-plugins/knowledge-graph -name memory-mcp.service | sort -V | tail -1)" \
   ~/.config/systemd/user/memory-mcp.service

# Enable and start
systemctl --user enable memory-mcp.service
systemctl --user start memory-mcp.service

# Check status
systemctl --user status memory-mcp.service

# View logs
journalctl --user -u memory-mcp.service -f

The service file configures all environment variables with sensible defaults. Re-run the cp after a plugin update only if the bundled unit file itself changed.

Data Recovery

If graph data is lost or corrupted, use backups first (see Data and Backup). If backups are unavailable, use the kg-scout skill to mine Claude Code's conversation history and rebuild knowledge from past sessions:

/skill kg-scout

Scout scans ~/.claude/projects/ JSONL files for patterns, decisions, and insights — no separate script required. Extend cleanupPeriodDays in ~/.claude/settings.json to maximize the recoverable history window (see Installation).

Troubleshooting

Server won't start

# Check if port is taken
lsof -i :8765

# Use port-based stop as fallback
kg-memory stop-port

# Then start
kg-memory start

Server crashes on start

# Check logs for Python errors
cat /tmp/mcp_server.log

# Common: missing dependencies — reinstall the plugin to rebuild the venv
# /plugin uninstall knowledge-graph@maxim-plugins
# /plugin install knowledge-graph@maxim-plugins

Claude Code can't connect

# Verify server is responding
curl http://127.0.0.1:8765/health

# Check MCP config (read-only — don't edit; clobbered on update)
cat "$(find ~/.claude/plugins/cache/maxim-plugins/knowledge-graph -name .mcp.json | sort -V | tail -1)"
# Should show: "url": "http://127.0.0.1:8765/"

Server using too much memory The in-memory store grows with loaded project graphs. Each project graph stays loaded once accessed. Restart the server to unload all project graphs — they reload on demand.

MCP tools go offline after restart After kg-memory restart, Claude Code's MCP connection reference goes stale — KG tools become unavailable in the current session. To restore them: run /mcp in Claude Code, find plugin:knowledge-graph:kg in the list, and hit Reconnect. Tools are available again immediately.

Stale PID warning If you see "WARNING: PID X is NOT the MCP server", the PID file contained a recycled PID. The server will automatically fall back to port-based stop. This safety check prevents accidentally killing unrelated processes.

Clone this wiki locally