npx @agentmemory/agentmemory [command] [options]
| Command | What it does |
|---|---|
| (default) | Start the worker, the pinned iii-engine, REST on 3111, and the viewer on 3113 |
init | Copy the bundled .env.example to ~/.agentmemory/.env if absent |
connect [agent] | Wire agentmemory into an installed agent. No argument opens an interactive picker. --all wires every detected agent, --dry-run previews, --force re-installs, --with-hooks adds native hooks |
status | Show connection status, memory count, flags, and health |
doctor | Interactive diagnostic and fixer. --all applies every fix without prompting (CI), --dry-run shows what each fix would do |
remove | Cleanly uninstall (pidfile, state, .env, binaries). --force skips confirmations, --keep-data keeps memory data |
demo [--serve] | Seed sample sessions and show recall in action. --serve boots the server, runs the demo, and stops it in one command |
upgrade | Upgrade local deps and the iii runtime, best effort |
stop [--force] | Stop the iii-engine this CLI started. --force bypasses the Docker-heuristic guard and signals whatever the pidfile and lsof report on the REST port |
mcp | Start the standalone MCP shim for MCP-only clients; REST stays at 3111 |
import-jsonl [path] | Import Claude Code JSONL transcripts (default ~/.claude/projects). --max-files <N> overrides the scan cap (default 200, max 1000) |
Global options
| Option | Effect |
|---|---|
--verbose, -v | Show engine stderr, boot log, and diagnostic info |
--reset | Wipe ~/.agentmemory/preferences.json and re-run onboarding |
--tools all|core | MCP tool visibility: all 54 tools (default) or the 8 core essentials |
--no-engine | Skip auto-starting iii-engine |
--port <N> | Override the REST port. Streams (N+1), viewer (N+2), and engine (N+46023) derive from it, so one flag relocates the whole quartet |
--instance <N> | Shortcut for --port 3111 + N*100 to run daemons side by side. --instance 1 gives 3211/3212/3213/49234. Max N is 50 |
--data-dir <path> | Store iii-engine state outside the current repo |
Environment
| Variable | Effect |
|---|---|
AGENTMEMORY_URL | Full REST base URL, honored by status, doctor, and the MCP shim |
AGENTMEMORY_DATA_DIR | State directory fallback when --data-dir is not set |
AGENTMEMORY_USE_DOCKER=1 | Prefer the bundled docker-compose path over the native iii-engine binary on first run |
AGENTMEMORY_III_VERSION | Override the pinned iii-engine version (0.11.2) |
AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS | Window for the smart-search follow-up diagnostic (default 30) |