Reference

CLI reference

Every gmem command and flag, client environment variables, exit codes.

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, every greatmemory.toml key, and the feature toggles are in the Configuration reference.

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).

The three feature toggles override greatmemory.toml and their GM_* env vars (GM_REFLECTION, GM_USEFULNESS, GM_TRUST); passing both --enable-X and --disable-X is an error. See the Configuration reference for the full toggle matrix.

gmem serve
gmem serve --host 0.0.0.0 --port 8080 --data-dir /var/lib/greatmemory
gmem serve --disable-trust --disable-reflection   # ingest-only, no LLM cards, no quarantine

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?"
gmem search "where does the user live?" --as-of 2022-01-01T00:00:00Z

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 timeline

Show the bi-temporal history of an entity in the knowledge graph: every fact ever recorded for a subject, oldest first, with its validity interval. A leading * marks the fact that is still true now. Unlike facts list (which shows only the current value), timeline shows how a fact changed over time - superseded values are preserved, not overwritten.

gmem timeline user
gmem timeline user --predicate lives_in --space work

  user lives_in London  [2020-01-01 → 2026-01-01]
* user lives_in Dubai   [2026-01-01 → now]

Like facts list, the graph is populated from LLM fact extraction, so it needs GM_LLM configured on the server to have data.

gmem episode

Episodic memory: group related events under a named episode (a project, an incident, a meeting) and reconstruct them later.

gmem episode create "Project Athena" --space work --summary "the Athena launch"
gmem episode add <episode-id> decision --note "Chose Postgres"
gmem episode list --space work
gmem episode show <episode-id>   # prints the episode and its events in time order

episode create prints the new episode id. episode show reconstructs it - the episode name, summary, and every event in time order.

gmem graph migrate

Move the entire knowledge graph (all spaces, full history) between backends - connects to both databases directly and copies verbatim. The destination should be empty. Values are backend URLs or paths (mysql://…, postgres://…, a sqlite file, or :memory:).

gmem graph migrate --from ./.greatmemory/greatmemory.db --to mysql://user:pass@host/gm

gmem card

Agentic memory cards (A-MEM): atomic notes that auto-link to cards sharing keywords or tags, forming a navigable knowledge web.

gmem card create "Postgres tuning" --summary "Bump shared_buffers to 25% RAM" \
  --keyword postgres --keyword tuning --tag db
gmem card list --space work
gmem card show <card-id>   # prints the card and its linked related cards

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
curl -X DELETE http://127.0.0.1:7437/v1/memories/<id>  # remove by id over REST
gmem facts list             # inspect distilled facts
gmem timeline user          # bi-temporal history of an entity
gmem episode list           # episodic memory: named event bundles
gmem card list              # agentic memory cards (A-MEM)
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