Service Management

Service Management

Recollectium can run as a managed service for adapters and clients, or as a foreground process for development.

Service types

• api: local HTTP JSON API with memory, workspace, embedding, health, version, and capability operations.
• mcp: MCP HTTP server using SSE transport.

Only one managed service runs at a time.

Start

recollectium service start api
recollectium service start mcp

Example success output:

{"endpoint":"http://127.0.0.1:8765","pid":12345,"status":"started","type":"api"}

Status

recollectium service status

Running:

{"endpoint":"http://127.0.0.1:8765","pid":12345,"running":true,"type":"api"}

Not running:

{"running":false}

Discovery

recollectium service discover

Adapters should use discovery instead of hardcoding PID files, runtime paths, host, port, or service type.

When a managed service is running, discovery returns service type, endpoint, API prefix, health URL, version URL, capabilities URL, PID path, discovery file path, runtime directory, config path, and version information.

When no service is running, discovery exits 1 and prints status: "not_running" output to stdout. Use recollectium service discover --json for adapter or script calls.

Stop

recollectium service stop

Recollectium sends SIGTERM and waits for graceful exit. If needed, it falls back to SIGKILL.

Restart

recollectium service restart
recollectium service restart --type api
recollectium service restart --type mcp

Use --type when no running service or stale PID metadata can identify the previous type.

Foreground dev serve mode

recollectium dev serve --host 127.0.0.1 --port 8765

dev serve is useful for development and debugging. It blocks until interrupted.

Runtime files

The service manager writes runtime metadata under the configured runtime directory. It includes a PID file and service-discovery.json.

Service stdout and stderr go to service logs in the logs directory. See Logs.

Security reminder

The v1 API and MCP services are unauthenticated. Keep them bound to localhost unless private networking and access controls protect the endpoint.