CLI

The mem0 CLI lets you add, search, list, update, and delete memories directly from the terminal. It works with the Mem0 Platform API and is available as both an npm package and a Python package.

Both implementations provide identical behavior: same commands, same options, same output formats.

Running it inside an agent? Put --agent before any command to get clean JSON instead of human output. See Use with AI agents.

Installation

pip install mem0-cli

Authentication

Run the interactive setup wizard to configure your API key:

mem0 init

This prompts for your API key and a default user ID, validates the connection, and saves the configuration locally.

For CI/CD or non-interactive environments, pass both values as flags:

mem0 init --api-key m0-xxx --user-id alice

You can also set your API key via environment variable:

export MEM0_API_KEY="m0-xxx"

Quick start

# Add a memory
mem0 add "I prefer dark mode and use vim keybindings" --user-id alice

# Search memories
mem0 search "What are Alice's preferences?" --user-id alice

# List all memories for a user
mem0 list --user-id alice

# Get a specific memory
mem0 get <memory-id>

# Update a memory
mem0 update <memory-id> "I prefer light mode now"

# Delete a memory
mem0 delete <memory-id>

Commands

mem0 init

Interactive setup wizard. Prompts for your API key and default user ID.

mem0 init
mem0 init --api-key m0-xxx --user-id alice
mem0 init --email [email protected]

If an existing configuration is detected, the CLI will ask for confirmation before overwriting. Use --force to skip the prompt (useful in CI/CD pipelines).

mem0 init --api-key m0-xxx --user-id alice --force

mem0 add

Add a memory from text, a JSON messages array, a file, or stdin.

mem0 add "I prefer dark mode" --user-id alice
mem0 add --file conversation.json --user-id alice
echo "Loves hiking on weekends" | mem0 add --user-id alice

mem0 search

Search memories using natural language.

mem0 search "dietary restrictions" --user-id alice
mem0 search "preferred tools" --user-id alice --output json --top-k 5

mem0 list

List memories with optional filters and pagination.

mem0 list --user-id alice
mem0 list --user-id alice --category preferences --output json
mem0 list --user-id alice --after 2024-01-01 --page-size 50

mem0 get

Retrieve a specific memory by ID.

mem0 get 7b3c1a2e-4d5f-6789-abcd-ef0123456789
mem0 get 7b3c1a2e-4d5f-6789-abcd-ef0123456789 --output json

mem0 update

Update the text or metadata of an existing memory.

mem0 update <memory-id> "Updated preference text"
mem0 update <memory-id> --metadata '{"priority": "high"}'
echo "new text" | mem0 update <memory-id>

mem0 delete

Delete a single memory, all memories for a scope, or an entire entity.

# Delete a single memory
mem0 delete <memory-id>

# Delete all memories for a user
mem0 delete --all --user-id alice --force

# Delete all memories project-wide
mem0 delete --all --project --force

# Preview what would be deleted
mem0 delete --all --user-id alice --dry-run

mem0 import

Bulk import memories from a JSON file.

mem0 import data.json --user-id alice

The file should be a JSON array where each item has a memory (or text or content) field and optional user_id, agent_id, and metadata fields.

mem0 config

View or modify the local CLI configuration.

mem0 config show              # Display current config (secrets redacted)
mem0 config get api_key       # Get a specific value
mem0 config set user_id bob   # Set a value

mem0 entity

List or delete entities (users, agents, apps, runs).

mem0 entity list users
mem0 entity list agents --output json
mem0 entity delete --user-id alice --force

Deleting an entity removes it and every memory belonging to it. Preview first with --dry-run.

mem0 event

Inspect background processing events created by async operations (e.g. bulk deletes, large add jobs).

# List recent events
mem0 event list

# Check the status of a specific event
mem0 event status <event-id>

mem0 status

Verify your API connection and display the current project.

mem0 status

mem0 whoami

Print the identity the CLI is currently using. After mem0 init --agent, the server issues an identifier (default_user_id, for example user_a1b2c3d4e5f6) and the CLI stores it in ~/.mem0/config.json. That value is the agent's stable identity across runs, and it is the row key on the AGENTRUSH leaderboard.

Use this instead of parsing the config file by hand:

mem0 whoami
# Your AGENTRUSH identifier:  user_a1b2c3d4e5f6
# Find your row at https://mem0.ai/agentrush

No network call. The command exits with code 1 if no default_user_id is configured yet. In that case, run mem0 init --agent first.

mem0 identify

Attach an agent name to an account created with mem0 init --agent, if you did not pass --agent-caller at the time. It keeps the same API key and only fills in the name, so it is safe to run more than once. See Sign up as an agent.

mem0 help

Print the command tree. Adding --json returns the whole tree as structured data, so an agent can discover the available commands and options for itself.

Output formats

Most commands take -o, --output to control how results are displayed. Not every command accepts every format:

Passing a format a command does not accept is an error, so check the command's own flag table above.

There is no agent value for --output. Agent mode is turned on by the global --json/--agent flag placed before the command name, and it overrides --output. See Use with AI agents.

The exact JSON shape depends on the command. search returns a bare array of memories, while list returns an envelope object with the memories under data:

# search: results are the top-level array
mem0 search "user preferences" --user-id alice --output json | jq '.[].memory'

# list: results are nested under .data
mem0 list --user-id alice --output json | jq '.data[].memory'

Agent mode always returns the envelope, whichever command you run, so .data[] works everywhere:

mem0 --agent search "user preferences" --user-id alice | jq '.data[].memory'

Use with AI agents

The CLI is purpose-built for use inside AI agent tool loops. Pass --agent or --json as a global flag on any command to activate agent mode:

• Every command outputs a consistent JSON envelope: {"status", "command", "duration_ms", "scope", "count", "data"}
• The data field contains only the fields that matter: IDs, memory text, scores, categories. Noisy API fields are stripped.
• All human-readable output is suppressed: no spinners, no colors, no banners.
• Errors are returned as JSON to stdout with a non-zero exit code, so your agent can catch them the same way as successes.

# Drop --agent on any command and get clean, parseable JSON
mem0 --agent search "response preferences" --user-id user-42
mem0 --agent add "User prefers concise responses" --user-id user-42
mem0 --agent list --user-id user-42
mem0 --agent delete --all --user-id user-42 --force

{
  "status": "success",
  "command": "add",
  "duration_ms": 210,
  "data": [
    { "id": "ghi-789", "memory": "Likes concise answers", "event": "ADD" }
  ]
}

Two other agent-friendly features:

• --output json returns structured data without sanitization, useful when you want the full raw API response
• mem0 help --json returns the complete command tree as JSON, so agents can self-discover available commands and options

For non-interactive environments (CI, agent runtimes), set credentials via mem0 init --api-key m0-xxx --user-id alice --force or the MEM0_API_KEY environment variable.

Errors and exit codes

Every command exits 0 when it succeeds and 1 when it fails, so if mem0 ...; then works as you would expect in a script. In agent mode (--json or --agent), failures still print a JSON envelope to stdout alongside the non-zero exit, so you can parse successes and failures the same way.

Errors you are most likely to hit:

Run mem0 status to check whether the CLI can reach the API and which project the key belongs to. It reports the connection state, the API URL, and any error.

Environment variables

Environment variables take precedence over values in the config file, which take precedence over defaults.

Global flags

These two flags belong to mem0 itself, so they go before the command name:

The following flags are accepted by most commands, but they belong to the command, so they go after the command name:

What's next