Skip to content

service.md

Latest commit

 

History

History
97 lines (62 loc) · 3.67 KB

service.md

File metadata and controls

97 lines (62 loc) · 3.67 KB

memory service

Use the service commands to enable, start, and inspect the shared backend service installed on your machine.

Table of Contents

What It Controls

These commands manage the installed shared memory service backend.

They are for the normal packaged setup, not for source-level development runs like cargo run --bin memory -- service run, which activate a fully isolated dev profile on different ports. See Dev Stack vs Installed Stack for the full contract.

Common Commands

Enable or start the service:

memory service enable

Preview the service action without changing the machine:

memory service enable --dry-run
memory service disable --dry-run
memory service ensure-api-token --rotate-placeholder --dry-run
memory service restart-all --dry-run --json

This command also provisions the shared service API token automatically if it is missing or still set to the old development placeholder.

Check service status:

memory service status

Rotate an old placeholder token manually:

memory service ensure-api-token --rotate-placeholder

Restart active services after an install or upgrade:

memory service restart-all --mark-tui-restart --json

restart-all restarts only services that are already active or loaded. It does not start services that the user intentionally stopped. On Linux it checks the system backend service and active user watcher services. When run as root during a package install, it also checks logged-in user systemd sessions under /run/user/*. On macOS it checks loaded Memory Layer LaunchAgents.

Installers pass --mark-tui-restart so a TUI that is already open can show restart in red in the bottom status bar. Restarting the TUI is still a user action; the installer does not kill the running terminal UI.

Health checks from the client side:

memory health
memory doctor

API Token Security

The HTTP API does not trust Origin or Referer headers as authentication, even when they point at localhost. API clients must send the configured service token with x-api-token. The bundled same-origin web UI bootstraps that token from the service and attaches it to its own API requests.

Platform Notes

On macOS, memory service enable manages the LaunchAgent.

On Linux, the packaged service is usually managed with:

sudo systemctl enable --now memory-layer.service
memory service restart-all --mark-tui-restart

Use systemctl directly only when debugging a specific unit.

Development And Source Use

When working from source, cargo run --bin memory -- service run starts a dev backend that is fully isolated from any installed service on the same machine: different HTTP port (4250 vs 4040), different Cap'n Proto port (4251 vs 4041), and its own Cap'n Proto Unix socket under the user-local project runtime directory. The dev profile ignores the installed global config entirely.

Bootstrap is one-time per checkout:

cargo run --bin memory -- init
cargo run --bin memory -- dev init --copy-from-global
cargo run --bin memory -- service run

--copy-from-global lifts the database URL and LLM/embedding endpoints out of the installed config into the dev overlay. Without it (and without a TTY) you will need to populate those sections in the user-local project config.dev.toml by hand.

For the full isolation contract, override flags, verification steps, and troubleshooting, see Dev Stack vs Installed Stack.