Memoxxx OpenClaw Plugin

Memoxxx OpenClaw Plugin gives OpenClaw long-term memory.

It can:

1. Recall relevant memories before the model answers.
2. Write useful conversation turns back to Memoxxx after a run.
3. Let you review recalled memories and label recall quality in a local Review UI.
4. Optionally include tool calls and tool results in written memories.

Install

Install from a local checkout during development:

openclaw plugins install --link /path/to/memoxxx-openclaw-plugin
openclaw gateway restart

After the package is published, install it from npm:

openclaw plugins install @wangbren/memoxxx-openclaw-plugin@latest
openclaw gateway restart

Installing the npm package with npm install is not enough by itself. OpenClaw must register the plugin through openclaw plugins install; otherwise an enabled config entry can still produce plugin not found.

Verify Installation

After installing and restarting the gateway, verify that OpenClaw loaded the plugin:

openclaw plugins inspect memoxxx-openclaw-plugin
openclaw plugins list | grep memoxxx

Expected:

Status: loaded

If you see:

plugin not found: memoxxx-openclaw-plugin

the plugin package may exist on disk, but it has not been registered with OpenClaw. Install it through OpenClaw:

openclaw plugins install @wangbren/memoxxx-openclaw-plugin@latest
openclaw gateway restart

If you already installed the package into a local node_modules path, register that directory instead:

openclaw plugins install /path/to/node_modules/@wangbren/memoxxx-openclaw-plugin
openclaw gateway restart

Basic Setup

The plugin reads configuration from:

1. ~/.openclaw/openclaw.json
2. ~/.openclaw/.env

Values in openclaw.json take priority over .env.

Minimal .env:

MEMOXXX_BASE_URL=http://localhost:8000
MEMOXXX_API_KEY=sk_xxx
MEMOXXX_USER_ID=user_123

MEMOXXX_API_KEY and MEMOXXX_USER_ID are required for recall/add. The plugin can appear loaded without them, but memory recall and writeback are disabled until both are configured.

For first-time setup, the local Config UI is usually the easiest path. After installing and restarting the gateway, open the URL printed in the gateway log:

[memoxxx] config ui ready: http://127.0.0.1:12345

Use that page to set baseUrl, apiKey, userId, recall/writeback options, telemetry, and Review UI settings. The same local server also exposes the recall review page:

http://127.0.0.1:<port>/memoxxx/review

After you run conversations with recall enabled, the Review UI shows reviewable recall turns and lets you label each recalled memory as useful, inaccurate, should not remember, irrelevant, or skipped. Use this during initial rollout to check whether recall quality is healthy before relying on automatic writeback.

Minimal plugin config in ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "memoxxx-openclaw-plugin": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": true
        },
        "config": {
          "baseUrl": "http://localhost:8000",
          "recallEnabled": true,
          "addEnabled": true,
          "recallOutputMode": "summary",
          "topK": 6
        }
      }
    }
  }
}

Only enable hooks.allowConversationAccess if you trust this plugin. It allows the plugin to read conversation content so it can write memories back to Memoxxx and power recall review.

Restart OpenClaw after changing config:

openclaw gateway restart

What Happens During Use

On each model run:

1. OpenClaw calls the plugin before building the prompt.
2. The plugin searches Memoxxx with the latest user request.
3. Relevant memories are inserted into the prompt as a structured <memories> block.
4. After the run ends, the plugin writes the selected conversation content back to Memoxxx.

By default, writeback captures the latest user turn and assistant reply.

Common Options

| Option | Default | What it does | |---|---:|---| | recallEnabled | true | Search Memoxxx before model generation. | | addEnabled | true | Write conversation content back to Memoxxx after a run. | | topK | 6 | Number of memories to recall. | | recallOutputMode | "summary" | Search output shape. Use "summary" for folded unit summaries or "facts" for atomic fact rows. | | scoreThreshold | 0 | Optional client-side score filter. Keep 0 unless your backend returns stable scores. | | captureStrategy | "last_turn" | Use "last_turn" or "full_session" for writeback. | | includeAssistant | true | Include assistant text in writeback. | | includeToolMessages | false | Include assistant tool calls and tool results in writeback. | | maxMessageChars | 20000 | Per-message truncation length for writeback. | | writebackBufferEnabled | true | Buffer agent_end writeback by session before sending add requests. | | writebackBufferMaxTurns | 8 | Flush the session writeback buffer after this many turns. | | writebackBufferMaxAgeMs | 300000 | Flush the session writeback buffer after this many milliseconds. | | recallGlobal | true | When false, recall only within the current session. |

Example with tool messages enabled:

{
  "includeToolMessages": true,
  "captureStrategy": "last_turn"
}

Tool messages are written as assistant text because the current Memoxxx add API accepts user and assistant roles. Example generated content:

[tool_call] name=browser id=call_1 arguments={"action":"tabs"}
[tool_result] name=browser id=call_1 content=tab list

Config UI

When the OpenClaw gateway starts, the plugin tries to launch a local config page on 127.0.0.1.

Look for a log line like:

[memoxxx] config ui ready: http://127.0.0.1:12345

The config page edits plugin settings in ~/.openclaw/openclaw.json. It does not create Memoxxx API keys.

For initial setup, use this page to configure the Memoxxx connection and enable recall review. Then open:

http://127.0.0.1:<port>/memoxxx/review

The review page is for labeling recall results after real conversations. It does not write feedback into the OpenClaw transcript.

Multi-Agent Use

Use multi-agent mode when one OpenClaw deployment runs multiple agents and each agent needs different memory behavior.

{
  "multiAgentMode": true,
  "allowedAgents": ["planner", "coder"],
  "agentOverrides": {
    "planner": {
      "topK": 3,
      "recallGlobal": false
    },
    "coder": {
      "addEnabled": false
    }
  }
}

Rules:

1. allowedAgents controls which agents can use the plugin.
2. agentOverrides only applies after the agent is allowed.
3. In multi-agent mode, the default agent id main is treated as the host default and is not injected into recall filters.

Optional Lifecycle Hooks

These hooks are disabled by default:

| Option | Hook | Purpose | |---|---|---| | hookMessageReceivedEnabled | message_received | Warm up recall from raw user input. | | hookSessionStartEnabled | session_start | Prefetch stable user preferences. | | hookBeforeCompactionEnabled | before_compaction | Capture transcript before compaction. | | hookSessionEndEnabled | session_end | Write a session snapshot. |

For session-end capture, set:

{
  "sessionEndWriteMode": "summary"
}

Allowed values are "summary", "full", and "both".

Recall Feedback

The plugin can capture quick feedback on the previous recall result.

By default, short exact messages such as these are recognized:

| Message | Meaning | |---|---| | 召回正确 | Previous recall was useful/correct. | | 召回错误 | Previous recall was wrong/not useful. |

You can customize the trigger strings with comma-separated config values:

{
  "recallFeedbackMatchMode": "equal",
  "recallFeedbackPositivePatterns": "召回正确,这次召回是对的,recall correct",
  "recallFeedbackNegativePatterns": "召回错误,这次召回错了,recall wrong"
}

recallFeedbackMatchMode can be "equal" or "include". Negative matches are checked first.

When triggered, the plugin reports feedback and ends that turn without sending the message to the model.

Recall Review UI

The plugin also records recalled memories into a local review store and marks them reviewable after agent_end. Open the config UI server's review page:

http://127.0.0.1:<port>/memoxxx/review

The page shows reviewable turns and lets you mark each recalled memory as useful, inaccurate, should not remember, irrelevant, or skipped. Start each review from the displayed query: confirm the query matches the conversation turn you want to inspect, optionally expand the assistant reply for context, then label each recalled memory against that query. Feedback is stored in recallReviewLocalPath; non-skip ratings are also reported through the recall feedback sink. To send these labels to the server, set telemetrySink to "remote" or "both" and configure clientJsonLogEndpoint / clientJsonLogApiKey when the defaults from baseUrl / apiKey are not enough.

Related config:

{
  "recallReviewEnabled": true,
  "recallReviewUiEnabled": true,
  "recallReviewLocalPath": "",
  "recallReviewLimit": 20,
  "recallReviewPollMs": 3000
}

Filters

Confirmed useful filter fields:

1. session_id
2. agent_id
3. app_id

Example:

{
  "filter": {
    "and": [
      { "app_id": "planner-app" },
      { "session_id": { "eq": "session-1" } }
    ]
  }
}

create_time and update_time are not recommended yet because some backend versions return errors for datetime filters.

CLI Helper

This repo also ships a small helper CLI.

Do not rely on memoxxx-cli being on PATH after an OpenClaw plugin install. Path installs, link installs, and package installs do not always expose npm bin shims to agent shells.

First find the plugin install directory:

openclaw plugins info memoxxx-openclaw-plugin

Then invoke the bundled script by absolute path:

node /path/to/memoxxx-openclaw-plugin/scripts/memoxxx.mjs --print-effective-config

Search only:

node /path/to/memoxxx-openclaw-plugin/scripts/memoxxx.mjs --query-only --query "concise answers preference"

Mark the latest pending recall as feedback:

node /path/to/memoxxx-openclaw-plugin/scripts/memoxxx.mjs --recall-feedback negative
node /path/to/memoxxx-openclaw-plugin/scripts/memoxxx.mjs --recall-feedback positive

If you are already inside the plugin root, npm run memoxxx -- ... is also fine for local debugging:

npm run memoxxx -- --print-effective-config
npm run memoxxx -- --recall-feedback negative

To enable the shorter memoxxx-cli command in your own terminal, install or link the npm package so npm creates the bin shim:

# Local development
cd /path/to/memoxxx-openclaw-plugin
npm link

# Then verify
command -v memoxxx-cli
memoxxx-cli --help

For published package usage:

npm install -g @wangbren/memoxxx-openclaw-plugin
memoxxx-cli --help

OpenClaw plugin install and npm CLI install are separate concerns: OpenClaw loads the plugin hooks, while npm global/link install exposes the terminal command.

Skills

The plugin exposes two OpenClaw skills:

| Skill | Use it for | |---|---| | memoxxx | Searching existing memories. | | memoxxx-feedback | Marking the previous recall as correct or wrong through the CLI. |

The CLI is recall/feedback only. New memory writes are handled by the plugin lifecycle writeback path, not by manual CLI commands. Keep feedback separate from normal memory writes; the feedback skill can mark the latest pending recall through the CLI.

Development And Debugging

Run tests:

npm test

Run smoke test against a live Memoxxx service:

MEMOXXX_BASE_URL=http://localhost:8000 \
MEMOXXX_API_KEY=sk_xxx \
npm run smoke

Telemetry defaults:

| Option | Default | |---|---| | telemetryEnabled | true | | telemetryMode | "meta" | | telemetrySink | "local" | | telemetryLocalPath | ~/.openclaw/logs/memoxxx-telemetry.jsonl |

When remote telemetry is enabled, daily telemetry events are wrapped as client JSON logs and sent to /v1/telemetry/client-json-logs.

Recall feedback local output remains separate, but remote feedback uses the same client JSON log endpoint:

| Sink | Destination | |---|---| | local | ~/.openclaw/logs/memoxxx-recall-feedback.jsonl | | remote | /v1/telemetry/client-json-logs |

Use telemetrySink: "local", "remote", or "both".

Troubleshooting

Plugin is enabled in config but OpenClaw says plugin not found

This means the config entry exists, but the plugin is not registered in OpenClaw's plugin registry.

Run:

openclaw plugins install @wangbren/memoxxx-openclaw-plugin@latest
openclaw gateway restart
openclaw plugins inspect memoxxx-openclaw-plugin

Plugin is loaded but recall/add does not work

Check the gateway logs:

tail -200 ~/.openclaw/logs/gateway.err.log | grep memoxxx
tail -200 ~/.openclaw/logs/gateway.log | grep memoxxx

If you see missing credential warnings, configure:

MEMOXXX_BASE_URL=http://localhost:8000
MEMOXXX_API_KEY=sk_xxx
MEMOXXX_USER_ID=user_123

or set equivalent values in plugins.entries.memoxxx-openclaw-plugin.config.

Writeback or recall review is blocked

For non-bundled plugins, OpenClaw may require explicit conversation access:

{
  "plugins": {
    "entries": {
      "memoxxx-openclaw-plugin": {
        "hooks": {
          "allowConversationAccess": true
        }
      }
    }
  }
}

Only enable this if you trust the plugin, because it allows the plugin to read conversation content.

Related Documents

1. Chinese README: README_ZH.md
2. Install guide: INSTALL.md
3. Memoxxx API snapshot: api_tutorial.md
4. Tool writeback API notes: TOOL_MESSAGE_WRITE_API.md
5. Recall feedback API notes: recall-feedback-api.md