Feature: Add OpenClaw plugin and documentation (#3964)

2026-02-02 10:04:08 -08:00
parent dba7f0458a
commit 3d3e875d21
8 changed files with 1944 additions and 13 deletions
@@ -0,0 +1,3 @@
+node_modules/
+package-lock.json
+*.db
@@ -0,0 +1,155 @@
+# @mem0/openclaw-mem0
+
+Long-term memory for [OpenClaw](https://github.com/openclaw/openclaw) agents, powered by [Mem0](https://mem0.ai).
+
+Your agent forgets everything between sessions. This plugin fixes that. It watches conversations, extracts what matters, and brings it back when relevant — automatically.
+
+## How it works
+
+<p align="center">
+  <img src="../docs/images/openclaw-architecture.png" alt="Architecture" width="800" />
+</p>
+
+**Auto-Recall** — Before the agent responds, the plugin searches Mem0 for memories that match the current message and injects them into context.
+
+**Auto-Capture** — After the agent responds, the plugin sends the exchange to Mem0. Mem0 decides what's worth keeping — new facts get stored, stale ones updated, duplicates merged.
+
+Both run silently. No prompting, no configuration, no manual calls.
+
+### Short-term vs long-term memory
+
+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 and automatically recalled alongside long-term memories.
+
+- **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.
+
+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.
+
+The agent tools (`memory_search`, `memory_list`) 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.
+
+All new parameters are optional and backward-compatible — existing configurations work without changes.
+
+## Setup
+
+```bash
+openclaw plugins install @mem0/openclaw-mem0
+```
+
+### Platform (Mem0 Cloud)
+
+Get an API key from [app.mem0.ai](https://app.mem0.ai), then add to your `openclaw.json`:
+
+```json5
+// plugins.entries
+"openclaw-mem0": {
+  "enabled": true,
+  "config": {
+    "apiKey": "${MEM0_API_KEY}",
+    "userId": "your-user-id"
+  }
+}
+```
+
+### Open-Source (Self-hosted)
+
+No Mem0 key needed. Requires `OPENAI_API_KEY` for default embeddings/LLM.
+
+```json5
+"openclaw-mem0": {
+  "enabled": true,
+  "config": {
+    "mode": "open-source",
+    "userId": "your-user-id"
+  }
+}
+```
+
+Sensible defaults 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" } }
+  }
+}
+```
+
+All `oss` fields are optional. See [Mem0 OSS docs](https://docs.mem0.ai/open-source/node-quickstart) for providers.
+
+## Agent tools
+
+The agent gets five 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 |
+
+## CLI
+
+```bash
+# Search all memories (long-term + session)
+openclaw mem0 search "what languages does the user know"
+
+# Search only long-term memories
+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
+
+# Stats
+openclaw mem0 stats
+```
+
+## Options
+
+### General
+
+| Key | Type | Default | |
+|-----|------|---------|---|
+| `mode` | `"platform"` \| `"open-source"` | `"platform"` | Which backend to use |
+| `userId` | `string` | `"default"` | 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 |
+| `searchThreshold` | `number` | `0.3` | Min similarity (0–1) |
+
+### Platform mode
+
+| Key | Type | Default | |
+|-----|------|---------|---|
+| `apiKey` | `string` | — | **Required.** Mem0 API key (supports `${MEM0_API_KEY}`) |
+| `orgId` | `string` | — | Organization ID |
+| `projectId` | `string` | — | Project ID |
+| `enableGraph` | `boolean` | `false` | Entity graph for relationships |
+| `customInstructions` | `string` | *(built-in)* | Extraction rules — what to store, how to format |
+| `customCategories` | `object` | *(12 defaults)* | Category name → description map for tagging |
+
+### Open-source mode
+
+Works with zero extra config. The `oss` block lets you swap out any component:
+
+| Key | Type | Default | |
+|-----|------|---------|---|
+| `customPrompt` | `string` | *(built-in)* | Extraction prompt for memory processing |
+| `oss.embedder.provider` | `string` | `"openai"` | Embedding provider (`"openai"`, `"ollama"`, etc.) |
+| `oss.embedder.config` | `object` | — | Provider config: `apiKey`, `model`, `baseURL` |
+| `oss.vectorStore.provider` | `string` | `"memory"` | Vector store (`"memory"`, `"qdrant"`, `"chroma"`, etc.) |
+| `oss.vectorStore.config` | `object` | — | Provider config: `host`, `port`, `collectionName`, `dimension` |
+| `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 |
+
+Everything inside `oss` is optional — defaults use OpenAI embeddings (`text-embedding-3-small`), in-memory vector store, and OpenAI LLM. Override only what you need.
+
+## License
+
+Apache 2.0
@@ -0,0 +1,168 @@
+{
+  "id": "openclaw-mem0",
+  "kind": "memory",
+  "uiHints": {
+    "mode": {
+      "label": "Mode",
+      "help": "\"platform\" for Mem0 cloud, \"open-source\" for self-hosted"
+    },
+    "apiKey": {
+      "label": "Mem0 API Key",
+      "sensitive": true,
+      "placeholder": "m0-...",
+      "help": "API key from app.mem0.ai (or use ${MEM0_API_KEY}). Only needed for platform mode."
+    },
+    "userId": {
+      "label": "Default User ID",
+      "placeholder": "default",
+      "help": "User ID for scoping memories"
+    },
+    "orgId": {
+      "label": "Organization ID",
+      "placeholder": "org-...",
+      "advanced": true
+    },
+    "projectId": {
+      "label": "Project ID",
+      "placeholder": "proj-...",
+      "advanced": true
+    },
+    "autoCapture": {
+      "label": "Auto-Capture",
+      "help": "Automatically store conversation context after each agent turn"
+    },
+    "autoRecall": {
+      "label": "Auto-Recall",
+      "help": "Automatically inject relevant memories before each agent turn"
+    },
+    "customInstructions": {
+      "label": "Custom Instructions",
+      "placeholder": "Only store user preferences and important facts...",
+      "help": "Natural language rules for what Mem0 should store or exclude (platform mode)"
+    },
+    "customCategories": {
+      "label": "Custom Categories",
+      "advanced": true,
+      "help": "Map of category names to descriptions for memory tagging (platform mode only). Sensible defaults are built in."
+    },
+    "customPrompt": {
+      "label": "Custom Prompt (Open-Source)",
+      "advanced": true,
+      "help": "Custom prompt for open-source mode memory extraction."
+    },
+    "enableGraph": {
+      "label": "Enable Graph Memory",
+      "help": "Enable Mem0 graph memory for entity relationships (platform mode only)"
+    },
+    "searchThreshold": {
+      "label": "Search Threshold",
+      "placeholder": "0.5",
+      "help": "Minimum similarity score for search results (0-1). Default: 0.5"
+    },
+    "topK": {
+      "label": "Top K Results",
+      "placeholder": "5",
+      "help": "Maximum number of memories to retrieve"
+    },
+    "oss": {
+      "label": "Open-Source Configuration",
+      "advanced": true,
+      "help": "Optional. Configure custom embedder, vector store, LLM, or history DB for open-source mode. Has sensible defaults — only override what you need."
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "mode": {
+        "type": "string",
+        "enum": [
+          "platform",
+          "open-source",
+          "oss"
+        ]
+      },
+      "apiKey": {
+        "type": "string"
+      },
+      "userId": {
+        "type": "string"
+      },
+      "orgId": {
+        "type": "string"
+      },
+      "projectId": {
+        "type": "string"
+      },
+      "autoCapture": {
+        "type": "boolean"
+      },
+      "autoRecall": {
+        "type": "boolean"
+      },
+      "customInstructions": {
+        "type": "string"
+      },
+      "customCategories": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "string"
+        }
+      },
+      "customPrompt": {
+        "type": "string"
+      },
+      "enableGraph": {
+        "type": "boolean"
+      },
+      "searchThreshold": {
+        "type": "number"
+      },
+      "topK": {
+        "type": "number"
+      },
+      "oss": {
+        "type": "object",
+        "properties": {
+          "embedder": {
+            "type": "object",
+            "properties": {
+              "provider": {
+                "type": "string"
+              },
+              "config": {
+                "type": "object"
+              }
+            }
+          },
+          "vectorStore": {
+            "type": "object",
+            "properties": {
+              "provider": {
+                "type": "string"
+              },
+              "config": {
+                "type": "object"
+              }
+            }
+          },
+          "llm": {
+            "type": "object",
+            "properties": {
+              "provider": {
+                "type": "string"
+              },
+              "config": {
+                "type": "object"
+              }
+            }
+          },
+          "historyDbPath": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "required": []
+  }
+}
@@ -0,0 +1,23 @@
+{
+  "name": "@mem0/openclaw-mem0",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Mem0 memory backend for OpenClaw — platform or self-hosted open-source",
+  "license": "Apache-2.0",
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "memory",
+    "mem0",
+    "long-term-memory"
+  ],
+  "dependencies": {
+    "@sinclair/typebox": "0.34.47",
+    "mem0ai": "^2.2.1"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}