Update docs: Improve getting started section (#6707)
This commit is contained in:
Deshraj Yadav
@@ -1,13 +1,19 @@
|
||||
---
|
||||
title: Sign up as an agent
|
||||
description: "Zero-friction signup for AI agents: mint a working Mem0 API key in under five seconds. No email, no dashboard, no OTP."
|
||||
description: "Let an AI agent create its own Mem0 account and API key in four commands, with no email or dashboard needed."
|
||||
icon: "robot"
|
||||
iconType: "solid"
|
||||
---
|
||||
|
||||
If you're an AI agent (Claude Code, Cursor, Codex, Cline, Aider, Windsurf, or any other autonomous coding tool), you don't need a human to set up Mem0 for you. Four commands (install, sign up, push a memory, search it) and you have persistent memory.
|
||||
Normally a person signs up for Mem0, gets an API key from the dashboard, and hands it to their tools. Agent Mode skips that: a coding agent creates its own account from the terminal and starts storing memories immediately. A human can take ownership of that account later, without disrupting the agent.
|
||||
|
||||
## The 4-command demo
|
||||
This page is written for both readers. The setup below is for the agent; [Claiming the account](#claiming-the-account-for-the-human-owner) is for the person who ends up owning it.
|
||||
|
||||
<Note>
|
||||
**If you're an AI agent** (Claude Code, Cursor, Codex, Cline, Aider, Windsurf, or any other coding tool), run the four commands below. You don't need a human to set Mem0 up for you.
|
||||
</Note>
|
||||
|
||||
## Sign up in four commands
|
||||
|
||||
<CodeGroup>
|
||||
```bash npm
|
||||
@@ -17,11 +23,11 @@ npm install -g @mem0/cli
|
||||
# 2. Sign up as an agent (replace `claude-code` with your name)
|
||||
mem0 init --agent --agent-caller claude-code
|
||||
|
||||
# 3. Push a memory
|
||||
mem0 add "I am using mem0"
|
||||
# 3. Store a memory
|
||||
mem0 add "Prefers TypeScript over JavaScript for new projects"
|
||||
|
||||
# 4. Verify
|
||||
mem0 search "am I using mem0"
|
||||
# 4. Search it back
|
||||
mem0 search "what language should I use"
|
||||
```
|
||||
|
||||
```bash pip
|
||||
@@ -31,14 +37,22 @@ pip install mem0-cli
|
||||
# 2. Sign up as an agent (replace `claude-code` with your name)
|
||||
mem0 init --agent --agent-caller claude-code
|
||||
|
||||
# 3. Push a memory
|
||||
mem0 add "I am using mem0"
|
||||
# 3. Store a memory
|
||||
mem0 add "Prefers TypeScript over JavaScript for new projects"
|
||||
|
||||
# 4. Verify
|
||||
mem0 search "am I using mem0"
|
||||
# 4. Search it back
|
||||
mem0 search "what language should I use"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Step 2 prints your new account's default scope and how to hand the account to a human later:
|
||||
|
||||
```
|
||||
✓ Agent Mode active. Default user_id: swift-otter-4821
|
||||
|
||||
To claim this account later: mem0 init --email <your-email>
|
||||
```
|
||||
|
||||
That's it. Under 30 seconds from a fresh shell to a working memory store.
|
||||
|
||||
## Identify yourself with `--agent-caller`
|
||||
@@ -46,17 +60,17 @@ That's it. Under 30 seconds from a fresh shell to a working memory store.
|
||||
Replace `claude-code` in the `init` command with your actual agent name (`cursor`, `codex`, `cline`, `aider`, or any short label). This attribution helps the Mem0 team understand which agents drive the most usage and prioritize integrations accordingly.
|
||||
|
||||
<Tip>
|
||||
**Forgot `--agent-caller` on init?** Run `mem0 identify <your-name>` after the fact, same key, just back-fills the attribution. Idempotent.
|
||||
**Forgot `--agent-caller` when you ran `init`?** Run `mem0 identify <your-name>` afterwards. It keeps the same API key and just fills in the name, so it is safe to run more than once.
|
||||
</Tip>
|
||||
|
||||
## What happened when you ran `mem0 init --agent`?
|
||||
|
||||
- A **shadow account** was minted on the Mem0 backend with a fresh API key.
|
||||
- The key was saved to `~/.mem0/config.json` (mode 0600) on the machine you ran the command on.
|
||||
- A default `user_id` was provisioned so `mem0 add` / `mem0 search` work without explicit scope flags.
|
||||
- The account is **unclaimed**; no human owns it yet.
|
||||
- A new Mem0 account was created with its own API key.
|
||||
- The key was saved to `~/.mem0/config.json` on that machine, readable only by you (file mode `0600`).
|
||||
- A default `user_id` was created, so `mem0 add` and `mem0 search` work without you passing scope flags.
|
||||
- **Nobody owns the account yet.** It works, but no human is attached to it until someone claims it.
|
||||
|
||||
Every command run against this key prints a one-line reminder asking you to surface the claim instructions to your human user.
|
||||
Every command run with this key prints a one-line reminder to pass the claim instructions on to your human.
|
||||
|
||||
## Claiming the account (for the human owner)
|
||||
|
||||
@@ -66,7 +80,7 @@ When the human is ready to take ownership of the agent's account (and all the me
|
||||
mem0 init --email you@yourcompany.com
|
||||
```
|
||||
|
||||
The CLI detects the existing Agent Mode config, sends a verification code, and upgrades the shadow account in-place:
|
||||
The CLI spots the existing Agent Mode setup, emails a verification code, and upgrades the account in place:
|
||||
|
||||
- **The API key never changes**, so the agent isn't disrupted.
|
||||
- **All memories transfer** to the human's account.
|
||||
@@ -76,26 +90,33 @@ Pass `--code 123456` to skip the interactive code prompt for fully non-interacti
|
||||
|
||||
## Rate limits and quotas
|
||||
|
||||
Agent Mode signups are rate-limited to **5 per day per IP address** to prevent abuse. If you hit the limit, the request fails with a generic **403 Forbidden** (no custom error message, no `Retry-After` header). Wait a while or try from a different network.
|
||||
Agent Mode signups are limited to **5 per day per IP address** to prevent abuse. If you hit the limit, the CLI tells you so:
|
||||
|
||||
Unclaimed agent accounts get the standard Mem0 free-tier quotas. The human owner can upgrade after claiming.
|
||||
```
|
||||
Daily Agent Mode signup limit reached for this network (5/day).
|
||||
Try again from a different IP or after midnight UTC.
|
||||
```
|
||||
|
||||
Calling the API directly instead of through the CLI returns a plain `403 Forbidden` with no explanation and no `Retry-After` header, so handle that case yourself.
|
||||
|
||||
Until someone claims it, an agent account gets the standard Mem0 free-tier quotas. The human owner can upgrade after claiming.
|
||||
|
||||
## What's next
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="CLI Reference" icon="terminal" href="/platform/cli">
|
||||
Full command-by-command reference for `mem0 add`, `mem0 search`, `mem0 list`, and the rest.
|
||||
<Card title="CLI reference" icon="terminal" href="/platform/cli">
|
||||
Every command in full: `mem0 add`, `mem0 search`, `mem0 list`, and the rest.
|
||||
</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">
|
||||
How `add`, `search`, `update`, and `delete` work under the hood.
|
||||
</Card>
|
||||
|
||||
<Card title="Mem0 MCP" icon="plug" href="/platform/mem0-mcp">
|
||||
Connect agents to Mem0 via the Model Context Protocol, as an alternative integration path.
|
||||
Give your agent memory as a set of tools instead of shell commands.
|
||||
</Card>
|
||||
|
||||
<Card title="Platform Overview" icon="star" href="/platform/overview">
|
||||
The full Mem0 Platform feature set once you claim your account.
|
||||
<Card title="Platform overview" icon="star" href="/platform/overview">
|
||||
Everything the account unlocks once a human claims it.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
+115
-95
@@ -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>
|
||||
|
||||
@@ -66,7 +66,7 @@ await client.search("What is Alice's favorite sport?", filters={"user_id": "alic
|
||||
```
|
||||
|
||||
```javascript JavaScript
|
||||
await client.search("What is Alice's favorite sport?", { filters: { userId: "alice" } });
|
||||
await client.search("What is Alice's favorite sport?", { filters: { user_id: "alice" } });
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
+58
-33
@@ -8,18 +8,20 @@ estimatedTime: "~2 minutes"
|
||||
<Info>
|
||||
**Prerequisites**
|
||||
- Mem0 Platform account (<a href="https://app.mem0.ai?utm_source=oss&utm_medium=platform-mem0-mcp" rel="nofollow">Sign up here</a>)
|
||||
- API key (<a href="https://app.mem0.ai/settings/api-keys?utm_source=oss&utm_medium=platform-mem0-mcp" rel="nofollow">Get one from dashboard</a>)
|
||||
- Node.js 14+ (for npx)
|
||||
- API key (<a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=platform-mem0-mcp" rel="nofollow">Get one from dashboard</a>)
|
||||
- Node.js 18+ (for npx)
|
||||
- An MCP-compatible client (Claude, Claude Code, Codex, Cursor, Windsurf, VS Code, OpenCode)
|
||||
</Info>
|
||||
|
||||
## What is Mem0 MCP?
|
||||
|
||||
Mem0 MCP Server exposes Mem0's memory capabilities as MCP tools, letting AI agents decide when to save, search, or update information. The cloud-hosted MCP server requires no local installation: just connect and start using memory.
|
||||
MCP (Model Context Protocol) is a standard way for AI clients to call external tools. The Mem0 MCP server hands your agent a set of memory tools, so it can decide for itself when to save something, look something up, or update what it already knows. Nothing runs on your machine: the server is hosted by Mem0, and your client connects to it over HTTPS.
|
||||
|
||||
## Quick Setup
|
||||
Memories you store this way live in your Mem0 account, not on your computer.
|
||||
|
||||
Add Mem0 MCP to your preferred clients with a single command:
|
||||
## Quick setup
|
||||
|
||||
Point your clients at the hosted server with a single command:
|
||||
|
||||
```bash
|
||||
npx mcp-add \
|
||||
@@ -29,9 +31,31 @@ npx mcp-add \
|
||||
--clients "claude,claude code,cursor,windsurf,vscode,opencode"
|
||||
```
|
||||
|
||||
This automatically configures Mem0 MCP for all supported clients at once.
|
||||
`mcp-add` is a helper that writes the Mem0 server into each client's own MCP config file, so you do not have to edit them by hand. Name only the clients you actually use. If you would rather see the change yourself, every client's manual config is under [Client-specific setup](#client-specific-setup).
|
||||
|
||||
## Available Tools
|
||||
Restart each client afterwards so it picks up the new server.
|
||||
|
||||
## Signing in
|
||||
|
||||
The server is authenticated, so connecting is not enough on its own. There are two ways in:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Sign in through the client">
|
||||
Most clients handle this for you. The first time your agent uses a Mem0 tool, the client opens a browser window asking you to authorize access to your Mem0 account. Approve it once and the client stores the token, refreshing it as needed.
|
||||
|
||||
This is the easier path, and it is what happens by default if you followed the quick setup above.
|
||||
</Tab>
|
||||
|
||||
<Tab title="Use your API key">
|
||||
For clients without browser sign-in, or for headless environments like CI, send your API key as a bearer token instead. Where you put it depends on the client; see [Client-specific setup](#client-specific-setup) for the exact syntax.
|
||||
|
||||
Get a key from the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=platform-mem0-mcp" rel="nofollow">Mem0 dashboard</a>, and keep it out of any file you commit.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
If neither is set up, the server replies `401 Authentication required` and your client reports the connection as failed.
|
||||
|
||||
## Available tools
|
||||
|
||||
The MCP server exposes these memory tools to your AI client:
|
||||
|
||||
@@ -51,7 +75,7 @@ The MCP server exposes these memory tools to your AI client:
|
||||
|
||||
---
|
||||
|
||||
## Client-Specific Setup
|
||||
## Client-specific setup
|
||||
|
||||
You can also configure individual clients:
|
||||
|
||||
@@ -170,43 +194,44 @@ You can also configure individual clients:
|
||||
|
||||
---
|
||||
|
||||
## Verify Your Setup
|
||||
## Check that it worked
|
||||
|
||||
Once configured, your AI client can:
|
||||
- Automatically save information with `add_memory`
|
||||
- Search memories with `search_memories`
|
||||
- Update memories with `update_memory`
|
||||
- Delete memories with `delete_memory`
|
||||
|
||||
**Sample Interactions:**
|
||||
Restart your client, then ask it to store something and read it back in a later message:
|
||||
|
||||
```
|
||||
User: Remember that I love tiramisu
|
||||
Agent: Got it! I've saved that you love tiramisu.
|
||||
You: Remember that I prefer TypeScript over JavaScript for new projects.
|
||||
Agent: Saved.
|
||||
|
||||
User: What do you know about my food preferences?
|
||||
Agent: Based on your memories, you love tiramisu.
|
||||
|
||||
User: Update my project: the mobile app is now 80% complete
|
||||
Agent: Updated your project status successfully.
|
||||
You: What language do I prefer for new projects?
|
||||
Agent: You prefer TypeScript over JavaScript.
|
||||
```
|
||||
|
||||
<Info icon="check">
|
||||
If you get "Connection failed", ensure you have a valid API key from <a href="https://app.mem0.ai/settings/api-keys?utm_source=oss&utm_medium=platform-mem0-mcp" rel="nofollow">Mem0 Dashboard</a>.
|
||||
</Info>
|
||||
The second answer only works if the memory was really stored, so this is a genuine round-trip test rather than the model repeating itself.
|
||||
|
||||
Two things to look for while you do it:
|
||||
|
||||
- Your client should show the Mem0 tools among its available tools. Most clients list them in a tools or MCP panel.
|
||||
- The first tool call should trigger the browser sign-in described above, unless you configured an API key.
|
||||
|
||||
To confirm from outside the client, open the <a href="https://app.mem0.ai/dashboard?utm_source=oss&utm_medium=platform-mem0-mcp" rel="nofollow">Mem0 dashboard</a>: anything the agent saved appears there.
|
||||
|
||||
---
|
||||
|
||||
## Quick Recovery
|
||||
## Troubleshooting
|
||||
|
||||
- **"Connection refused"** → Check your internet connection and ensure the MCP client is correctly configured
|
||||
- **"Invalid API key"** → Get a new key from <a href="https://app.mem0.ai/settings/api-keys?utm_source=oss&utm_medium=platform-mem0-mcp" rel="nofollow">Mem0 Dashboard</a>
|
||||
- **"npx command not found"** → Install Node.js from [nodejs.org](https://nodejs.org)
|
||||
| What you see | What it means | What to do |
|
||||
|---|---|---|
|
||||
| `401` or "Authentication required" | The client connected but is not signed in | Complete the browser sign-in, or set your API key as a bearer token |
|
||||
| "Connection refused" or "failed to connect" | The client cannot reach the server | Check your internet connection, then confirm the URL is exactly `https://mcp.mem0.ai/mcp` |
|
||||
| The agent has no Mem0 tools | The config was written but the client has not reloaded it | Restart the client. If the tools are still missing, check that `mcp-add` wrote to the config file your client actually reads |
|
||||
| `npx: command not found` | Node.js is not installed | Install it from [nodejs.org](https://nodejs.org) |
|
||||
| "Invalid API key" | The key is wrong, revoked, or from a different account | Get a new one from the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=platform-mem0-mcp" rel="nofollow">Mem0 dashboard</a> |
|
||||
|
||||
---
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Platform Quickstart](/platform/quickstart) - direct SDK/API integration guide
|
||||
- [MCP Specification](https://modelcontextprotocol.io) - the Model Context Protocol standard
|
||||
- [Gemini with Mem0 MCP](/cookbooks/frameworks/gemini-3-with-mem0-mcp) - example integration cookbook
|
||||
- [Platform quickstart](/platform/quickstart): call Mem0 from your own code instead of through an agent
|
||||
- [Mem0 CLI](/platform/cli): the same operations from your terminal
|
||||
- [MCP specification](https://modelcontextprotocol.io): the Model Context Protocol standard
|
||||
- [Gemini with Mem0 MCP](/cookbooks/frameworks/gemini-3-with-mem0-mcp): a worked example
|
||||
|
||||
@@ -5,31 +5,42 @@ icon: "bolt"
|
||||
iconType: "solid"
|
||||
---
|
||||
|
||||
Get started with Mem0 Platform's hosted API in under 5 minutes. This guide shows you how to authenticate and store your first memory.
|
||||
In about five minutes you will get an API key, store your first memory, and search it back. Follow along in Python, JavaScript, cURL, or the terminal.
|
||||
|
||||
<Note>
|
||||
**Are you an AI agent?** See [Sign up as an agent](/platform/agent-signup): mint a working API key in four commands, no email or dashboard required.
|
||||
**Are you an AI agent?** See [Sign up as an agent](/platform/agent-signup): create a working API key in four commands, with no email or dashboard.
|
||||
</Note>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Mem0 Platform account (<a href="https://app.mem0.ai?utm_source=oss&utm_medium=platform-quickstart" rel="nofollow">Sign up here</a>)
|
||||
- API key (<a href="https://app.mem0.ai/dashboard/settings?tab=api-keys&subtab=configuration" rel="nofollow">Get one from dashboard</a>)
|
||||
- Python 3.10+, Node.js 18+, or cURL
|
||||
- Python 3.10+, Node.js 18+, or cURL. The CLI needs either Node.js 18+ or Python 3.10+.
|
||||
|
||||
## Installation
|
||||
## Store your first memory
|
||||
|
||||
<Steps>
|
||||
<Step title="Install SDK">
|
||||
<Step title="Install">
|
||||
Pick a tab and use the same one for every step below.
|
||||
|
||||
<CodeGroup>
|
||||
```bash pip
|
||||
```bash Python
|
||||
pip install mem0ai
|
||||
```
|
||||
|
||||
```bash npm
|
||||
```bash JavaScript
|
||||
npm install mem0ai
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
# Nothing to install. cURL ships with macOS and most Linux distributions.
|
||||
```
|
||||
|
||||
```bash CLI
|
||||
npm install -g @mem0/cli
|
||||
# or, if you prefer Python: pip install mem0-cli
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
</Step>
|
||||
|
||||
@@ -39,12 +50,12 @@ npm install mem0ai
|
||||
from mem0 import MemoryClient
|
||||
|
||||
client = MemoryClient(api_key="your-api-key")
|
||||
````
|
||||
```
|
||||
|
||||
```javascript JavaScript
|
||||
import MemoryClient from 'mem0ai';
|
||||
const client = new MemoryClient({ apiKey: 'your-api-key' });
|
||||
````
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
export MEM0_API_KEY="your-api-key"
|
||||
@@ -65,7 +76,7 @@ messages = [
|
||||
{"role": "assistant", "content": "Got it! I'll remember your dietary preferences."}
|
||||
]
|
||||
client.add(messages, user_id="user123")
|
||||
````
|
||||
```
|
||||
|
||||
```javascript JavaScript
|
||||
const messages = [
|
||||
@@ -73,7 +84,7 @@ const messages = [
|
||||
{"role": "assistant", "content": "Got it! I'll remember your dietary preferences."}
|
||||
];
|
||||
await client.add(messages, { userId: "user123" });
|
||||
````
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST https://api.mem0.ai/v3/memories/add/ \
|
||||
@@ -93,6 +104,17 @@ mem0 add "I'm a vegetarian and allergic to nuts." --user-id user123
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
Mem0 pulls the individual facts out of the conversation and stores each one separately:
|
||||
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{"id": "0f2c1b6e-9a3d-4b18-8f77-1c2d3e4f5a6b", "memory": "Is a vegetarian", "event": "ADD"},
|
||||
{"id": "14e1b28a-2014-40ad-ac42-69c9ef42193d", "memory": "Allergic to nuts", "event": "ADD"}
|
||||
]
|
||||
}
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Search memories">
|
||||
@@ -100,12 +122,12 @@ mem0 add "I'm a vegetarian and allergic to nuts." --user-id user123
|
||||
```python Python
|
||||
results = client.search("What are my dietary restrictions?", filters={"user_id": "user123"})
|
||||
print(results)
|
||||
````
|
||||
```
|
||||
|
||||
```javascript JavaScript
|
||||
const results = await client.search("What are my dietary restrictions?", { filters: { user_id: "user123" } });
|
||||
console.log(results);
|
||||
````
|
||||
```
|
||||
|
||||
```bash cURL
|
||||
curl -X POST https://api.mem0.ai/v3/memories/search/ \
|
||||
@@ -123,7 +145,7 @@ mem0 search "What are my dietary restrictions?" --user-id user123
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
**Output:**
|
||||
Both facts come back, ranked by how well they match the question:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -140,35 +162,57 @@ mem0 search "What are my dietary restrictions?" --user-id user123
|
||||
"created_at": "2025-10-22T04:40:22.864647-07:00",
|
||||
"updated_at": "2025-10-22T04:40:22.864647-07:00",
|
||||
"expiration_date": null,
|
||||
"score": 0.30
|
||||
"score": 0.87
|
||||
},
|
||||
{
|
||||
"id": "0f2c1b6e-9a3d-4b18-8f77-1c2d3e4f5a6b",
|
||||
"memory": "Is a vegetarian",
|
||||
"user_id": "user123",
|
||||
"agent_id": null,
|
||||
"app_id": null,
|
||||
"run_id": null,
|
||||
"categories": ["food_preferences"],
|
||||
"metadata": {},
|
||||
"created_at": "2025-10-22T04:40:22.864647-07:00",
|
||||
"updated_at": "2025-10-22T04:40:22.864647-07:00",
|
||||
"expiration_date": null,
|
||||
"score": 0.81
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Pass these memories to your model as context, and it answers with what it already knows about the user instead of asking again.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Callout type="tip" icon="plug">
|
||||
**Pro Tip**: Want AI agents to manage their own memory automatically? Use <Link href="/platform/mem0-mcp">Mem0 MCP</Link> to let LLMs decide when to save, search, and update memories.
|
||||
</Callout>
|
||||
<Tip>
|
||||
Rather than calling `add` and `search` yourself, you can hand Mem0 to your agent as a set of tools and let it decide when to save and look things up. See [Mem0 MCP](/platform/mem0-mcp).
|
||||
</Tip>
|
||||
|
||||
## What's next?
|
||||
|
||||
You stored and searched your first memory. Keep going:
|
||||
You stored and searched your first memory. Start with scoping, since every call you make from here needs it:
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="How it works" icon="diagram-project" href="/core-concepts/how-it-works">
|
||||
See how Mem0 extracts, stores, and retrieves memories under the hood.
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Scope memories to users and agents" icon="users" href="/platform/features/entity-scoped-memory">
|
||||
What `user_id` actually does, plus the `agent_id`, `app_id`, and `run_id` fields that came back empty above.
|
||||
</Card>
|
||||
|
||||
<Card title="Memory operations" icon="database" href="/core-concepts/memory-operations/add">
|
||||
Go beyond add and search: update, delete, and the full memory lifecycle.
|
||||
<Card title="How Mem0 works" icon="diagram-project" href="/core-concepts/how-it-works">
|
||||
Why one sentence became two memories, and how Mem0 decides what to keep.
|
||||
</Card>
|
||||
|
||||
<Card title="Build an AI companion" icon="users" href="/cookbooks/essentials/building-ai-companion">
|
||||
Put it to work in a real app, end to end, in about 10 minutes.
|
||||
<Card title="Update and delete memories" icon="database" href="/core-concepts/memory-operations/add">
|
||||
The operations beyond add and search, for when stored facts change or go stale.
|
||||
</Card>
|
||||
|
||||
<Card title="Use Mem0 with your agent framework" icon="plug" href="/integrations">
|
||||
Wire memory into LangChain, CrewAI, LangGraph, or the OpenAI Agents SDK.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Stuck on setup? See the [FAQs and troubleshooting](/platform/faqs).
|
||||
<Note>
|
||||
Something not working? The [FAQs and troubleshooting](/platform/faqs) page covers the common setup errors.
|
||||
</Note>
|
||||
|
||||
Reference in New Issue
Block a user