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 --json

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

When a managed service is running, service discover --json returns the compact adapter payload with status, running, type, endpoint, and pid, plus the validation URLs adapters use to confirm the service is healthy. Use --verbose when you need full paths or version metadata.

When no service is running, compact --json discovery exits 1 and prints status: "not_running" output to stdout. Use recollectium service discover --json for adapter or script calls, and add --verbose when you need the full fields.

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.