Skip to content

Server Management

Jump to bottom
Maxim Mironenko edited this page Jul 3, 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 stays running across sessions — not spawned per session. You normally don't start it yourself: a SessionStart hook health-checks it on every session and launches it in the background when down; the start script builds the Python environment automatically on first run (and after plugin updates, which install into a fresh directory). The hook only ever starts the server — it never stops or restarts one you're running. The commands below are for manual control.

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:8766
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 ~/.local/state/knowledge-graph/mcp_server.log
kg-memory commit     # Force git commit of ~/.knowledge-graph/ (only if you've git-init'd it)

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.

Git auto-commit: if ~/.knowledge-graph is a git repository, stop and restart automatically commit all graph changes (throttled to once per 10 minutes); kg-memory commit forces one anytime. See Data and Backup → Versioned History for the one-time setup.

What Happens on Start

  1. Script checks PID file — if server already running, exits
  2. Builds the Python venv if missing (first run or post-update; one-time ~1 min)
  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, refill, 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
GET /api/nodes/{level}/{id} REST read node (auto-promotes archived → active)
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

All endpoints require a local Host header (localhost / 127.0.0.1 / ::1); other hosts get 421 — this closes the DNS-rebinding route around CORS. WebSocket upgrades additionally require a local (or absent) Origin. There is no authentication beyond that: the trust boundary is processes on your machine — see SECURITY.md.

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 ~/.local/state/knowledge-graph/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. The bundled unit calls the kg-memory shim from ~/.local/bin/, so it stays valid across plugin updates.

Prerequisite: run install_command.sh once (see Installation → Optional shell commands) so the shim exists.

# Copy the unit file once
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

Re-run the cp only when the unit definition itself changes. Environment variables for the server (port, log level, etc.) live in the unit's Environment= lines — edit your local copy at ~/.config/systemd/user/memory-mcp.service, then systemctl --user daemon-reload && systemctl --user restart memory-mcp.service.

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 ~/.local/state/knowledge-graph/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