Reference

Server command reference

The actual gm-server operational commands, plus pointers to REST/OpenAPI and MCP for memory operations.

Server command reference

The current deployable binary is gm-server. It runs the Meivo memory framework over REST and MCP and provides two operational helpers. It is not a general client CLI: memory operations such as remember, recall, timeline, episodes, and cards are performed through REST or MCP.

Configuration precedence

For settings a command accepts, later layers win:

command flags  >  GM_* environment variables  >  greatmemory.toml  >  defaults

greatmemory.toml is read from the current directory when present. --config <path> selects an explicit file, which must exist. Unknown TOML keys and invalid environment values fail fast.

`gm-server serve`

Runs the versioned REST API under /v1, the OpenAPI document at /v1/openapi.json, and streamable HTTP MCP at /mcp.

Flag	Default	Purpose
`--host`	`127.0.0.1`	Bind host
`--port`	`7437`	Bind port
`--data-dir`	`./.greatmemory`	SQLite database and embedding-model cache
`--config`	current-directory config when present	Explicit `greatmemory.toml` path
`--enable-reflection` / `--disable-reflection`	enabled	Automatic document-to-card reflection; needs an LLM to do work
`--enable-usefulness` / `--disable-usefulness`	enabled	Apply usefulness feedback as a retrieval prior
`--enable-trust` / `--disable-trust`	enabled	Apply content-aware trust gating

Each enable/disable pair is mutually exclusive. The flag overrides the matching GM_REFLECTION, GM_USEFULNESS, or GM_TRUST value.

# Engine-only local development
GM_AUDIT_MODE=standalone gm-server serve

# Network-reachable engine: set a key first
GM_API_KEYS=internal-agent:replace-with-a-secret \
  gm-server serve --host 0.0.0.0 --port 8080 \
  --data-dir /var/lib/greatmemory

# Keep raw memory/retrieval but turn off the three optional behaviors
gm-server serve \
  --disable-reflection \
  --disable-usefulness \
  --disable-trust

Without API keys, serve refuses a non-loopback bind unless the operator sets the explicit unsafe override GM_ALLOW_INSECURE=true. Do not use that override for a production endpoint.

`gm-server mcp`

Runs stdio MCP. It opens the configured store directly, so a separate HTTP server is not required.

Flag	Default	Purpose
`--data-dir`	`./.greatmemory`	Database and embedding-model cache
`--config`	current-directory config when present	Explicit `greatmemory.toml` path

GM_AUDIT_MODE=standalone \
  gm-server mcp --data-dir /absolute/path/to/.greatmemory

Logs go to stderr; stdout is reserved for MCP protocol frames. Use an absolute data directory in agent configuration so clients launched from different working directories do not open different stores.

The stdio server exposes 13 tools: remember, recall, get_context, get_profile, timeline, create_episode, add_episode_event, get_episode, list_episodes, create_card, get_card, list_cards, and forget.

See MCP reference for schemas and integration examples.

`gm-server healthcheck`

Performs the container liveness check used by the slim deployment image. It attempts a TCP connection to 127.0.0.1 on the configured port and exits 0 only when a listener accepts the connection.

Flag	Default	Purpose
`--port`	configured `GM_PORT` or `7437`	Port to probe
`--config`	current-directory config when present	Explicit config used to resolve the port

gm-server healthcheck
gm-server healthcheck --port 8080

This is a liveness probe, not an authenticated application-level test. Use GET /v1/readyz when the orchestrator also needs a storage-readiness signal.

`gm-server warmup`

Downloads and loads the default local fastembed model into <data-dir>/models, then exits. Use it while building an image or preparing an offline host so runtime startup does not need to fetch model assets.

Flag	Default	Purpose
`--data-dir`	`./.greatmemory`	Destination data directory
`--config`	current-directory config when present	Explicit config path

gm-server warmup --data-dir /opt/greatmemory/data

Warmup covers the built-in fastembed model. Any separately operated local LLM, remote embedder, container base image, or operating-system dependency needs its own preparation and supply-chain process.

Calling memory operations

Use REST from services and scripts:

# Remember
curl -sS http://127.0.0.1:7437/v1/memories \
  -H 'Content-Type: application/json' \
  -d '{"content":"The production change window is Saturday at 22:00 UTC."}'

# Recall
curl -sS http://127.0.0.1:7437/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"when is the production change window?","mode":"recall"}'

# Engine statistics
curl -sS http://127.0.0.1:7437/v1/stats

When GM_API_KEYS is configured, add:

-H 'Authorization: Bearer replace-with-a-secret'

Use MCP when an agent host supports tool discovery and calls. The REST and MCP surfaces reach the same core memory behaviors, but a direct engine call does not automatically receive the enterprise gateway's JWT/LDAP identity, ACL resolution, or guardrails.

Exit behavior

All four commands exit 0 on success and non-zero on configuration, startup, protocol, health-check, or warmup failure. Diagnostics and MCP logs are written to stderr.

Quick reference

gm-server serve        # REST + streamable HTTP MCP
gm-server mcp          # stdio MCP
gm-server healthcheck  # TCP liveness probe
gm-server warmup       # pre-stage the local embedding model