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

refactor: adjust CLI config commands, provider defaults, and README docs

Browse Source
This commit is contained in:
kartik-mem0
2026-04-06 16:10:25 +05:30
parent 8b9f11df39
commit f8c6ccf5fe
3 changed files with 143 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files
openclaw/README.md
+41 -63
View File
@@ -12,7 +12,7 @@ openclaw plugins install @mem0/openclaw-mem0
### Platform (Mem0 Cloud) ### Platform (Mem0 Cloud)
Get an API key from [app.mem0.ai](https://app.mem0.ai): Get an API key from [app.mem0.ai](https://app.mem0.ai/dashboard/api-keys):
```bash ```bash
openclaw mem0 init --api-key <your-key> --user-id <your-user-id> openclaw mem0 init --api-key <your-key> --user-id <your-user-id>
@@ -32,7 +32,9 @@ Or configure manually in `openclaw.json`:
### Open-Source (Self-hosted) ### Open-Source (Self-hosted)
No Mem0 key needed. Requires `OPENAI_API_KEY` for default embeddings and LLM. No Mem0 key needed. Requires `OPENAI_API_KEY` for default embeddings and LLM. Vectors are stored locally in SQLite at `~/.mem0/vector_store.db` — no external database required.
Defaults: `text-embedding-3-small` for embeddings, `gpt-5.4` for fact extraction.
```json5 ```json5
"openclaw-mem0": { "openclaw-mem0": {
@@ -53,7 +55,7 @@ Customize the embedder, vector store, or LLM via the `oss` block:
"oss": { "oss": {
"embedder": { "provider": "openai", "config": { "model": "text-embedding-3-small" } }, "embedder": { "provider": "openai", "config": { "model": "text-embedding-3-small" } },
"vectorStore": { "provider": "qdrant", "config": { "host": "localhost", "port": 6333 } }, "vectorStore": { "provider": "qdrant", "config": { "host": "localhost", "port": 6333 } },
"llm": { "provider": "openai", "config": { "model": "gpt-4o" } } "llm": { "provider": "openai", "config": { "model": "gpt-5.4" } }
} }
} }
``` ```
@@ -74,79 +76,57 @@ Both run silently. No prompting, no manual calls required.
### Memory Scopes ### Memory Scopes
| Scope | Description | - **Session (short-term)** — Scoped to the current conversation via `run_id`. Recalled alongside long-term memories.
|-------|-------------| - **User (long-term)** — Persistent across all sessions. Default for `memory_add`.
| **Session (short-term)** | Memories scoped to the current conversation via `run_id`. Automatically recalled alongside long-term memories. |
| **User (long-term)** | Persistent memories that span all sessions. Stored via `memory_add` with `longTerm: true` (the default). |
During auto-recall, both scopes are searched and presented separately — long-term first, then session — so the agent has full context.
### Multi-Agent Isolation ### Multi-Agent Isolation
In multi-agent setups, each agent gets its own memory namespace automatically. Session keys matching `agent:<name>:<uuid>` route memories to `userId:agent:<name>`. Single-agent deployments are unaffected. Each agent gets its own memory namespace automatically via session key routing (`agent:<name>:<uuid>` maps to `userId:agent:<name>`). Single-agent setups are unaffected.
All memory tools accept an optional `agentId` parameter for cross-agent queries:
```
memory_search({ query: "user's tech stack", agentId: "researcher" })
```
## Agent Tools ## Agent Tools
Seven tools are available to the agent during conversations: Eight tools are registered for agent use:
| Tool | Description | | Tool | Description |
|------|-------------| | ---- | ----------- |
| **`memory_search`** | Search memories by natural language query. Supports `scope` (`session`, `long-term`, `all`) and `agentId` filtering. | | `memory_search` | Search by natural language query. Supports `scope` (`session`, `long-term`, `all`), `categories`, `filters`, and `agentId`. |
| **`memory_add`** | Save a fact to memory. Supports `category`, `importance`, `longTerm`, and `agentId`. | | `memory_add` | Store facts. Accepts `text` or `facts` array, `category`, `importance`, `longTerm`, `metadata`. |
| **`memory_get`** | Retrieve a specific memory by ID. | | `memory_get` | Retrieve a single memory by ID. |
| **`memory_list`** | List stored memories with optional `userId`, `agentId`, and `limit` filters. | | `memory_list` | List all memories. Filter by `userId`, `agentId`, `scope`. |
| **`memory_update`** | Update an existing memory's text in place. Preserves edit history. | | `memory_update` | Update a memory's text in place. Preserves history. |
| **`memory_delete`** | Delete by ID, search query, or bulk (`all: true`). Requires `confirm: true` for bulk. | | `memory_delete` | Delete by `memoryId`, `query` (search-and-delete), or `all: true` (requires `confirm: true`). |
| **`memory_history`** | View the edit history of a specific memory. | | `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. |
## CLI ## CLI
All commands follow the pattern `openclaw mem0 <command>`. All commands: `openclaw mem0 <command>`.
### Memory Operations
```bash ```bash
# Add a memory # Memory operations
openclaw mem0 add "User prefers TypeScript over JavaScript" openclaw mem0 add "User prefers TypeScript over JavaScript"
# Search memories
openclaw mem0 search "what languages does the user know" openclaw mem0 search "what languages does the user know"
openclaw mem0 search "preferences" --scope long-term openclaw mem0 search "preferences" --scope long-term
openclaw mem0 search "context" --scope session
# Get, list, update, delete
openclaw mem0 get <memory_id> openclaw mem0 get <memory_id>
openclaw mem0 list --user-id alice --top-k 20 openclaw mem0 list --user-id alice --top-k 20
openclaw mem0 update <memory_id> "Updated preference text" openclaw mem0 update <memory_id> "Updated preference text"
openclaw mem0 delete <memory_id> openclaw mem0 delete <memory_id>
openclaw mem0 delete --all --user-id alice --confirm openclaw mem0 delete --all --user-id alice --confirm
openclaw mem0 import memories.json
# View edit history # Management
openclaw mem0 history <memory_id>
```
### Management
```bash
# Authenticate and configure
openclaw mem0 init openclaw mem0 init
openclaw mem0 init --api-key <key> --user-id alice openclaw mem0 init --api-key <key> --user-id alice
# Check connectivity
openclaw mem0 status openclaw mem0 status
# Manage configuration
openclaw mem0 config show openclaw mem0 config show
openclaw mem0 config get api_key openclaw mem0 config get api_key
openclaw mem0 config set user_id alice openclaw mem0 config set user_id alice
# Memory consolidation (review, merge, prune) # Events (platform only)
openclaw mem0 event list
openclaw mem0 event status <event_id>
# Memory consolidation
openclaw mem0 dream openclaw mem0 dream
openclaw mem0 dream --dry-run openclaw mem0 dream --dry-run
``` ```
@@ -156,9 +136,9 @@ openclaw mem0 dream --dry-run
### General ### General
| Key | Type | Default | Description | | Key | Type | Default | Description |
|-----|------|---------|-------------| | --- | ---- | ------- | ----------- |
| `mode` | `"platform"` \| `"open-source"` | `"platform"` | Backend mode | | `mode` | `"platform"` \| `"open-source"` | `"platform"` | Backend mode |
| `userId` | `string` | `"default"` | Unique identifier for the user. You define this — it's not found in any dashboard. All memories are scoped to this value. | | `userId` | `string` | OS username | User identifier. All memories scoped to this value. |
| `autoRecall` | `boolean` | `true` | Inject relevant memories before each turn | | `autoRecall` | `boolean` | `true` | Inject relevant memories before each turn |
| `autoCapture` | `boolean` | `true` | Extract and store facts after each turn | | `autoCapture` | `boolean` | `true` | Extract and store facts after each turn |
| `topK` | `number` | `5` | Max memories returned per recall | | `topK` | `number` | `5` | Max memories returned per recall |
@@ -167,32 +147,30 @@ openclaw mem0 dream --dry-run
### Platform Mode ### Platform Mode
| Key | Type | Default | Description | | Key | Type | Default | Description |
|-----|------|---------|-------------| | --- | ---- | ------- | ----------- |
| `apiKey` | `string` | — | **Required.** Mem0 API key (supports `${MEM0_API_KEY}`) | | `apiKey` | `string` | — | **Required.** Mem0 API key (supports `${MEM0_API_KEY}`) |
| `orgId` | `string` | — | Organization ID | | `orgId` | `string` | — | Organization ID |
| `projectId` | `string` | — | Project ID | | `projectId` | `string` | — | Project ID |
| `enableGraph` | `boolean` | `false` | Enable entity graph for relationship tracking | | `enableGraph` | `boolean` | `false` | Entity graph for relationship tracking |
| `customInstructions` | `string` | *(built-in)* | Custom extraction rules for what to store and how to format | | `customInstructions` | `string` | *(built-in)* | Custom extraction rules |
| `customCategories` | `object` | *(12 defaults)* | Category name to description map for memory tagging | | `customCategories` | `object` | *(12 defaults)* | Category name to description map |
### Open-Source Mode ### Open-Source Mode
All fields below are optional. Defaults use OpenAI embeddings, in-memory vector store, and OpenAI LLM. All fields optional. Defaults: `text-embedding-3-small` embeddings, local SQLite vector store (`~/.mem0/vector_store.db`), `gpt-5.4` LLM.
| Key | Type | Default | Description | | Key | Type | Default | Description |
|-----|------|---------|-------------| | --- | ---- | ------- | ----------- |
| `customPrompt` | `string` | *(built-in)* | Extraction prompt for memory processing | | `customPrompt` | `string` | *(built-in)* | Extraction prompt |
| `oss.embedder.provider` | `string` | `"openai"` | Embedding provider | | `oss.embedder.provider` | `string` | `"openai"` | Embedding provider |
| `oss.embedder.config` | `object` | — | Provider config (`apiKey`, `model`, `baseURL`) | | `oss.embedder.config` | `object` | — | Provider config (`apiKey`, `model`, `baseURL`) |
| `oss.vectorStore.provider` | `string` | `"memory"` | Vector store provider | | `oss.vectorStore.provider` | `string` | `"memory"` | Vector store provider (see list above) |
| `oss.vectorStore.config` | `object` | — | Provider config (`host`, `port`, `collectionName`) | | `oss.vectorStore.config` | `object` | — | Provider config (`host`, `port`, `collectionName`, `dbPath`) |
| `oss.llm.provider` | `string` | `"openai"` | LLM provider | | `oss.llm.provider` | `string` | `"openai"` | LLM provider |
| `oss.llm.config` | `object` | — | Provider config (`apiKey`, `model`, `baseURL`) | | `oss.llm.config` | `object` | — | Provider config (`apiKey`, `model`, `baseURL`) |
| `oss.historyDbPath` | `string` | — | SQLite path for memory edit history | | `oss.historyDbPath` | `string` | — | SQLite path for edit history |
| `oss.disableHistory` | `boolean` | `false` | Skip history DB initialization | | `oss.disableHistory` | `boolean` | `false` | Skip history DB |
Supported providers: `openai`, `anthropic`, `ollama`, `lmstudio`, `qdrant`, `chroma`, and more. See the [Mem0 OSS docs](https://docs.mem0.ai/open-source/node-quickstart) for the full list.
## License ## License
Apache 2.0 [Apache 2.0](LICENSE)
openclaw/cli/commands.ts
+72 -31
View File
@@ -548,7 +548,7 @@ export function registerCliCommands(
"\n Skipped. You can add it later via:", "\n Skipped. You can add it later via:",
); );
console.log( console.log(
" openclaw mem0 config set oss.embedder.config.apiKey <key>", " openclaw mem0 config set embedder_key <key>",
); );
console.log( console.log(
" Or set OPENAI_API_KEY in your environment.\n", " Or set OPENAI_API_KEY in your environment.\n",
@@ -949,6 +949,7 @@ export function registerCliCommands(
const CONFIG_KEYS: Record<string, string> = { const CONFIG_KEYS: Record<string, string> = {
// Short aliases (matches Python CLI) // Short aliases (matches Python CLI)
api_key: "apiKey", api_key: "apiKey",
email: "userEmail",
base_url: "baseUrl", base_url: "baseUrl",
user_id: "userId", user_id: "userId",
org_id: "orgId", org_id: "orgId",
@@ -958,29 +959,34 @@ export function registerCliCommands(
auto_capture: "autoCapture", auto_capture: "autoCapture",
top_k: "topK", top_k: "topK",
mode: "mode", mode: "mode",
"platform.api_key": "apiKey", embedder_provider: "oss.embedder.provider",
"platform.email": "userEmail", embedder_model: "oss.embedder.config.model",
"defaults.user_id": "userId", embedder_key: "oss.embedder.config.apiKey",
"defaults.org_id": "orgId", llm_provider: "oss.llm.provider",
"defaults.project_id": "projectId", llm_model: "oss.llm.config.model",
"defaults.enable_graph": "enableGraph", llm_key: "oss.llm.config.apiKey",
"defaults.auto_recall": "autoRecall", vector_provider: "oss.vectorStore.provider",
"defaults.auto_capture": "autoCapture", vector_host: "oss.vectorStore.config.host",
"defaults.top_k": "topK", vector_port: "oss.vectorStore.config.port",
collection_name: "oss.vectorStore.config.collectionName",
vector_db_path: "oss.vectorStore.config.dbPath",
history_db_path: "oss.historyDbPath",
disable_history: "oss.disableHistory",
}; };
// Keys that contain secrets — redact in show/get output // Keys that contain secrets — redact in show/get output
const SECRET_KEYS = new Set(["apiKey"]); const SECRET_KEYS = new Set(["apiKey", "oss.embedder.config.apiKey", "oss.llm.config.apiKey"]);
// Boolean config fields — coerce "true"/"1"/"yes" on set // Boolean config fields — coerce "true"/"1"/"yes" on set
const BOOLEAN_KEYS = new Set([ const BOOLEAN_KEYS = new Set([
"enableGraph", "enableGraph",
"autoRecall", "autoRecall",
"autoCapture", "autoCapture",
"oss.disableHistory",
]); ]);
// Integer config fields — coerce to number on set // Integer config fields — coerce to number on set
const INTEGER_KEYS = new Set(["topK"]); const INTEGER_KEYS = new Set(["topK", "oss.vectorStore.config.port"]);
/** Resolve a user-facing key to the internal camelCase field name. */ /** Resolve a user-facing key to the internal camelCase field name. */
function resolveConfigKey(key: string): string | null { function resolveConfigKey(key: string): string | null {
@@ -989,6 +995,15 @@ export function registerCliCommands(
/** Read a config value by internal field name. */ /** Read a config value by internal field name. */
function getConfigValue(field: string): unknown { function getConfigValue(field: string): unknown {
if (field.startsWith("oss.")) {
const parts = field.split(".");
let current: unknown = cfg.oss;
for (let i = 1; i < parts.length && current != null; i++) {
current = (current as Record<string, unknown>)[parts[i]];
}
return current;
}
const auth = readPluginAuth(); const auth = readPluginAuth();
const values: Record<string, unknown> = { const values: Record<string, unknown> = {
apiKey: auth.apiKey ?? cfg.apiKey, apiKey: auth.apiKey ?? cfg.apiKey,
@@ -1027,20 +1042,37 @@ export function registerCliCommands(
.command("show") .command("show")
.description("Show current configuration") .description("Show current configuration")
.action(() => { .action(() => {
// Display order matching Python CLI: platform first, then defaults // Display order: general first, then mode-specific
const entries: Array<[string, string, string]> = [ const entries: Array<[string, string]> = [
["platform.api_key", "apiKey", ""], ["mode", "mode"],
["platform.email", "userEmail", ""], ["user_id", "userId"],
["defaults.user_id", "userId", ""], ["auto_recall", "autoRecall"],
["defaults.org_id", "orgId", ""], ["auto_capture", "autoCapture"],
["defaults.project_id", "projectId", ""], ["top_k", "topK"],
["defaults.enable_graph", "enableGraph", ""],
["defaults.auto_recall", "autoRecall", ""],
["defaults.auto_capture", "autoCapture", ""],
["defaults.top_k", "topK", ""],
["mode", "mode", ""],
]; ];
if (cfg.mode === "platform") {
entries.push(
["api_key", "apiKey"],
["email", "userEmail"],
["org_id", "orgId"],
["project_id", "projectId"],
["enable_graph", "enableGraph"],
);
} else {
entries.push(
["embedder_provider", "oss.embedder.provider"],
["embedder_model", "oss.embedder.config.model"],
["embedder_key", "oss.embedder.config.apiKey"],
["llm_provider", "oss.llm.provider"],
["llm_model", "oss.llm.config.model"],
["llm_key", "oss.llm.config.apiKey"],
["vector_provider", "oss.vectorStore.provider"],
["history_db_path", "oss.historyDbPath"],
["disable_history", "oss.disableHistory"],
);
}
// Calculate column widths // Calculate column widths
const maxKeyLen = Math.max( const maxKeyLen = Math.max(
...entries.map(([k]) => k.length), ...entries.map(([k]) => k.length),
@@ -1068,17 +1100,21 @@ export function registerCliCommands(
console.log(" openclaw mem0 config set <key> <value>"); console.log(" openclaw mem0 config set <key> <value>");
console.log(""); console.log("");
console.log(" Examples:"); console.log(" Examples:");
console.log(" openclaw mem0 config set mode open-source"); if (cfg.mode === "platform") {
console.log(" openclaw mem0 config set mode platform"); console.log(" openclaw mem0 config set mode open-source");
console.log(" openclaw mem0 config set auto_recall false"); console.log(" openclaw mem0 config set auto_recall false");
console.log(" openclaw mem0 config set top_k 10"); } else {
console.log(" openclaw mem0 config set vector_provider qdrant");
console.log(" openclaw mem0 config set llm_model gpt-4o");
console.log(" openclaw mem0 config set embedder_provider openai");
}
console.log(""); console.log("");
}); });
configCmd configCmd
.command("get") .command("get")
.description("Get a config value") .description("Get a config value")
.argument("<key>", "Config key (e.g. user_id, platform.api_key)") .argument("<key>", "Config key (e.g. user_id, api_key, llm_model)")
.action((key: string) => { .action((key: string) => {
const field = resolveConfigKey(key); const field = resolveConfigKey(key);
if (!field) { if (!field) {
@@ -1094,7 +1130,7 @@ export function registerCliCommands(
configCmd configCmd
.command("set") .command("set")
.description("Set a config value") .description("Set a config value")
.argument("<key>", "Config key (e.g. user_id, platform.api_key)") .argument("<key>", "Config key (e.g. user_id, api_key, llm_model)")
.argument("<value>", "New value") .argument("<value>", "New value")
.action((key: string, rawValue: string) => { .action((key: string, rawValue: string) => {
const field = resolveConfigKey(key); const field = resolveConfigKey(key);
@@ -1121,7 +1157,12 @@ export function registerCliCommands(
value = parsed; value = parsed;
} }
writePluginAuth({ [field]: value } as PluginAuthConfig); // Nested OSS fields use dot-path writer; flat fields use auth writer
if (field.startsWith("oss.")) {
writePluginConfigField(field.split("."), value);
} else {
writePluginAuth({ [field]: value } as PluginAuthConfig);
}
console.log( console.log(
`${key} = ${displayValue(field, value)}`, `${key} = ${displayValue(field, value)}`,
); );
openclaw/providers.ts
+30 -2
View File
@@ -254,10 +254,38 @@ class OSSProvider implements Mem0Provider {
const config: Record<string, unknown> = { version: "v1.1" }; const config: Record<string, unknown> = { version: "v1.1" };
if (this.ossConfig?.embedder) config.embedder = this.ossConfig.embedder; const defaultEmbedder = { provider: "openai", config: { model: "text-embedding-3-small" } };
const defaultLlm = { provider: "openai", config: { model: "gpt-5.4" } };
// Helper: strip empty-string values so they don't clobber defaults
const stripEmpty = (obj: Record<string, unknown>) => {
const out = { ...obj };
for (const k of Object.keys(out)) { if (out[k] === "") delete out[k]; }
return out;
};
if (this.ossConfig?.embedder) {
const ec = stripEmpty(this.ossConfig.embedder.config ?? {});
config.embedder = {
provider: this.ossConfig.embedder.provider || defaultEmbedder.provider,
config: { ...defaultEmbedder.config, ...ec },
};
} else {
config.embedder = defaultEmbedder;
}
if (this.ossConfig?.llm) {
const lc = stripEmpty(this.ossConfig.llm.config ?? {});
config.llm = {
provider: this.ossConfig.llm.provider || defaultLlm.provider,
config: { ...defaultLlm.config, ...lc },
};
} else {
config.llm = defaultLlm;
}
if (this.ossConfig?.vectorStore) if (this.ossConfig?.vectorStore)
config.vectorStore = this.ossConfig.vectorStore; config.vectorStore = this.ossConfig.vectorStore;
if (this.ossConfig?.llm) config.llm = this.ossConfig.llm;
if (this.ossConfig?.historyDbPath) { if (this.ossConfig?.historyDbPath) {
const dbPath = this.resolvePath const dbPath = this.resolvePath