Skip to content

Server Management

Jump to bottom
Claude edited this page Oct 9, 2026 · 15 revisions

Server Management

One shared memory server on 127.0.0.1:8765 serves every session: Claude Code, Codex, Antigravity and Claude Desktop alike. You rarely need to manage it by hand.

  • Every harness connects through kg mcp, a small stdio bridge. It starts the server when it is down and waits out restarts, so the tools stay connected through kg update or kg restart.
  • The SessionStart hooks start it too, and wait for it, so a cold start still gets its preload.
  • On Linux with a systemd user session, kg setup installs a user service that starts it at login.

Nothing stops or restarts a running server except kg itself: your own kg stop/kg restart, or kg setup and kg update when they bring it to a new version. A stopped server comes back as soon as a session or kg mcp needs it.

Commands

kg status                    # running? which version, how many sessions, from where
kg start | stop | restart    # through systemctl when the service is enabled
kg logs [-f]                 # the server log, or the journal under the service
kg doctor                    # check every piece the memory depends on
kg update                    # upgrade kg, restart the server on it, update the plugins
kg editor [stop]             # visual editor at http://localhost:8766
kg commit                    # commit the storage git repository now
kg version                   # this kg's version

kg serve runs the server in the foreground; it is what the systemd unit runs. kg mcp is the stdio bridge the harnesses launch; you don't run it yourself.

Concurrent starts are serialised, so a harness and its hook starting at the same moment share one server. A second server on the same storage directory refuses to run. A failed start records its cause in ~/.local/state/knowledge-graph/last_start_error; the hooks report that cause instead of retrying every session, and the next successful kg start or kg restart clears it.

Logs

  • Under the systemd service, the server writes to the journal. kg logs reads it there (journalctl --user -u kg-memory.service; -f follows).
  • Otherwise, a server started by kg start, kg mcp or a hook writes ~/.local/state/knowledge-graph/mcp_server.log, and kg logs tails that file.

Set KG_LOG_LEVEL=DEBUG for more detail (Configuration says where to set it).

The systemd service (Linux)

kg setup installs and enables ~/.config/systemd/user/kg-memory.service, which runs kg serve and restarts it on failure. While the service is enabled, kg start, kg stop and kg restart go through systemctl --user, and kg start also stops any stray server the service doesn't own (one started by an older plugin or by hand). Check it with systemctl --user status kg-memory and kg status.

The unit's environment is fixed when setup writes it: PATH, CODEX_HOME and every KG_* variable are copied from the environment kg setup ran in. Later changes to your shell profile don't reach it, and rerunning setup leaves a working unit as it is. To change a variable, edit the Environment= lines in the unit, then:

systemctl --user daemon-reload && kg restart

On macOS, and on Linux without a systemd user session, there is no service: the first session (or kg mcp) starts the server, and it keeps running in the background until you stop it.

kg uninstall disables and removes the service.

File locations

What Where
Memory (plain JSON) ~/.knowledge-graph/ (KG_STORAGE_ROOT), see Data and Backup
PID file, last start error, setup backups ~/.local/state/knowledge-graph/
Server log, when kg started the server ~/.local/state/knowledge-graph/mcp_server.log
Visual editor log and PID ~/.local/state/knowledge-graph/visual_editor.log, editor.pid
A server on a port other than 8765 its own port-<N>/ inside ~/.local/state/knowledge-graph/
The kg command and server code uv's tool environment (uv tool dir)
Systemd user unit (Linux) ~/.config/systemd/user/kg-memory.service

Endpoints

The server speaks MCP on / and serves a REST API for the hooks and the visual editor. The ones useful by hand:

Endpoint Purpose
POST / MCP Streamable HTTP (what kg mcp forwards to)
GET /health Health check with version and session count
GET /api/graph/read REST read (visual editor); reload=true forces a re-read from disk
GET /api/nodes/{level}/{id} Read one node (promotes an archived node to active)
GET /api/nodes/{level}/{id}/score Read-only archival score breakdown
POST /api/nodes/rename Rename a node and update every reference to it
GET /api/projects Stored project graphs, independent of any harness's history

The rest are for the hooks (session bootstrap, prompt and tool events, Antigravity's hook bridge) and the editor (node and edge create/delete, progress, session stats, and WS /ws for live updates).

Every request must carry a local Host header (localhost, 127.0.0.1 or ::1); other hosts get 421, which closes the DNS-rebinding route around browser protections. HTTP requests a browser marks as cross-site, or that carry a non-local Origin, are refused, and WebSocket upgrades need a local or absent Origin. There is no authentication beyond that: the trust boundary is the processes on your machine. See SECURITY.md.

Troubleshooting

  • Start with kg doctor. It names each broken piece and the fix; kg setup applies the fixes it can.
  • Tools offline. kg mcp starts the server and retries on its own, so offline tools mean a start that fails. kg start prints why, and kg logs shows the rest.
  • The session says the last start failed. The hooks found last_start_error and stopped retrying. Fix the cause it names, then kg start.
  • A KG PREFLIGHT: line in the log names an incompatible dependency or a second server on the same storage. For a dependency, run kg update or uv tool install --reinstall kg-memory; the same fixes a tool environment broken by an OS Python upgrade.
  • kg status shows another version than kg version. The running server predates the installed kg: kg restart.
  • Port 8765 is taken by another program. Set KG_HTTP_PORT for the server and every client (Configuration).
  • A variable you set has no effect. Under the systemd service, set it in the unit (above), not your shell profile.
  • Graph looks stale after editing the JSON by hand while the server runs: the server keeps graphs in memory. curl -s 'http://127.0.0.1:8765/api/graph/read?reload=true&project_path=<root>' forces a re-read from disk. Safer still, kg stop before editing and kg start after (Data and Backup).
  • A harness still on a 0.11 plugin connects by URL and needs /mcp → Reconnect (Claude Code) or a new session (Codex) after a restart; kg update moves it to kg mcp.

If the memory itself is lost or damaged, restore from the rolling backup or git history first (Data and Backup). Without backups, /kg-scout can rebuild lessons from your Claude Code, Codex and Antigravity session history (Skills Reference).

Agents have the same recipes in the kg-ops skill: "run /kg-ops and fix the memory server" is a complete instruction.

Clone this wiki locally