Skip to content

direct-server-systemd.md

Latest commit

 

History

History
161 lines (120 loc) · 4.68 KB

direct-server-systemd.md

File metadata and controls

161 lines (120 loc) · 4.68 KB
Raw

Direct server mode with systemd

This guide is for Linux users who want the Rust server to run as a long-lived local service. MCP bridges can reach it over a Unix socket, while REST clients remain available over HTTP.

This is optional. The default npx -y @shodh/memory-mcp setup is still the quickest path for Claude Code, Cursor, Claude Desktop, and other MCP clients.

When to use this

Use direct server mode when you want:

  • A single backend process supervised by systemd.
  • Stable health checks and logs outside of any one MCP client.
  • REST clients, shell helpers, or multiple local tools to share the same server.
  • The backend lifecycle to be independent from the MCP bridge lifecycle.

Command roles

  • shodh server starts the HTTP API and, by default, the local IPC listener.
  • shodh serve starts the MCP stdio bridge, preferring local IPC and falling back to SHODH_API_URL when IPC is unavailable.
  • @shodh/memory-mcp is the npm MCP wrapper used by MCP clients.

Direct server mode runs shodh server separately. MCP and REST clients can then connect to that server instead of owning the backend process themselves.

Create a user systemd service

First find the installed binary path:

command -v shodh

Create ~/.config/systemd/user/shodh-memory.service:

[Unit]
Description=Shodh Memory server
After=network.target

[Service]
Type=simple
Environment=SHODH_HOST=127.0.0.1
Environment=SHODH_PORT=3030
Environment=SHODH_MEMORY_PATH=%h/.local/share/shodh-memory
Environment=SHODH_IPC_ENABLED=true
Environment=SHODH_IPC_ENDPOINT=%h/.local/share/shodh/shodh-memory.sock
Environment=SHODH_IPC_REQUIRED=true
Environment=SHODH_DEV_API_KEY=local-dev-key
ExecStart=%h/.cargo/bin/shodh server
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

Replace ExecStart=%h/.cargo/bin/shodh server with the path returned by command -v shodh if your binary is installed somewhere else.

Start the service:

systemctl --user daemon-reload
systemctl --user enable --now shodh-memory.service
systemctl --user status shodh-memory.service

Check the server directly:

curl -sS http://127.0.0.1:3030/health

Also check the journal for Local IPC ready at .... With SHODH_IPC_REQUIRED=true, a socket bind failure makes service activation fail; without it, the server logs the failure and continues HTTP-only.

View logs:

journalctl --user -u shodh-memory.service -f

Restart after configuration changes:

systemctl --user restart shodh-memory.service

MCP client example

If you want an MCP client to use this separately supervised server, point the native MCP bridge at the same Unix socket:

{
  "mcpServers": {
    "shodh-memory": {
      "command": "shodh",
      "args": ["serve"],
      "env": {
        "SHODH_IPC_ENDPOINT": "/home/you/.local/share/shodh/shodh-memory.sock",
        "SHODH_API_URL": "http://127.0.0.1:3030",
        "SHODH_API_KEY": "local-dev-key",
        "SHODH_USER_ID": "local-agent"
      }
    }
  }
}

Use the full path to shodh if your MCP client does not inherit your shell PATH. Replace /home/you with the service user's home directory and keep the endpoint identical to the service value. The socket parent is mode 0700 and the socket is mode 0600; Shodh refuses unsafe, foreign-owned, or live replacement endpoints.

User IDs

The user_id in API request bodies, and the SHODH_USER_ID environment variable used by MCP and hook commands, identify the memory namespace for the calling user or agent. This value is not an API key, password, or authentication token.

Choose a stable user_id such as local-agent, alice, or robot-1, and keep using the same value for that client if you want it to see the same memories.

REST client example

All /api/* endpoints require the X-API-Key header.

export SHODH_API_URL=http://127.0.0.1:3030
export SHODH_API_KEY=local-dev-key
export SHODH_USER_ID=local-agent

curl -sS -X POST "$SHODH_API_URL/api/remember" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $SHODH_API_KEY" \
  -d "{\"user_id\":\"$SHODH_USER_ID\",\"content\":\"Prefer direct server mode\",\"memory_type\":\"Decision\"}"

curl -sS -X POST "$SHODH_API_URL/api/recall" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $SHODH_API_KEY" \
  -d "{\"user_id\":\"$SHODH_USER_ID\",\"query\":\"direct server mode\"}"

Production notes

For local-only use, keep SHODH_HOST=127.0.0.1.

Before binding to 0.0.0.0 or exposing the service to another machine:

  • Use production mode with SHODH_ENV=production.
  • Set strong values in SHODH_API_KEYS.
  • Put the service behind TLS and normal network access controls.
  • Avoid using development keys such as local-dev-key.