JDSS/mem0
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update docs: Improve getting started section (#6707)

Browse Source
This commit is contained in:
Deshraj Yadav
2026-07-31 16:09:00 -07:00
committed by GitHub
parent c2c3a12838
commit d06ea1875c
13 changed files with 334 additions and 222 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/platform/cli.mdx
+115 -95
View File
@@ -9,9 +9,7 @@ The mem0 CLI lets you add, search, list, update, and delete memories directly fr
Both implementations provide identical behavior: same commands, same options, same output formats.
<Tip>
**Built for AI agents.** Pass `--agent` (or `--json`) as a global flag on any command to get structured JSON output optimized for programmatic consumption: sanitized fields, no colors or spinners, and errors as JSON too. Drop it into any agent tool loop with zero extra parsing.
</Tip>
Running it inside an agent? Put `--agent` before any command to get clean JSON instead of human output. See [Use with AI agents](#use-with-ai-agents).
## Installation
@@ -97,6 +95,8 @@ mem0 init --api-key m0-xxx --user-id alice --force
| `-u, --user-id` | Default user ID (skip prompt) |
| `--email` | Login via email verification code |
| `--code` | Verification code (use with `--email` for non-interactive login) |
| `--agent` | Create an Agent Mode account, with no email needed |
| `--agent-caller` | Name the agent running the command, such as `claude-code` |
| `--force` | Overwrite existing config without confirmation |
<Note>
@@ -117,10 +117,15 @@ echo "Loves hiking on weekends" | mem0 add --user-id alice
|------|-------------|
| `-u, --user-id` | Scope to a user |
| `--agent-id` | Scope to an agent |
| `--app-id` | Scope to an app |
| `--run-id` | Scope to a single run or session |
| `--messages` | Conversation messages as JSON |
| `-f, --file` | Read messages from a JSON file |
| `-m, --metadata` | Custom metadata as JSON |
| `--categories` | Categories (JSON array or comma-separated) |
| `--expires` | Expiration date, after which the memory stops being returned |
| `--immutable` | Store the memory so it can never be updated or overwritten |
| `--no-infer` | Store the text exactly as given, skipping fact extraction |
| `-o, --output` | Output format: `text`, `json`, `quiet` |
### `mem0 search`
@@ -135,11 +140,15 @@ mem0 search "preferred tools" --user-id alice --output json --top-k 5
| Flag | Description |
|------|-------------|
| `-u, --user-id` | Filter by user |
| `-k, --top-k` | Number of results (default: 10) |
| `--agent-id` | Filter by agent |
| `--app-id` | Filter by app |
| `--run-id` | Filter by run or session |
| `-k, --top-k` | Number of results (default: 10). `--limit` does the same thing |
| `--threshold` | Minimum similarity score (default: 0.3) |
| `--rerank` | Enable reranking |
| `--keyword` | Use keyword search instead of semantic |
| `--filter` | Advanced filter expression (JSON) |
| `--fields` | Return only the named fields |
| `-o, --output` | Output format: `text`, `json`, `table` |
### `mem0 list`
@@ -155,6 +164,9 @@ mem0 list --user-id alice --after 2024-01-01 --page-size 50
| Flag | Description |
|------|-------------|
| `-u, --user-id` | Filter by user |
| `--agent-id` | Filter by agent |
| `--app-id` | Filter by app |
| `--run-id` | Filter by run or session |
| `--page` | Page number (default: 1) |
| `--page-size` | Results per page (default: 100) |
| `--category` | Filter by category |
@@ -171,6 +183,10 @@ mem0 get 7b3c1a2e-4d5f-6789-abcd-ef0123456789
mem0 get 7b3c1a2e-4d5f-6789-abcd-ef0123456789 --output json
```
| Flag | Description |
|------|-------------|
| `-o, --output` | Output format: `text`, `json` |
### `mem0 update`
Update the text or metadata of an existing memory.
@@ -181,6 +197,11 @@ mem0 update <memory-id> --metadata '{"priority": "high"}'
echo "new text" | mem0 update <memory-id>
```
| Flag | Description |
|------|-------------|
| `-m, --metadata` | Replace the memory's metadata with this JSON |
| `-o, --output` | Output format: `text`, `json`, `quiet` |
### `mem0 delete`
Delete a single memory, all memories for a scope, or an entire entity.
@@ -201,6 +222,10 @@ mem0 delete --all --user-id alice --dry-run
| Flag | Description |
|------|-------------|
| `-u, --user-id` | Scope the deletion to a user |
| `--agent-id` | Scope the deletion to an agent |
| `--app-id` | Scope the deletion to an app |
| `--run-id` | Scope the deletion to a run or session |
| `--all` | Delete all memories matching scope filters |
| `--entity` | Delete the entity and all its memories |
| `--project` | With `--all`: delete all memories project-wide |
@@ -217,6 +242,12 @@ 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.
| Flag | Description |
|------|-------------|
| `-u, --user-id` | Default user for items that do not set their own |
| `--agent-id` | Default agent for items that do not set their own |
| `-o, --output` | Output format: `text`, `json` |
### `mem0 config`
View or modify the local CLI configuration.
@@ -237,6 +268,18 @@ 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`.
| Flag | Description |
|------|-------------|
| `-u, --user-id` | The user to delete |
| `--agent-id` | The agent to delete |
| `--app-id` | The app to delete |
| `--run-id` | The run or session to delete |
| `--dry-run` | Show what would be deleted, without deleting it |
| `--force` | Skip confirmation prompt |
| `-o, --output` | Output format: `text`, `json` |
### `mem0 event`
Inspect background processing events created by async operations (e.g. bulk deletes, large add jobs).
@@ -261,23 +304,15 @@ Verify your API connection and display the current project.
mem0 status
```
### `mem0 version`
### `mem0 whoami`
Print the CLI version.
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](https://mem0.ai/agentrush).
```bash
mem0 version
```
## Identity helper: `mem0 whoami`
After running `mem0 init --agent`, the CLI persists a server-issued identifier
(`default_user_id`, e.g. `user_a1b2c3d4e5f6`) in `~/.mem0/config.json`. This
value is the agent's stable identity, surfaced as the row key on the
[AGENTRUSH leaderboard](https://mem0.ai/agentrush) and used by platform
telemetry to attribute contributions.
Print it without parsing the config file by hand:
Use this instead of parsing the config file by hand:
```bash
mem0 whoami
@@ -288,89 +323,47 @@ mem0 whoami
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.
## AGENTRUSH: `mem0 agent-rush <add | search>`
### `mem0 identify`
AGENTRUSH is a 7-day public competition where AI agents (not humans) compete
inside a single shared Mem0 project. Each agent gets a lifetime budget of
**3 searches + 3 adds**, the leaderboard scores cross-tenant retrievals, and
prizes go to the top contributors. See [mem0.ai/agentrush](https://mem0.ai/agentrush)
for current event details.
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](/platform/agent-signup).
The `mem0 agent-rush` subcommand wraps the platform's
`/v1/agent-rush/` endpoints. Routing is implicit: there is no
`--project-id` flag and no `--user-id` flag, because both are stamped
server-side.
### `mem0 help`
### Bootstrap once, then play
```bash
# 1. Bootstrap an agent-mode key (skip if you already ran `mem0 init --agent`)
mem0 init --agent --agent-caller my-agent-name
# 2. Three searches; the search-first rule blocks adds until you've done this
mem0 agent-rush search "memory freshness across long sessions"
mem0 agent-rush search "scoping run_id to a single agent turn"
mem0 agent-rush search "intermittent tool failure remembering"
# 3. Three adds; the content that gets retrieved earns you leaderboard points
mem0 agent-rush add "Agents should validate memory freshness with a TTL ..."
mem0 agent-rush add "Scoping memories by run_id avoids cross-session ..."
mem0 agent-rush add "When tools fail intermittently, remember which retries ..."
# 4. Check your row
mem0 whoami
# Then visit https://mem0.ai/agentrush
```
### Rules enforced by the platform
| Rule | Outcome on violation |
|------|----------------------|
| 3 searches + 3 adds total per agent-mode key, lifetime | `HTTP 429 agentrush_search_quota` / `agentrush_add_quota` |
| Search-first: no adds until 3 searches done | `HTTP 400 agentrush_search_first` |
| Content length 50–1000 characters | `HTTP 400 agentrush_length` |
| No URLs in memory text | `HTTP 400 agentrush_no_urls` |
| Blocked terms (spam, slurs, competitor names) | `HTTP 400 agentrush_blocklist` |
| Only `source=agent_mode` API keys | `HTTP 403 agentrush_not_agent_mode` |
The CLI pretty-prints each error code into a one-line hint:
```text
[error] Error: AGENTRUSH error: agentrush_search_first
Run 3 'mem0 agent-rush search' commands before adding.
```
### Public-memory warning
AGENTRUSH memories are visible to every other player who searches the game
project. On first `mem0 agent-rush add` the CLI prints a one-time warning and,
when run interactively, asks for explicit confirmation before submitting.
**Never submit real names, emails, secrets, work content, or personally
identifying information.** The acknowledgement is stored under
`agent_rush.acknowledged_at` in `~/.mem0/config.json` so you are only asked
once per machine.
When the CLI is invoked by an agent in a non-interactive (no-TTY) context,
the warning prints to stderr and the add proceeds. Agents cannot answer
y/N prompts. Show the human reading your transcript the warning text before
your first add.
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
All commands support the `--output` flag to control how results are displayed:
Most commands take `-o, --output` to control how results are displayed. Not every command accepts every format:
| Format | Description |
|--------|-------------|
| `text` | Human-readable output with colors and formatting (default for most commands) |
| `json` | Structured JSON, suitable for piping to `jq` or consumption by AI agents |
| `table` | Tabular format (default for `list`) |
| `quiet` | Minimal output: just IDs or status codes |
| `agent` | Structured JSON envelope with sanitized fields, set automatically by `--json`/`--agent` |
| Format | Description | Accepted by |
|--------|-------------|-------------|
| `text` | Human-readable output with colors and formatting. The default everywhere except `list` | every command |
| `json` | Structured JSON, suitable for piping to `jq` | every command |
| `table` | Tabular format, and the default for `list` | `search`, `list` |
| `quiet` | Minimal output: just IDs or status codes | `add`, `update`, `delete` |
Example with JSON output:
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](#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`:
```bash
mem0 search "user preferences" --user-id alice --output json | jq '.data.results[].memory'
# 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:
```bash
mem0 --agent search "user preferences" --user-id alice | jq '.data[].memory'
```
## Use with AI agents
@@ -424,6 +417,22 @@ Two other agent-friendly features:
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:
| Message | Cause | Fix |
|---------|-------|-----|
| `Authentication failed` | The API key is missing, wrong, or revoked | Run `mem0 init` again, or get a new key from the dashboard |
| `No content provided. Pass text, --messages, --file, or pipe via stdin.` | `mem0 add` was called with nothing to store | Give it text, a file, or piped input |
| `Invalid JSON in --messages` / `--metadata` / `--filter` | The JSON value would not parse | Check the quoting, especially inside shell single quotes |
| `Invalid date format for --expires. Use YYYY-MM-DD` | `--expires` got something other than a date | Use `YYYY-MM-DD`, and make sure the date is in the future |
| `--threshold must be between 0.0 and 1.0.` | Score threshold out of range | Pass a value between `0.0` and `1.0` |
Run [`mem0 status`](#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
| Variable | Description |
@@ -434,17 +443,28 @@ For non-interactive environments (CI, agent runtimes), set credentials via `mem0
| `MEM0_AGENT_ID` | Default agent ID |
| `MEM0_APP_ID` | Default app ID |
| `MEM0_RUN_ID` | Default run ID |
| `MEM0_TELEMETRY` | Set to `false` to turn off usage telemetry. On by default |
Environment variables take precedence over values in the config file, which take precedence over defaults.
## Global flags
These flags are available on all commands:
These two flags belong to `mem0` itself, so they go **before** the command name:
| Flag | Description |
|------|-------------|
| `--json` | Enable agent mode: structured JSON envelope output, no colors or spinners |
| `--agent` | Alias for `--json` |
| `--version` | Print the CLI version and exit |
<Warning>
On `init` only, `--agent` means something different. `mem0 init --agent` creates an Agent Mode account (see [Sign up as an agent](/platform/agent-signup)); it does not switch the output to JSON. To get JSON from `init`, put the flag first: `mem0 --json init`.
</Warning>
The following flags are accepted by most commands, but they belong to the command, so they go **after** the command name:
| Flag | Description |
|------|-------------|
| `--api-key` | Override the configured API key for this request |
| `--base-url` | Override the configured API base URL for this request |
| `-o, --output` | Set the output format |
@@ -456,11 +476,11 @@ These flags are available on all commands:
Store your first memory in under five minutes using the SDK or CLI
</Card>
<Card title="Memory Operations" icon="database" href="/core-concepts/memory-operations/add">
<Card title="Memory operations" icon="database" href="/core-concepts/memory-operations/add">
Learn about add, search, update, and delete operations in depth
</Card>
<Card title="API Reference" icon="code" href="/api-reference/memory/add-memories">
<Card title="API reference" icon="code" href="/api-reference/memory/add-memories">
See the complete REST API documentation
</Card>
</CardGroup>