CLI reference

One binary, gmem, contains the server, the MCP server, and a client CLI. serve and mcp run the engine in-process; add, search, and facts talk to a running server over HTTP. status, backup, and restore open the database directly — they work with no server running.

Configuration precedence

Everything the binary does is configured in layers; later layers win:

CLI flags  >  GM_* environment variables  >  greatmemory.toml  >  built-in defaults

greatmemory.toml is read from the current directory by default (skipped silently when absent); --config <path> selects an explicit file, which must exist. Unknown keys are an error, so typos fail fast. The full GM_* table is in the server quickstart and the deployment pages.

Client environment

The client commands use two variables of their own:

GM_URL=https://memory.example.com GM_API_KEY=gm_... gmem status

Exit codes

gmem exits 0 on success and non-zero on any failure — unreachable server, an error response from the API, or invalid arguments — with a human-readable message on stderr. The most common failure from client commands is "is the server running?": start gmem serve, or set GM_URL if it listens elsewhere.

Commands

gmem serve

Run the HTTP server (REST /v1 + streamable-HTTP MCP at /mcp).

gmem serve
gmem serve --host 0.0.0.0 --port 8080 --data-dir /var/lib/greatmemory

On first run the embedding model (a few tens of MB) is downloaded into <data_dir>/models; after that the server runs fully offline.

gmem mcp

Run the MCP server on stdio. Self-contained: it opens the database directly from the data dir — no gmem serve needed. Logs go to stderr; stdout is reserved for MCP framing.

gmem mcp --data-dir ~/.greatmemory

Agents may launch this process from any working directory — prefer an absolute --data-dir (or GM_DATA_DIR) so every client sees the same memories. Tool reference: MCP server.

gmem add

Store a memory on the server.

gmem add "Venkatesh prefers Rust for backend services."
gmem add "Acme renewal is due March 1st." --space work

Prints the new memory's id. Ingestion is asynchronous: the server replies immediately and chunks/embeds in the background, so a memory becomes searchable a moment after the command returns.

gmem search

Hybrid search (vector + BM25 + facts, fused with reciprocal rank fusion, boosted by recency).

gmem search "what database does staging use?"

0.016  The staging database runs Postgres 17 with pgvector.

gmem search "user preferences" --mode context

recall prints score-prefixed chunks; context prints a single assembled block — facts first, then relevant memories — suitable for pasting straight into a prompt.

gmem facts list

List the active facts the configured LLM has distilled (subject / predicate / object with confidence). Empty unless GM_LLM is configured on the server — without an LLM you still get full hybrid search, just no extracted facts.

gmem facts list

A new fact that contradicts an old one (same subject and predicate, different object) supersedes it automatically; only active facts are listed.

gmem status

Store statistics and memory usage. By default it opens the database directly — no server required — and reports counts, on-disk size, and efficiency:

gmem status

  greatmemory  local store · sqlite

  On disk
    database  562.7 KB

  Store
    documents                3
    chunks                   3
    active facts             0

  Efficiency
    chunks / doc           1.0
    disk / chunk      187.6 KB

When GM_URL points at a running server, status switches to a live view that adds the server process's resident memory (RSS) drawn against the 1 GB design ceiling — the live proof of the bounded-memory claim. The same numbers are available to monitoring via GET /v1/stats.

gmem status --watch            # live dashboard, redraws every 2s
gmem status -w -n 1            # refresh once a second
GM_URL=https://memory.example.com gmem status   # remote, with live RSS

gmem backup

Write a portable snapshot of the database.

• SQLite: a consistent single-file copy (via VACUUM INTO) — safe to run while the server is up, and defragmented with no -wal/-shm sidecars.
• Postgres: runs pg_dump (custom format) when it's installed; otherwise prints your cloud provider's managed-backup steps plus the exact pg_dump command to run yourself.

gmem backup                          # → greatmemory-<timestamp>.db (or .dump)
gmem backup snapshots/before-upgrade.db

The destination must not already exist. Default location and backend come from the same config layers as everything else (GM_DATA_DIR / GM_DB).

gmem restore

Replace the current database from a backup. This overwrites data, so it requires --force — and you should stop any running server first.

• SQLite: the backup is integrity-checked and confirmed to be a greatmemory database before it replaces the live file; stale WAL sidecars are cleared.
• Postgres: runs pg_restore --clean when installed; otherwise prints managed point-in-time-restore guidance and the manual command.

gmem restore greatmemory-1718409600.db --force

Without --force, restore refuses and tells you what it would overwrite.

Quick reference

gmem serve                  # run the server (loopback + SQLite by default)
gmem mcp                    # MCP on stdio (no server needed)
gmem add "text" --space s   # store
gmem search "query"         # recall; --mode context for a block
gmem facts list             # inspect distilled facts
gmem status                 # counts + disk size (no server); live RSS when GM_URL set
gmem status --watch         # live dashboard until Ctrl-C
gmem backup [path]          # snapshot the database
gmem restore <path> --force # replace the database from a backup