Server Management

Server Management

Commands

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

kg-memory start     # Start the server (background, nohup)
kg-memory stop      # Stop the server (SIGTERM, then SIGKILL after 2s)
kg-memory restart   # Stop + start
kg-memory status    # Check PID + hit /health endpoint
kg-memory logs      # tail -f /tmp/mcp_server.log

Alternative (without global command):

cd ~/.claude/plugins/cache/maxim-plugins/memory/latest/server
./manage_server.sh start

What Happens on Start

1. Script checks PID file — if server already running, exits
2. Runs mcp_streamable_server.py via the venv Python, backgrounded with nohup
3. PID written to .mcp_server.pid
4. Waits 2 seconds, checks if process is alive
5. Server loads user graph from ~/.claude/knowledge/user.json
6. Starts background saver thread (30s interval)
7. Listens on http://127.0.0.1:8765/

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)
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	~/.claude/plugins/cache/maxim-plugins/memory/latest/server/mcp_streamable_server.py
PID file	~/.claude/plugins/cache/maxim-plugins/memory/latest/server/.mcp_server.pid
Logs	/tmp/mcp_server.log
Python venv	~/.claude/plugins/cache/maxim-plugins/memory/latest/server/venv/
MCP config	~/.claude/plugins/memory/.mcp.json

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 ~/.claude/plugins/cache/maxim-plugins/memory/latest/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.

Troubleshooting

Server won't start

# Check if port is taken
lsof -i :8765

# Check for stale PID file
cat ~/.claude/plugins/cache/maxim-plugins/memory/latest/server/.mcp_server.pid
ps -p $(cat ~/.claude/plugins/cache/maxim-plugins/memory/latest/server/.mcp_server.pid)

# Remove stale PID and try again
rm ~/.claude/plugins/cache/maxim-plugins/memory/latest/server/.mcp_server.pid
kg-memory start

Server crashes on start

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

# Common: missing dependencies
cd ~/.claude/plugins/cache/maxim-plugins/memory/latest/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 points to right URL
cat ~/.claude/plugins/memory/.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.