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

docs: update memory tool list, CLI usage, and config file reading logic (#4861)

Browse Source 
Co-authored-by: Livia Ellen <liviaellen@msn.com>
This commit is contained in:
Kartik
2026-04-20 20:09:45 +05:30
committed by GitHub
parent 5520226b5b
commit 4e611e8dba
31 changed files with 1531 additions and 365 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/changelog/openclaw.mdx
+13
View File
@@ -4,6 +4,19 @@ description: "Release notes for the OpenClaw plugin and agent harness."
mode: "wide"
---
<Update label="2026-04-20" description="v1.0.7">
**New Features:**
- **Chat-Based Setup:** Added chat-based Platform setup flow — users can now configure the plugin conversationally instead of editing config files manually
- **Installation Docs Rewrite:** Rewrote README and integration docs with chat-first setup, numbered manual steps.
**Improvements:**
- **SDK Upgrade:** Bumped `mem0ai` dependency to 3.0.1 for V3 API compatibility
- **Config Cleanup:** Dropped deprecated `orgId`, `projectId`, `enableGraph` config options; updated CLI prompts ([#4734](https://github.com/mem0ai/mem0/pull/4734), [#4764](https://github.com/mem0ai/mem0/pull/4764))
- **Noise Filtering:** Expanded noise patterns in memory add tool; handle leading text in JSON extraction
</Update>
<Update label="2026-04-11" description="v1.0.6">
**Bug Fixes:**
docs/integrations/openclaw.mdx
+215 -42
View File
@@ -14,16 +14,37 @@ Add long-term memory to [OpenClaw](https://github.com/openclaw/openclaw) agents
The plugin provides:
1. **Auto-Recall** — Before the agent responds, memories matching the current message are injected into context
2. **Auto-Capture** — After the agent responds, the exchange is sent to Mem0 which decides what's worth keeping
3. **Agent Tools** — Five tools for explicit memory operations during conversations
3. **Agent Tools** — Eight tools for explicit memory operations during conversations
Both auto-recall and auto-capture run silently with no manual configuration required.
## Installation
## Requirements
Check your OpenClaw version:
```bash
openclaw plugins install @mem0/openclaw-mem0
openclaw --version
# OpenClaw 2026.4.15 (041266a)
```
| OpenClaw Version | Plugin Support |
|------------------|----------------|
| `>= 2026.4.15` | Fully supported |
## Installation
The fastest way is to install directly from your OpenClaw chat, no CLI or config editing needed.
**Copy and paste this into your OpenClaw chat**; Telegram, WhatsApp, default chat, or any channel where your agent lives:
```
Setup Mem0 from mem0.ai/claw-setup
```
OpenClaw installs the plugin, prompts you for your email, and connects your Mem0 account with OTP verification. See [Chat Setup](#option-1-chat-setup-recommended) below for the full walkthrough.
If you prefer the OpenClaw CLI, or are setting up self-hosted / open-source mode, see [Manual Config](#option-2-manual-config) and [Open-Source Mode](#open-source-mode-self-hosted) below.
## Setup and Configuration
### Understanding `userId`
@@ -36,37 +57,113 @@ Pick any stable, unique identifier for the user. Common choices:
- A UUID (e.g. `"550e8400-e29b-41d4-a716-446655440000"`)
- A simple username (e.g. `"alice"`)
All memories are scoped to this `userId` — different values create separate memory namespaces. If you don't set it, it defaults to `"default"`, which means all users share the same memory space.
All memories are scoped to this `userId` — different values create separate memory namespaces. If you don't set it, it defaults to your OS username.
<Tip>In a multi-user application, set `userId` dynamically per user (e.g. from your auth system) rather than hardcoding a single value.</Tip>
### Platform Mode (Mem0 Cloud)
<Note>Get your API key from <a href="https://app.mem0.ai" rel="nofollow">app.mem0.ai</a>.</Note>
There are two ways to set up `@mem0/openclaw-mem0` on the Mem0 platform:
Add to your `openclaw.json`:
- **Chat setup (recommended)** — run the setup inside any OpenClaw chat. No config editing, no API key handling.
- **Manual config** — edit `openclaw.json` directly.
```json5
// plugins.entries
"openclaw-mem0": {
"enabled": true,
"config": {
"apiKey": "${MEM0_API_KEY}",
"userId": "alice" // any unique identifier you choose for this user
}
}
```
#### Option 1: Chat Setup (Recommended)
You no longer need manual config editing to get started. Everything happens inside the OpenClaw chat itself.
<Steps>
<Step title="Send the setup command to your OpenClaw agent">
Open any OpenClaw channel — Telegram, WhatsApp, your default chat, wherever your agent lives. Paste and send this command:
```
Setup Mem0 from mem0.ai/claw-setup
```
OpenClaw responds with a Mem0 setup card and immediately asks:
> "What's your email address? I'll send you a verification code to connect your Mem0 account."
</Step>
<Step title="Enter your email">
Type your email address and send it. Mem0 sends back:
> "Check your email for a 6-digit code and paste it here."
</Step>
<Step title="Paste the OTP">
Copy the 6-digit code from your email inbox and paste it into the chat.
You'll see the confirmation:
> "Connected to Mem0."
</Step>
</Steps>
That's it. No API key, no config file editing, no environment variables. The plugin is now active and auto-capture and auto-recall are running on every turn.
<Note>The chat flow uses the same underlying config as manual setup — it writes `apiKey` and `userId` into `openclaw.json` for you. You can still open the file to inspect or override values afterward.</Note>
#### Option 2: Manual Config
<Steps>
<Step title="Install the plugin via the OpenClaw CLI">
```bash
openclaw plugins install @mem0/openclaw-mem0
```
</Step>
<Step title="Get your API key">
Get your API key from <a href="https://app.mem0.ai?utm_source=mem0-docs" rel="nofollow">app.mem0.ai</a>.
</Step>
<Step title="Select the plugin as your memory backend in `openclaw.json`">
Add the full config to your `openclaw.json`:
```json5
{
"plugins": {
"slots": {
"memory": "openclaw-mem0"
},
"entries": {
"openclaw-mem0": {
"enabled": true,
"config": {
"apiKey": "${MEM0_API_KEY}",
"userId": "alice" // any unique identifier you choose for this user
}
}
}
}
}
```
</Step>
</Steps>
<Warning>
OpenClaw treats memory plugins as an exclusive slot. Installing the plugin alone does **not** activate it — you must also set `plugins.slots.memory` as shown above.
</Warning>
### Open-Source Mode (Self-hosted)
No Mem0 key needed. Requires `OPENAI_API_KEY` for default embeddings/LLM.
```json5
"openclaw-mem0": {
"enabled": true,
"config": {
"mode": "open-source",
"userId": "alice" // any unique identifier you choose for this user
{
"plugins": {
"slots": {
"memory": "openclaw-mem0"
},
"entries": {
"openclaw-mem0": {
"enabled": true,
"config": {
"mode": "open-source",
"userId": "alice" // any unique identifier you choose for this user
}
}
}
}
}
```
@@ -74,13 +171,25 @@ No Mem0 key needed. Requires `OPENAI_API_KEY` for default embeddings/LLM.
Sensible defaults work out of the box. To customize the embedder, vector store, or LLM:
```json5
"config": {
"mode": "open-source",
"userId": "your-user-id",
"oss": {
"embedder": { "provider": "openai", "config": { "model": "text-embedding-3-small" } },
"vectorStore": { "provider": "qdrant", "config": { "host": "localhost", "port": 6333 } },
"llm": { "provider": "openai", "config": { "model": "gpt-4o" } }
{
"plugins": {
"slots": {
"memory": "openclaw-mem0"
},
"entries": {
"openclaw-mem0": {
"enabled": true,
"config": {
"mode": "open-source",
"userId": "your-user-id",
"oss": {
"embedder": { "provider": "openai", "config": { "model": "text-embedding-3-small" } },
"vectorStore": { "provider": "qdrant", "config": { "host": "localhost", "port": 6333 } },
"llm": { "provider": "openai", "config": { "model": "gpt-4o" } }
}
}
}
}
}
}
```
@@ -93,23 +202,26 @@ Memories are organized into two scopes:
- **Session (short-term)** — Auto-capture stores memories scoped to the current session via Mem0's `run_id` / `runId` parameter. These are contextual to the ongoing conversation.
- **User (long-term)** — The agent can explicitly store long-term memories using the `memory_store` tool (with `longTerm: true`, the default). These persist across all sessions for the user.
- **User (long-term)** — The agent can explicitly store long-term memories using the `memory_add` tool (with `longTerm: true`, the default). These persist across all sessions for the user.
During **auto-recall**, the plugin searches both scopes and presents them separately — long-term memories first, then session memories — so the agent has full context.
## Agent Tools
The agent gets five tools it can call during conversations:
The agent gets eight tools it can call during conversations:
| Tool | Description |
|------|-------------|
| `memory_search` | Search memories by natural language |
| `memory_list` | List all stored memories for a user |
| `memory_store` | Explicitly save a fact |
| `memory_get` | Retrieve a memory by ID |
| `memory_forget` | Delete by ID or by query |
| `memory_search` | Search memories by natural language query. Supports `scope`, `categories`, `filters`. |
| `memory_add` | Store facts. Accepts `text` or `facts` array, `category`, `importance`, `metadata`. |
| `memory_get` | Retrieve a single memory by ID |
| `memory_list` | List all memories. Filter by `userId`, `agentId`, `scope`. |
| `memory_update` | Update a memory's text in place. Preserves history. |
| `memory_delete` | Delete by `memoryId`, `query` (search-and-delete), or `all: true`. |
| `memory_event_list` | List recent background processing events (platform mode only). |
| `memory_event_status` | Get status of a specific event by ID (platform mode only). |
The `memory_search` and `memory_list` tools accept a `scope` parameter (`"session"`, `"long-term"`, or `"all"`) to control which memories are queried. The `memory_store` tool accepts a `longTerm` boolean (default: `true`) to choose where to store.
The `memory_search` and `memory_list` tools accept a `scope` parameter (`"session"`, `"long-term"`, or `"all"`) to control which memories are queried.
## CLI Commands
@@ -123,8 +235,9 @@ openclaw mem0 search "what languages does the user know" --scope long-term
# Search only session/short-term memories
openclaw mem0 search "what languages does the user know" --scope session
# View stats
openclaw mem0 stats
# List all memories
openclaw mem0 list
openclaw mem0 list --user-id alice --top-k 20
```
## Configuration Options
@@ -134,7 +247,7 @@ openclaw mem0 stats
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `mode` | `"platform"` \| `"open-source"` | `"platform"` | Which backend to use |
| `userId` | `string` | `"default"` | Scope memories per user |
| `userId` | `string` | OS username | Scope memories per user |
| `autoRecall` | `boolean` | `true` | Inject memories before each turn |
| `autoCapture` | `boolean` | `true` | Store facts after each turn |
| `topK` | `number` | `5` | Max memories per recall |
@@ -145,8 +258,6 @@ openclaw mem0 stats
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `apiKey` | `string` | — | **Required.** Mem0 API key (supports `${MEM0_API_KEY}`) |
| `orgId` | `string` | — | Organization ID |
| `projectId` | `string` | — | Project ID |
| `customInstructions` | `string` | *(built-in)* | Extraction rules — what to store, how to format |
| `customCategories` | `object` | *(12 defaults)* | Category name → description map for tagging |
@@ -162,15 +273,77 @@ openclaw mem0 stats
| `oss.llm.provider` | `string` | `"openai"` | LLM provider (`"openai"`, `"anthropic"`, `"ollama"`, etc.) |
| `oss.llm.config` | `object` | — | Provider config: `apiKey`, `model`, `baseURL`, `temperature` |
| `oss.historyDbPath` | `string` | — | SQLite path for memory edit history |
| `oss.disableHistory` | `boolean` | `false` | Disable memory edit history tracking |
Everything inside `oss` is optional — defaults use OpenAI embeddings (`text-embedding-3-small`), in-memory vector store, and OpenAI LLM.
## Plugin Management
### Updating the Plugin
```bash
openclaw plugins update @mem0/openclaw-mem0
```
<Note>Use the npm package name (`@mem0/openclaw-mem0`) for plugin management commands, not the plugin ID (`openclaw-mem0`).</Note>
### Checking Plugin Status
```bash
openclaw plugins list
openclaw plugins inspect openclaw-mem0
```
## Troubleshooting
### "plugins.allow excludes mem0" Error
If you see an error like:
```
[openclaw] Failed to start CLI: Error: The `openclaw mem0` command is unavailable
because `plugins.allow` excludes "mem0". Add "mem0" to `plugins.allow` if you want
that bundled plugin CLI surface.
```
Add `mem0` to your `plugins.allow` list in `openclaw.json`:
```json5
{
"plugins": {
"allow": ["mem0"],
"slots": {
"memory": "openclaw-mem0"
}
}
}
```
### Plugin Not Activating
If the plugin installs but doesn't work:
1. Verify `plugins.slots.memory` is set to `"openclaw-mem0"` (not the npm package name)
2. Check `openclaw plugins list --enabled` to confirm the plugin is loaded
3. Run `openclaw mem0 status` to verify configuration
### Plugin Update Not Working
If `openclaw plugins update` fails:
1. Use the full npm package name: `openclaw plugins update @mem0/openclaw-mem0`
2. If that fails, uninstall and reinstall:
```bash
openclaw plugins uninstall openclaw-mem0
openclaw plugins install @mem0/openclaw-mem0
```
## Key Features
1. **Zero Configuration** — Auto-recall and auto-capture work out of the box with no prompting required
2. **Dual Memory Scopes** — Session-scoped short-term and user-scoped long-term memories
3. **Flexible Backend** — Use Mem0 Cloud for managed service or self-host with open-source mode
4. **Rich Tool Suite** — Five agent tools for explicit memory operations when needed
4. **Rich Tool Suite** — Eight agent tools for explicit memory operations when needed
## Conclusion