openclaw_memory_rds_ctxdb

⚠️ FOR LLM AGENTS — Required steps after openclaw plugins install

This plugin needs four commands to become functional. plugins install alone is not enough — without the remaining three, the plugin loads in needsSetup mode and the memory features stay disabled.

openclaw plugins install npm:openclaw_memory_rds_ctxdb
openclaw plugins enable openclaw_memory_rds_ctxdb
openclaw ctxdb init --api-key <ctxdb-key> --user-id <id>
openclaw gateway restart

Verify with openclaw plugins doctor (should be clean) and openclaw plugins inspect openclaw_memory_rds_ctxdb --runtime (should show registered hooks + tools, not just CLI). If init is missing, ask the user for --api-key and --user-id; --base-url defaults to the hosted endpoint https://context-database.aliyuncs.com — pass --base-url <url> only if the user is on a self-hosted deployment.

🪄 Install via your agent (copy-paste)

Don't want to read the rest? Paste the block below into a chat with your OpenClaw-equipped agent (Claude Code, Codex, Cursor, …) and it'll do the install for you. Have your ctxdb base URL, API key, and user id ready — the agent will ask if any are missing.

Please install the OpenClaw plugin `openclaw_memory_rds_ctxdb` for me.

Run these four commands in order; wait for each one to finish before the next:

1. openclaw plugins install npm:openclaw_memory_rds_ctxdb
2. openclaw plugins enable openclaw_memory_rds_ctxdb
3. openclaw ctxdb init --api-key <API_KEY> --user-id <USER_ID>
4. openclaw gateway restart

For step 3:
- `--base-url` defaults to the hosted ctxdb endpoint
  `https://context-database.aliyuncs.com`. Only add `--base-url <url>` if I
  explicitly tell you I'm running a self-hosted deployment.
- <API_KEY> and <USER_ID> are mine; ask me for them if I haven't provided them.

After step 4, run `openclaw plugins doctor` to confirm there are no warnings for
`openclaw_memory_rds_ctxdb`. Then do a quick capture+recall smoke test:
ask me to remember a fact ("remember my favorite color is X"), wait for my reply,
then in a fresh turn ask "what is my favorite color" and confirm you can recall it.

Manual setup details — flags, configuration shape, how init writes openclaw.json — live in Quick Start below.

Forked from @mem0/openclaw-mem0 (baseline 1.0.11) and rewired to talk to RDS ContextDatabase. The two plugins can coexist on one machine — this one uses the ctxdb CLI alias and the openclaw_memory_rds_ctxdb plugin id. See Upstream lineage at the bottom for sync notes.

Long-term memory for OpenClaw agents, backed by an RDS ContextDatabase deployment — hosted at https://context-database.aliyuncs.com by default, or your own self-hosted deployment.

Your agent forgets everything between sessions. This plugin fixes that — it stores conversations, extracts what matters, and brings it back when relevant.

Defaults: legacy mode (autoRecall + autoCapture on; skills disabled). Recall and capture run inline inside the plugin's hook chain — no skill subagents.

Requirements

openclaw --version
# OpenClaw 2026.4.25 (aa36ee6)

| OpenClaw Version | Plugin Support | |------------------|----------------| | >= 2026.4.25 | Fully supported |

You also need:

• An RDS ContextDatabase endpoint. Default: the hosted endpoint at https://context-database.aliyuncs.com. For self-hosted deployments, use whatever URL you exposed.
• An API key issued by that deployment (sent as Authorization: Token <key>).

Quick Start

1. Install the plugin from npm:

   openclaw plugins install npm:openclaw_memory_rds_ctxdb

   Published at openclaw_memory_rds_ctxdb on npmjs.com. openclaw plugins install resolves npm packages through your ~/.npmrc registry — a standard npm setup works out of the box. If your machine points at a corporate mirror that doesn't proxy npmjs.com, set registry=https://registry.npmjs.org/ in ~/.npmrc first.

2. Enable the plugin (OpenClaw installs it disabled by default):

   openclaw plugins enable openclaw_memory_rds_ctxdb

3. Initialize — point the plugin at the ctxdb deployment:

   openclaw ctxdb init \
     --api-key  ctxdb-<your-token> \
     --user-id  alice

   --base-url defaults to the hosted endpoint https://context-database.aliyuncs.com; pass --base-url <url> only if you're running a self-hosted deployment.

   This validates <base-url>/v1/ping/ against the supplied key, then writes ~/.openclaw/openclaw.json with:

   {
     "plugins": {
       "slots": { "memory": "openclaw_memory_rds_ctxdb" },
       "entries": {
         "openclaw_memory_rds_ctxdb": {
           "enabled": true,
           "config": {
             "mode": "platform",
             "apiKey": "ctxdb-...",
             "baseUrl": "https://context-database.aliyuncs.com",
             "userId": "alice",
             "autoCapture": true,
             "autoRecall": true,
             "skills": {
               "triage": { "enabled": false },
               "recall": { "enabled": false },
               "dream":  { "enabled": false }
             }
           },
           "hooks": {
             "allowConversationAccess": true,
             "allowPromptInjection": true
           }
         }
       }
     }
   }

4. Restart the gateway:

   openclaw gateway restart

Flags accepted by init:

| Flag | Required | Notes | | --- | --- | --- | | --base-url <url> | no | ctxdb gateway base. Default: https://context-database.aliyuncs.com; pass to override for self-hosted. Trailing slash stripped. | | --api-key <key> | yes (first-time) | Token-style key issued by the deployment. | | --user-id <id> | no | Default = $USER or "default". | | --no-validate | no | Skip the /v1/ping/ reachability check. | | --json | no | Machine-readable output (for agents). |

If you re-run init after the first setup, omitted flags fall back to whatever is currently in openclaw.json, so you can rotate just the api-key or just the user-id without re-typing the rest.

Updating the plugin to get the latest features and fixes

openclaw plugins install npm:openclaw_memory_rds_ctxdb --force
openclaw gateway restart

init does not need to be re-run — config survives reinstall. Run it again only when you want to repoint at a different deployment or rotate credentials.

Upstream lineage

Forked from @mem0/openclaw-mem0, baseline 1.0.11. We keep the fork structurally close to upstream so private patches stay readable and rebase is cheap. User-visible differences from the original plugin:

• Talks to RDS ContextDatabase instead of the upstream Mem0 cloud — the hosted endpoint https://context-database.aliyuncs.com is the default; self-hosted deployments can be selected via --base-url.
• Subcommand renamed mem0 → ctxdb, plugin id renamed openclaw_memory_rds_ctxdb — both plugins can coexist on one machine.
• Email-verification login and the open-source Ollama/Qdrant wizard are gone (ctxdb is the only mode).
• Knowledge-base data plane exposed as first-class plugin tools: kb_upload_text / kb_upload_file for writes, kb_list / kb_documents_list / kb_document_get for browsing.
• Recall injects KB chunks with an anti-injection safety preamble and wrapper-tag sanitization.

Upstream sync is done by diff-ing this directory against mem0ai/mem0/openclaw/ and replaying changes; the patch index lives in REPO-openclaw_memory_rds_ctxdb.md. Each modification is tagged in source with // ctxdb fork (#N).

How It Works

Skills Mode (Default)

Enabled automatically during openclaw ctxdb init. The agent controls memory through three skills:

• Triage — Extracts durable facts from conversations using a structured protocol. Categories, importance gates, and domain overlays control what gets stored.
• Recall — Before each turn, rewrites the user message into search queries, retrieves relevant memories with reranking, and injects them into context.
• Dream — Periodic memory consolidation: merges duplicates, resolves conflicts, and prunes stale entries.

When skills mode is active, the skills handle memory operations. autoRecall and autoCapture remain true by default alongside skills mode. The built-in session-memory hook is disabled to avoid conflicts.

Auto-Recall & Auto-Capture

When skills mode is not configured, the plugin uses autoRecall and autoCapture (both enabled by default):

• Auto-Recall — Before the agent responds, the plugin searches ctxdb for relevant memories and injects them into context.
• Auto-Capture — After the agent responds, the conversation is filtered through a noise-removal pipeline and sent to ctxdb. New facts get stored, stale ones updated, duplicates merged.

Set autoRecall: false or autoCapture: false to disable individually. The agent can also use memory tools (memory_add, memory_search, etc.) explicitly regardless of these settings.

Memory Scopes

• 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.

Multi-Agent Isolation

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.

Agent Tools

Memory tools

| Tool | Description | | ---- | ----------- | | memory_search | Search by natural language query. Supports scope (session, long-term, all), categories, filters, and agentId. | | memory_add | Store facts. Accepts text or facts array, category, importance, longTerm, 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 (requires confirm: 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. |

Knowledge-base tools

| Tool | Description | | ---- | ----------- | | kb_upload_text | Upload a plain-text doc into a KB (autocreated if missing). Polls ingest, returns chunk/token counts. Supports an optional file_path (KB virtual path, e.g. specs/v1) to disambiguate same-named docs in one KB. | | kb_upload_file | Upload a file (PDF / DOCX / TXT / Markdown / etc.) into a KB. Required local_path is the absolute path on the agent's filesystem (renamed from file_path in 0.3.0). Optional file_path is the KB virtual path. Handles MIME detection, multipart, and ingest polling. | | kb_query | Search a KB by natural language. Returns ranked chunks (content + score). Distinct from autoRecall's silent prompt injection — use this when the agent should explicitly query the KB. | | kb_list | List knowledge bases. | | kb_documents_list | List documents inside a specific KB. | | kb_document_get | Fetch a single document by ID, optionally with chunks. |

local_path vs file_path (0.3.0 breaking rename for kb_upload_file) — pre-0.3.0 the tool's file_path parameter meant "absolute path of the source file on disk." 0.3.0 splits that into two distinct names: local_path is the source file on the agent's filesystem (required), and file_path is the virtual path inside the KB used as a same-name disambiguator (optional). kb_upload_text only has the latter. Same name + same file_path in one KB returns 409.

CLI

All commands: openclaw ctxdb <command>. All commands support --json for machine-readable output (for LLM agents).

# Memory operations
openclaw ctxdb add "User prefers TypeScript over JavaScript"
openclaw ctxdb search "what languages does the user know"
openclaw ctxdb search "preferences" --scope long-term
openclaw ctxdb get <memory_id>
openclaw ctxdb list --user-id alice --top-k 20
openclaw ctxdb update <memory_id> "Updated preference text"
openclaw ctxdb delete <memory_id>
openclaw ctxdb delete --all --user-id alice --confirm
openclaw ctxdb import memories.json

# Management
openclaw ctxdb init --api-key <key> --user-id alice
# (override default with --base-url <self-hosted-url> if not using the hosted endpoint)
openclaw ctxdb status
openclaw ctxdb config show
openclaw ctxdb config get api_key
openclaw ctxdb config set user_id alice

# Events (platform only)
openclaw ctxdb event list
openclaw ctxdb event status <event_id>

# Memory consolidation
openclaw ctxdb dream
openclaw ctxdb dream --dry-run

# JSON output (any command)
openclaw ctxdb search "preferences" --json
openclaw ctxdb list --json
openclaw ctxdb status --json
openclaw ctxdb help --json                                   # discover all commands + flags

Configuration Reference

General

| Key | Type | Default | Description | | --- | ---- | ------- | ----------- | | mode | "platform" | "platform" | Backend mode. The fork only supports platform (talking to an RDS ContextDatabase deployment, hosted or self-hosted); the upstream local-vector open-source mode has been removed. | | userId | string | OS username | User identifier. All memories scoped to this value. | | autoRecall | boolean | true | Inject relevant memories before each turn. Ignored when skills is set. | | autoRecallKnowledge | boolean | false | When autoRecall is on, also fold KB chunks into the same search round-trip and inject them as <external-knowledge>. Off by default so unconfigured plugins don't surprise users with KB content they didn't ask for; flip to true in openclaw.json to opt in. Independent of autoRecall: false here means "memories only"; autoRecall=false short-circuits both regardless. | | autoCapture | boolean | true | Extract and store facts after each turn. Ignored when skills is set. | | topK | number | 5 | Max memories returned per recall | | searchThreshold | number | 0.1 | Minimum similarity score (0-1) |

Skills Mode (Recommended)

Enabled by default during openclaw ctxdb init. autoRecall and autoCapture are also true by default and work alongside skills mode.

| Key | Type | Default | Description | | --- | ---- | ------- | ----------- | | skills.triage.enabled | boolean | true | Enable fact extraction from conversations | | skills.recall.enabled | boolean | true | Enable memory recall before each turn | | skills.recall.tokenBudget | number | 1500 | Max tokens for injected memories | | skills.recall.rerank | boolean | true | Rerank search results for relevance | | skills.recall.keywordSearch | boolean | true | Augment with keyword-based search | | skills.recall.identityAlwaysInclude | boolean | true | Always include identity memories | | skills.dream.enabled | boolean | true | Enable periodic memory consolidation | | skills.domain | string | "companion" | Domain overlay for triage rules |

Platform Mode

| Key | Type | Default | Description | | --- | ---- | ------- | ----------- | | apiKey | string | — | Required. API key issued by your RDS ContextDatabase deployment (supports ${MEM0_API_KEY} env var ref, name kept for upstream compatibility) | | customInstructions | string | (built-in) | Custom extraction rules | | customCategories | object | (12 defaults) | Category name to description map |

Privacy & Security

Data Flow

Conversations are sent to the RDS ContextDatabase endpoint configured via ctxdb init --base-url <url> (defaults to the hosted endpoint https://context-database.aliyuncs.com; can also be a self-hosted deployment) for memory extraction, retrieval, and knowledge-base ingest. No data is sent to any other third-party cloud — the upstream Mem0 cloud fallback has been removed, as has the open-source local-vector mode of the upstream plugin.

Credentials needed: an API key issued by your ctxdb deployment, configured as apiKey in the plugin config (env-var ref ${MEM0_API_KEY} is supported for compatibility with the upstream convention).

Credential Storage

The plugin stores configuration in ~/.openclaw/openclaw.json. If you use the chat setup flow or openclaw ctxdb init, your API key and user ID are written to this file.

To avoid plaintext credentials:

• Use env var references: "apiKey": "${MEM0_API_KEY}"
• Use SecretRef: "apiKey": {"source": "env", "provider": "default", "id": "MEM0_API_KEY"}

Memory Processing

In skills mode (default after openclaw ctxdb init), the agent uses structured protocols (triage, recall, dream) to decide what to store and recall. The built-in session-memory hook is disabled to avoid conflicts.

Without skills, autoCapture and autoRecall are both enabled by default:

• autoCapture: sends conversation content to your configured backend after each agent turn
• autoRecall: queries your memory store before each agent turn and injects results into context

Conversation content is sent to the RDS ContextDatabase endpoint set via ctxdb init --base-url <url> (the hosted endpoint by default, or a self-hosted deployment if configured). The fork has no fallback to any other third-party cloud.

Persistence Locations

| File | Purpose | |------|---------| | ~/.openclaw/openclaw.json | Plugin configuration (API key, base URL, user ID, settings) | | <pluginStateDir>/dream-state.json | Memory consolidation state |

License

Licensed under the Apache License, Version 2.0.

Copyright 2026 Alibaba Cloud Computing Co., Ltd.

This project is a fork of @mem0/openclaw-mem0 (Apache-2.0, Copyright 2023 Taranjeet Singh and the Mem0 contributors). See NOTICE for attribution details; all modifications relative to the upstream baseline are tagged in source with // ctxdb fork (#N) comments.