Skip to content

Server Management

Jump to bottom
Maxim Mironenko edited this page Mar 16, 2026 · 10 revisions

Server Management

Commands

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.

Migration & Recovery Tools

Legacy Migration

Migrates data from old .claude/knowledge/ paths to centralized ~/.knowledge-graph/:

kg-memory migrate              # Dry run
kg-memory migrate --apply      # Apply migration

Migration runs automatically on first server start if needed.

Session Replay (Data Recovery)

Reconstructs graph data from Claude Code session history:

cd <plugin-dir>/server
./venv/bin/python tools/replay_sessions.py           # Dry run
./venv/bin/python tools/replay_sessions.py --apply   # Apply recovery

Scans all ~/.claude/projects/ JSONL session files for kg_put_node/kg_put_edge tool calls and rebuilds the graph.

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