Openclaw-memory

OpenClaw memory plugin backed by the Agentic Memory API — provides long-term semantic memory and skill management for your agents.

Features

• MCP-based tools: Memory, Skill and Knowledgebase tools are provided via MCP server configuration
• Auto-recall: Injects relevant memories (and optionally skills) before each agent execution
• Auto-capture: Stores conversation highlights after each agent execution
• CLI commands: mem search|get|update|forget|task
• Zero native dependencies: Uses Node.js built-in fetch() — no SDK required

Get your API token

1. Sign up at https://opensearch.console.aliyun.com/cn-shanghai/rag/server-market if you haven't already
2. Go to api-keys
3. Click Create API Key, copy the api token (starts with OS-) and endpoint (e.g. http://xxx.platform-cn-shanghai.opensearch.aliyuncs.com)
4. These two values (api token, endpoint) will be used in the following configuration

Installation

1. Install the plugin:

    openclaw plugins install @alicloud-ai-search/openclaw-memory

2. Change your ~/.openclaw/openclaw.json: Add the following to your plugins.entries.openclaw-memory:

    "config": {
      "baseUrl": "http://xxx.platform-cn-shanghai.opensearch.aliyuncs.com",
      "workspaceName": "{YOUR_WORKSPACE_HERE}",
      "apiKey": "{YOUR_API_KEY_HERE}"
    }

   So that the complete config should look like this:

    "openclaw-memory": {
      "enabled": true,
        "config": {
          "baseUrl": "http://xxx.platform-cn-shanghai.opensearch.aliyuncs.com",
          "workspaceName": "default",
          "apiKey": "YOUR_API_KEY_HERE"
        }
    }

MCP Configuration

Memory tools are provided via an MCP server. Add the following mcp section to your ~/.openclaw/openclaw.json:

  "mcp": {
    "servers": {
      "agentic-memory": {
        "url": "<YOUR_ENDPOINT>/v1/agentic-memory/mcp",
        "transport": "streamable-http", 
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }

Replace <YOUR_ENDPOINT> with your Agentic Memory API base URL and <token> with your API key.

3. Restart the gateway after all configuration is complete:

   openclaw gateway restart

   You should see in the logs:

   [openclaw-memory] Plugin registered (autoRecallMemory=true, autoCaptureMemory=true, autoRecallSkill=false, autoCaptureSkill=false, ...)

Configuration

| Option | Type | Default | Required | Description | |--------|------|---------|----------|-------------| | baseUrl | string | http://localhost:8000 | yes | Agentic Memory API base URL | | workspaceName | string | — | yes | Workspace Name | | apiKey | string | — | yes | Agentic Memory API key | | serviceId | string | agentic-memory | no | Service ID for the memory service | | userId | string | auto-generated | no | A string you choose to uniquely identify the user whose memories are being stored. If not set, a persistent UUID is auto-generated (see below) | | agentId | string | "" | no | Agent ID (optional, associates memories/skills with a specific agent) | | autoCaptureMemory | boolean | false | no | Store conversation context after agent execution | | autoRecallMemory | boolean | false | no | Inject relevant memories before agent execution | | autoRecallSkill | boolean | false | no | Include skills in auto-recall results | | autoCaptureSkill | boolean | false | no | (Coming soon) Auto-capture skills from conversations | | recallLimit | number | 5 | no | Max items to recall per query |

Auto-generated userId

When userId is not set in the plugin config, the plugin automatically generates and persists one:

1. It looks for a file called autogen-userid.txt in the ~/.openclaw directory.
2. If the file exists, its content is read and used as the userId.
3. If the file does not exist, a new openclaw-memory-<UUID> string is generated, written to autogen-userid.txt, and used as the userId.

Whenever an auto-generated userId is used (whether newly created or read from an existing file), a log line is printed:

[openclaw-memory] Using auto-generated userId from /path/to/autogen-userid.txt: openclaw-memory-xxx

To switch to a manually configured userId, simply add "userId": "your-id" to the plugin config — the autogen-userid.txt file will then be ignored.

CLI Commands

# Search memories (optionally include skills)
openclaw mem search "project architecture"
openclaw mem search "project architecture" --limit 10 --skill

# Get a memory or skill by ID
openclaw mem get <id>

# Update a memory's content by ID
openclaw mem update <id> "new memory content"

# Delete a memory or skill
openclaw mem forget <id>

# Check async task status
openclaw mem task <task_id>

How Auto-Recall Works

When autoRecallMemory is enabled, the plugin hooks into before_agent_start:

1. The user's prompt is used as a search query against the Agentic Memory API

2. Up to recallLimit memories (and skills, if autoRecallSkill is enabled) are retrieved

3. They are prepended to the agent context as:

   <relevant-memories>
   Relevant facts from long-term memory:
   - Some stored fact
   - Another relevant memory
   
   Relevant skills:
   - skill-name: description of the skill
   </relevant-memories>

4. Temporary sessions (session keys starting with temp:) and start prompts are skipped

How Auto-Capture Works

When autoCaptureMemory is enabled, the plugin hooks into agent_end:

1. User and assistant messages from the conversation are extracted
2. Messages shorter than 50 characters are skipped
3. Messages containing <relevant-memories> are skipped (prevents feedback loops)
4. Start prompts (A new session was started via...) are skipped
5. Temporary sessions are skipped
6. Remaining messages are sent to the Agentic Memory API for extraction and storage