Skip to content

Server Management

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

Server Management

Commands

After running install_command.sh, 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

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

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

Alternative (without global command):

cd <plugin-install-dir>/server
./manage_server.sh start

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

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
Graph data ~/.knowledge-graph/

Systemd Service (Optional, Linux Only)

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

# Link service file
mkdir -p ~/.config/systemd/user
ln -s <plugin-dir>/server/memory-mcp.service \
      ~/.config/systemd/user/

# 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.

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
cd <plugin-dir>/server
./venv/bin/pip install -r requirements.txt

Claude Code can't connect

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

# Check MCP config
cat <plugin-dir>/.mcp.json
# 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.

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