agentmemory CLI is the primary way to manage the memory server, connect agents, and inspect memory state. Every command runs as agentmemory <command> (or npx @agentmemory/agentmemory <command> before a global install).
Global Options
These flags work with any command, including the default start command.Commands
agentmemory (start)
Starts the memory server. On first run, agentmemory auto-installs the pinned iii-engine runtime if it isn’t already present. Once the server is ready, agentmemory prints the REST API and viewer URLs so you can confirm everything is running.
Run
agentmemory connect <agent> in a separate terminal after the server is up to wire your coding agent into the running instance.agentmemory init
Creates ~/.agentmemory/.env from the bundled default template. Safe to re-run — if the file already exists it is left untouched and you are shown a diff hint so you can compare against the latest template.
init, open ~/.agentmemory/.env in your editor, uncomment your LLM provider key, and restart agentmemory.
agentmemory connect [agent]
Wires Agent Memory into an installed coding agent by writing the MCP server configuration into the agent’s settings file. Run without an argument for an interactive picker that shows all detected agents on your machine.
Supported agents: claude-code, cursor, copilot-cli, codex, gemini-cli, cline, zed, warp, continue, openclaw, hermes, pi, openhuman, droid, kiro, qwen, antigravity
agentmemory status
Shows a real-time snapshot of your running memory server: session count, observation count, memory count, knowledge graph stats (nodes and edges), active feature flags, estimated token savings, and circuit breaker state.
If the server is not running,
status exits with an error and prints the start command.agentmemory doctor
An interactive diagnostic tool that checks for common issues — missing provider keys, unreachable viewer, engine version mismatches, and more — and offers to fix each one in place.
Interactive keys:
agentmemory demo [--serve]
Seeds three realistic sample sessions (JWT auth setup, database migration debugging, rate limiting) and runs smart-search queries against them to demonstrate semantic recall. The demo shows how a query like “database performance optimization” surfaces the N+1 query fix — something keyword matching alone cannot do.
curl command to delete the seeded demo data.
agentmemory upgrade
Upgrades local npm dependencies and the pinned iii-engine binary to the latest compatible version. The command detects whether you are using pnpm or npm and runs the appropriate install command, then prompts you to re-run the iii-engine installer.
agentmemory stop [--force]
Gracefully stops the running agentmemory worker (flushing its BM25/vector index to disk first) and then stops the iii-engine process. Use --force to bypass the Docker-heuristic guard and signal whatever lsof reports on the REST port — useful when the engine was started natively but the state file is missing.
Memories are always persisted to disk before the worker exits. You can restart safely at any time with
agentmemory.agentmemory remove
Cleanly uninstalls Agent Memory. Builds a destruction plan (pidfiles, state files, .env, iii-engine binary, connect backups) and shows it before asking for confirmation. Data in ~/.agentmemory/ is included in the plan unless you pass --keep-data.
agentmemory mcp
Starts the standalone MCP shim without launching the full iii-engine. The REST API remains available at :3111. Use this for minimal deployments or MCP-only clients (Cursor, Gemini CLI, etc.) that do not need the full engine stack.
The standalone MCP shim uses a local fallback store at
~/.agentmemory/standalone.json when the main server is unreachable. Set STANDALONE_PERSIST_PATH in your .env to change this location.agentmemory import-jsonl [path]
Imports Claude Code JSONL session transcripts into Agent Memory so you can search and recall past work. Defaults to scanning ~/.claude/projects/. The server must be running before you import.