Mem0 CLI Command Reference

Complete reference for every command, argument, flag, and output mode in the mem0 CLI. Both the Node.js (@mem0/cli) and Python (mem0-cli) implementations are identical in behavior.

Global Options

These options are available on every command:

Commands

mem0 init

Interactive setup wizard. Configures API key and default user ID.

Usage: mem0 init [OPTIONS]

Options:

Behavior:

• If ~/.mem0/config.json already exists with an API key, warns and asks for confirmation (or errors in non-TTY unless --force is set).
• Email login flow (--email): sends a 6-digit code to the email via POST /api/v1/auth/email_code/. If --code is also given, verifies immediately. On success, saves API key, org_id, and project_id. Cannot be combined with --api-key.
• API key flow: if both --api-key and --user-id are given, runs fully non-interactively. Otherwise prompts for missing values.
• In non-TTY without sufficient flags, prints a usage hint and exits with error.

Examples:

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

mem0 add

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

Usage: mem0 add [text] [OPTIONS]

Arguments:

Options:

Input priority: --file > --messages > text argument > stdin (if piped and no text).

Text content is wrapped as [{"role": "user", "content": "<text>"}] before sending to the API. Messages from --messages or --file are sent as-is.

Output events: The API returns results with an event field per memory:

Examples:

mem0 add "I prefer dark mode" --user-id alice
mem0 add "allergic to nuts" -u alice -m '{"source":"onboarding"}'
mem0 add --messages '[{"role":"user","content":"I like Python"}]' -u alice
mem0 add --file conversation.json -u alice -o json
echo "I prefer dark mode" | mem0 add -u alice
mem0 add "temporary note" -u alice --expires 2025-12-31
mem0 add "important fact" -u alice --immutable
mem0 add "uses vim" -u alice --categories "tools,preferences"

mem0 search

Search memories by semantic query.

Usage: mem0 search <query> [OPTIONS]

Arguments:

Options:

Examples:

mem0 search "preferences" --user-id alice
mem0 search "tools" -u alice -o json -k 5
mem0 search "dietary restrictions" -u alice --threshold 0.5
mem0 search "project setup" -u alice --rerank
mem0 search "preferences" -u alice --filter '{"categories":{"contains":"food"}}'
echo "preferences" | mem0 search -u alice

mem0 get

Get a specific memory by ID.

Usage: mem0 get <memory_id> [OPTIONS]

Arguments:

Options:

Examples:

mem0 get abc-123-def-456
mem0 get abc-123-def-456 -o json

mem0 list

List memories with optional filters and pagination.

Usage: mem0 list [OPTIONS]

Options:

Examples:

mem0 list -u alice
mem0 list --category prefs --after 2024-01-01 -o json
mem0 list -u alice --page 2 --page-size 50
mem0 list --before 2024-06-01 -o table

mem0 update

Update a memory's text or metadata.

Usage: mem0 update <memory_id> [text] [OPTIONS]

Arguments:

Options:

Examples:

mem0 update abc-123 "new text"
mem0 update abc-123 --metadata '{"priority":"high"}'
mem0 update abc-123 "new text" -m '{"priority":"high"}'
echo "new text" | mem0 update abc-123

mem0 delete

Delete a memory, all memories matching a scope, or an entity. This command has three mutually exclusive modes.

Usage: mem0 delete [memory_id] [OPTIONS]

Arguments:

Options:

Three modes (mutually exclusive):

1. Single memory: mem0 delete <memory_id> -- deletes one memory by its UUID.
2. Bulk delete: mem0 delete --all [scope flags] -- deletes all memories matching the scope. Add --project to wipe all memories project-wide (sends wildcard * entity IDs).
3. Entity cascade: mem0 delete --entity [scope flags] -- deletes the entity itself AND all its memories.

You cannot combine <memory_id> with --all or --entity, and you cannot combine --all with --entity. If none of these are provided, the command prints a usage hint and exits with an error.

Dry-run behavior:

• Single: fetches the memory, displays it, prints "No changes made."
• --all: lists matching memories with count, prints "No changes made."
• --entity: shows the affected scope without deleting.

Confirmation: Without --force, all destructive modes prompt [y/N]. With --all --project, the prompt explicitly warns about project-wide deletion.

--all --project behavior: Sends DELETE /v1/memories/ with user_id=*&agent_id=*&app_id=*&run_id=*. The API returns an async response. The CLI prints "Deletion started. Memories will be removed in the background."

Examples:

mem0 delete abc-123-def-456
mem0 delete --all -u alice --force
mem0 delete --all --project --force
mem0 delete --entity -u alice --force
mem0 delete abc-123 --dry-run
mem0 delete --all -u alice --dry-run

mem0 import

Import memories from a JSON file.

Usage: mem0 import <file_path> [OPTIONS]

Arguments:

Options:

File format: A JSON array (or single object) where each item has a memory, text, or content field for the text, plus optional user_id, agent_id, and metadata fields. CLI-provided --user-id and --agent-id override per-item values.

Import format example:

[
  { "memory": "Prefers dark mode", "user_id": "alice" },
  { "text": "Allergic to nuts", "metadata": { "source": "intake" } },
  { "content": "Uses VS Code" }
]

Behavior: Iterates through items, calling the add API for each. Displays progress and reports added and failed counts on completion.

Examples:

mem0 import memories.json --user-id alice
mem0 import data.json -u alice -o json

mem0 config show

Display current configuration with secrets redacted.

Usage: mem0 config show [OPTIONS]

Options:

Examples:

mem0 config show
mem0 config show -o json

mem0 config get

Get a single configuration value.

Usage: mem0 config get <key>

Arguments:

Valid keys: platform.api_key, platform.base_url, defaults.user_id, defaults.agent_id, defaults.app_id, defaults.run_id.

API key values are always redacted in output.

Examples:

mem0 config get platform.api_key
mem0 config get defaults.user_id

mem0 config set

Set a configuration value.

Usage: mem0 config set <key> <value>

Arguments:

Type coercion: Boolean fields accept true/1/yes (case-insensitive) as true, anything else as false.

Examples:

mem0 config set defaults.user_id alice
mem0 config set platform.base_url https://api.mem0.ai

mem0 config clear

Clear the configuration file. Removes ~/.mem0/config.json.

Usage: mem0 config clear

Examples:

mem0 config clear

mem0 entity list

List all entities of a given type.

Usage: mem0 entity list <entity_type> [OPTIONS]

Arguments:

Options:

Behavior: Calls GET /v1/entities/ (returns all types), then filters client-side using the type map (users -> user, agents -> agent, etc.). Displays a table with "Name / ID" and "Created" columns.

Examples:

mem0 entity list users
mem0 entity list agents -o json

mem0 entity delete

Delete an entity and ALL its memories (cascade).

Usage: mem0 entity delete [OPTIONS]

Options:

At least one entity ID is required. Errors if none provided.

Examples:

mem0 entity delete --user-id alice --force
mem0 entity delete --user-id alice --dry-run
mem0 entity delete --agent-id bot1 --force

mem0 event list

List recent background processing events.

Usage: mem0 event list [OPTIONS]

Options:

Behavior: Fetches all events for the project. Displays a table with columns: Event ID (first 8 chars), Type, Status (color-coded), Latency, Created. Status values: PENDING, SUCCEEDED, FAILED, PROCESSING.

Examples:

mem0 event list
mem0 event list --output json

mem0 event status

Get the status and results of a specific background event.

Usage: mem0 event status <event_id> [OPTIONS]

Arguments:

Options:

Behavior: Fetches the event by ID. Displays: Event ID, Type, Status, Latency, Created, Updated, and a list of result memories.

Examples:

mem0 event status evt-abc-123
mem0 event status evt-abc-123 --output json

mem0 status

Check connectivity and authentication.

Usage: mem0 status [OPTIONS]

Options:

Behavior: Calls GET /v1/ping/ to validate connectivity and authentication. Displays connection status, backend type, and base URL.

JSON output:

{
  "status": "success",
  "command": "status",
  "duration_ms": 112,
  "data": {
    "connected": true,
    "backend": "platform",
    "base_url": "https://api.mem0.ai"
  }
}

Examples:

mem0 status
mem0 status -o json

Agent Mode Envelope Format

When --json or --agent is passed, every command wraps its output in a consistent JSON envelope on stdout:

{
  "status": "success",
  "command": "<command_name>",
  "duration_ms": 245,
  "scope": { "user_id": "alice", "agent_id": null },
  "count": 10,
  "error": null,
  "data": { ... }
}

Fields:

• status: "success" or "error".
• command: The command name (e.g. "search", "add", "list").
• duration_ms: Elapsed time in milliseconds (optional).
• scope: Active entity scope, omitted if empty (optional).
• count: Number of results, where applicable (optional).
• error: Error message string, or null on success.
• data: Command-specific response data, or null on error.

Sanitized data fields per command in agent mode:

Error envelope:

{
  "status": "error",
  "command": "search",
  "error": "Authentication failed. Your API key may be invalid or expired.",
  "data": null
}

Entity ID Resolution

Rule: If any explicit entity ID is provided via CLI flags (--user-id, --agent-id, --app-id, --run-id), the CLI uses only the explicitly provided IDs. It does NOT mix in defaults from config for the other entity types.

If no explicit IDs are given, all configured defaults from config file and env vars apply.

Rationale: If a user passes --user-id alice and the config also has agent_id=bot1, they want only Alice's memories -- not the intersection of Alice AND bot1.

if any(user_id, agent_id, app_id, run_id) were passed as flags:
    use only the explicitly provided IDs (others = null)
else:
    use all configured defaults

This applies to commands with resolveIds: true: add, search, list, delete, import.

Filter Building

For search and list, entity IDs and additional filters are composed into the API filter structure:

1. If the user provides a pre-built filter via --filter containing AND or OR keys, it is passed through to the API as-is.
2. Otherwise, the CLI builds an array of AND conditions:
   • Each entity ID becomes a condition: {"user_id": "alice"}, etc.
   • Category filters: {"categories": {"contains": "<category>"}}.
   • Date filters: {"created_at": {"gte": "YYYY-MM-DD"}} and/or {"created_at": {"lte": "YYYY-MM-DD"}}.
3. If exactly 1 condition: sent as a single object (no wrapping).
4. If 2+ conditions: wrapped as {"AND": [condition1, condition2, ...]}.
5. If 0 conditions: no filter sent.

Output Mode Support Matrix

All commands additionally support agent mode (--json/--agent) which overrides the output format with the JSON envelope.