CLI reference
The memory CLI is the primary automation surface for Memory Layer. It configures projects, runs the backend, captures work, curates memory, answers questions, manages embeddings, opens the TUI, exposes MCP, and runs evaluations.
Use command help as the final source of truth before scripting:
memory --help
memory <command> --help
memory <command> <subcommand> --helpGlobal options
| Option | Env var | Purpose |
|---|---|---|
--config <path> | MEMORY_LAYER_CONFIG | Use a specific global config file. |
--writer-id <id> | MEMORY_LAYER_WRITER_ID | Override the writer identity for captures and activity. |
--agent-id <id> | MEMORY_LAYER_WRITER_ID | Alias for --writer-id. |
Many commands also support --project <slug>, --json, or --dry-run. Prefer --json for agent automation and --dry-run before commands that write config, memory, history, embeddings, or repo metadata.
Command groups
| Group | Commands | Use when |
|---|---|---|
| Setup and bootstrap | wizard, init, upgrade, completion, dev | Installing, configuring, refreshing repo-local integration files, and setting up shell completion. |
| Service and health | service, status, doctor, health, stats, automation | Starting the backend, diagnosing config, checking API health, and inspecting automation queues. |
| Query and briefings | query, resume, up-to-speed, activities, history, verify-provenance | Asking project questions, resuming work, inspecting activity, and proving memory sources still exist. |
| Capture and curation | remember, capture, scan, curate, proposals, archive, prune-history, checkpoint | Writing project memory, reviewing replacements, pruning history, and tracking plan execution. |
| Repository, evidence, and search | commits, repo, graph, embeddings, bundle | Importing code/history evidence, maintaining search indexes, and exporting project memory. |
| Integrations and evals | tui, watcher, mcp, eval | Opening UIs, attaching agents, serving MCP, and measuring memory quality. |
Agent contract
Agents should follow a repeatable command pattern:
- Run
memory querybefore answering project-specific questions. - Run
memory resumeafter interruptions or context loss. - Use
memory checkpoint start-executionwhen beginning approved plans. - Use
memory rememberafter meaningful completed work. - Use
memory status,memory doctor, andmemory healthbefore blaming retrieval or the TUI.
Read/write guide
| Kind | Mostly read-only | Writes local or service state |
|---|---|---|
| Setup | completion, most dev inspection | wizard, init, upgrade, some dev scaffolding |
| Service | status, doctor, health, stats | service enable, service disable, service restart-all, automation flushes |
| Query | query, resume, up-to-speed, activities, history, verify-provenance | Query/activity logging may write audit events when the service is running. |
| Memory | proposals list, scan --dry-run | remember, capture, curate, scan, proposal approval/rejection, archive, prune-history |
| Evidence | repo inspect, graph inspect, embeddings status | commit import, repo indexing, graph extraction, embedding rebuilds, bundle import |
| Integrations | mcp status, watcher status, eval compare | watcher start/stop, MCP HTTP service config, eval run artifacts |
Project resolution
Commands that operate on memory need a project slug. In normal repo-local use, the CLI can read .mem/project.toml; in automation, pass --project <slug> explicitly so the command does not depend on the current working directory.
memory query --project memory --question "What changed in the docs site?"
memory status --project memory --jsonNext
Use Setup and bootstrap for installation flows or Query and briefings for day-to-day agent use.