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> --help

Global 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 advisory writer label for captures and activity; authenticated principal identity is authoritative.
`--agent-id <id>`	`MEMORY_LAYER_WRITER_ID`	Alias for `--writer-id`; it changes the label, not authorization.

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 shape

Most commands follow one of three shapes:

Shape	Example	Notes
Root command with flags	`memory query --project memory --question "..."`	Common for query, scan, remember, status, doctor.
Command group with subcommand	`memory commits sync --project memory`	Common for service, watcher, repo, graph, bundle, eval, embeddings, checkpoint.
Foreground long-running command	`memory service run`	Runs until interrupted; use service managers for packaged background operation.

Command inventory

Current command inventory

This reference is checked against the CLI's visible root commands in Rust tests. Use command help for flags and subcommands.

Workflow	Commands	Use when
Start and set up	wizard, init, demo, tour	Configure Memory Layer, bootstrap a project, and try a guided example.
Use every day	remember, query, resume, tui	Capture finished work, ask cited questions, recover context, and inspect memory.
Diagnose	status, health, doctor	Check the service, project configuration, and environment health.
Capture and curate	capture, curate, scan, ingest, proposals, consolidate, structure, review, archive	Collect evidence, make it durable, and review changes to canonical memory.
Reinforce and validate	scores, validate	Inspect what stays useful and validate it against project evidence.
History and sharing	history, prune-history, verify-provenance, bundle	Inspect versions, prove sources, keep history manageable, and transfer memory.
Workflow continuity	checkpoint, activities, up-to-speed	Record execution state and prepare the next person or agent to continue.
Connect people and tools	service, auth, watcher, agent, loops, mcp, embeddings	Run the backend, manage access, connect agents, and operate integrations.
Index project evidence	commits, repo, graph	Import repository history and build code-aware retrieval evidence.
Maintain and evaluate	eval, upgrade	Measure memory quality and refresh repo-local integration files.

Show all 41 visible root commands

wizard · init · demo · tour · remember · query · resume · tui · status · health · doctor · capture · curate · scan · ingest · proposals · consolidate · structure · review · archive · scores · validate · history · prune-history · verify-provenance · bundle · checkpoint · activities · up-to-speed · service · auth · watcher · agent · loops · mcp · embeddings · commits · repo · graph · eval · upgrade

The hidden contributor utilities memory completion and memory dev remain documented in Setup and bootstrap. They are intentionally not part of the everyday root-command inventory above.

Agent contract

Agents should follow a repeatable command pattern:

Run memory query before answering project-specific questions.
Run memory resume after interruptions or context loss.
Use memory checkpoint start-execution when beginning approved plans.
Use memory remember after meaningful completed work.
Use memory status, memory doctor, and memory health before 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`	`service enable`, `service disable`, `service restart-all`, `watcher flush`
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`
Reinforcement	`scores`, `review list`	`validate`, `review apply`, `review reject`
Evidence	`repo status`, `graph status`, `embeddings list`	commit sync, repo indexing, graph extraction, embedding reindex/reembed/prune, bundle import
Integrations	`mcp status`, watcher status, `loops list`, eval compare	watcher start/stop, loop settings/runs/approvals, 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 --json

Output contracts

Commands intended for automation prefer JSON output where supported. Usage mistakes, such as missing required flags, normally exit with code 2. Operational failures normally exit non-zero and include a human-readable error on stderr.

Use memory status --project <slug> --json as the first broad diagnostic when command behavior looks wrong.

Use Setup and bootstrap for installation flows or Query and briefings for day-to-day agent use.