OpenClaw MindMemOS Memory Plugin

This package connects OpenClaw to MindMemOS through the local mindmemos SDK CLI. It is intentionally thin: OpenClaw provides hook events, and the plugin shells out to the same CLI that users can run by hand.

What it does

• Before each prompt is built, it searches MindMemOS with mindmemos memory search and prepends matching memories inside a <relevant-memories> block.
• After a successful agent turn, it stores the last user turn and the messages that followed it with mindmemos memory add.
• When the stored turn includes OpenClaw tool-call text for read, write, or edit on a SKILL.md path, it passes SDK-compatible skill context to memory add with --skill-context-json.

The plugin does not manage credentials, does not talk directly to the HTTP API, and does not update local skill files by itself. Authentication, memory API calls, skill registration, skill update, rollback, history, and diff are owned by the Python SDK and its mindmemos CLI.

Requirements

• OpenClaw with plugin API support compatible with >=2026.6.6.
• A working mindmemos CLI from the Python SDK.
• A configured SDK profile:

uv run mindmemos auth
uv run mindmemos doctor

If you install the SDK outside this repository, use the installed command instead:

mindmemos auth
mindmemos doctor

mindmemos doctor checks local config and transport readiness. A real memory round trip can also be checked with:

mindmemos memory search "hello" --json

Install

Published package:

openclaw plugins install @mindmemos/openclaw-plugin
openclaw plugins enable mindmemos-memory

Local source checkout:

cd /path/to/packages/openclaw-plugin
npm install
npm run build

openclaw plugins install --link /path/to/packages/openclaw-plugin
openclaw plugins enable mindmemos-memory

Installing with --link points OpenClaw at this source directory, so future npm run build runs are picked up without reinstalling.

Do not install src/ or src/index.ts directly. OpenClaw expects the native plugin manifest at the package root (openclaw.plugin.json). This is a native hook plugin, so openclaw plugins validate for simple defineToolPlugin plugins is not the right validation path for it.

Grant conversation access

The plugin must read conversation messages in order to persist them at agent_end. The package manifest requests conversation access, but OpenClaw requires an explicit entry-level grant for non-bundled plugins installed from npm or linked from a local checkout:

openclaw config set plugins.entries.mindmemos-memory.hooks.allowConversationAccess true
openclaw gateway restart

Without this grant, the pre-prompt recall hook can still work, but the agent_end storage hook is blocked by the gateway.

Configuration

Optional plugin config:

{
  "enabled": true,
  "cli": "mindmemos",
  "topK": 5,
  "addMode": "async",
  "userId": "optional-user-override",
  "appId": "openclaw",
  "sessionId": "optional-session-override",
  "minQueryLength": 2,
  "maxConversationMessages": 80
}

Fields:

| Field | Default | Description | | --- | --- | --- | | enabled | true | Disable the plugin without uninstalling it. | | cli | mindmemos | Command spawned by the OpenClaw gateway. Prefer an absolute path when OpenClaw does not inherit your shell PATH. | | topK | 5 | Number of memories requested from memory search. | | addMode | async | async passes --async to memory add; sync waits for extraction to finish. | | userId | SDK default | Optional user override passed to search and add. | | appId | openclaw | App scope passed to search and add. | | sessionId | derived | Optional fixed session override. Otherwise the plugin derives one from OpenClaw event/context fields. | | minQueryLength | 2 | Skip recall for very short prompts. | | maxConversationMessages | 80 | Maximum number of trailing messages persisted from the last turn. |

Example with an absolute CLI path:

openclaw config set plugins.entries.mindmemos-memory.config.cli \
  /path/to/repo/.venv/bin/mindmemos
openclaw gateway restart

The .venv/bin/mindmemos shim has an absolute-path shebang, so it can run without activating the virtual environment. A wrapper such as uv run mindmemos can also work, but only if the gateway can resolve uv and runs from the expected repository directory.

Data flow

Recall flow:

OpenClaw before_prompt_build
  -> extract prompt or latest user message
  -> mindmemos memory search <query> --top-k <topK> --json --app-id <appId> --session-id <sessionId>
  -> prepend formatted <relevant-memories> context

Store flow:

OpenClaw agent_end after a successful run
  -> collect the last user message and following assistant/tool messages
  -> normalize them to MindMemOS dialogue messages
  -> mindmemos memory add --messages-json-file - --json --metadata-json '{"source":"openclaw-plugin"}'
  -> add --async, --user-id, --app-id, --session-id, and --skill-context-json when configured/detected

In subagent sessions, recognized by a session key containing :subagent:, the recalled memory block is marked as background context so the subagent does not assume it is the user.

Captured messages

OpenClaw transcripts can contain conversational messages and internal harness artifacts. The plugin stores the conversational subset:

• user messages.
• assistant messages.
• assistant tool calls, serialized inline as [tool_call] <name>(<json args>) on the assistant message.
• toolResult / tool_result messages, mapped to the generic tool role.

Internal OpenClaw artifacts are intentionally dropped before storage, including heartbeat messages and async command completion/status messages. The system prompt is not persisted as part of the transcript.

Skill context

The SDK now has first-class skill management commands:

mindmemos skill register <skill_dir_or_SKILL.md> --alias <alias>
mindmemos skill list
mindmemos skill show <skill>
mindmemos skill pull <skill>
mindmemos skill push <skill>
mindmemos skill update <skill|--all> --yes
mindmemos skill rollback <skill> --to <version_id> --yes
mindmemos skill history <skill>
mindmemos skill diff <skill> --to <version_id>
mindmemos skill unregister <skill>

This OpenClaw plugin complements that system. If a turn includes tool-call text for read, write, or edit on a SKILL.md path, the plugin extracts the skill content from the same messages it sends to memory add, computes the SDK-compatible content hash, and sends a skill context array with:

• name
• content_hash
• base_version_id
• optional version_label
• usage as injected or modified

That gives MindMemOS enough context to bind memories to the skill version that OpenClaw loaded or modified, without requiring this plugin to parse OpenClaw's private trace files or mutate local skill directories.

Useful SDK commands

The plugin relies on the memory commands below, and they are also useful for debugging:

mindmemos config show
mindmemos doctor

mindmemos memory search "query" --top-k 5 --json
mindmemos memory add --content "remember this" --role user --json
mindmemos memory add --messages-json '[{"role":"user","content":"hello","timestamp":0}]' --json
mindmemos memory get --filter '{"app_id":"openclaw"}' --top-k 20
mindmemos memory update <memory_id> --content "new content"
mindmemos memory delete <memory_id> --yes
mindmemos memory feedback --text "explicit correction"
mindmemos memory dreaming

The plugin specifically uses:

• memory search <query> --top-k ... --json --app-id ... --session-id ...
• memory add --messages-json-file - --json --metadata-json ...
• optional --async, --user-id, --app-id, --session-id, and --skill-context-json.

Troubleshooting

mindmemos not found

The cli command is spawned by the OpenClaw gateway process. Desktop apps, launch agents, and service managers often do not inherit the same PATH as your interactive shell, so mindmemos may work in a terminal but fail inside OpenClaw with spawn mindmemos ENOENT.

Use an absolute path:

which mindmemos
openclaw config set plugins.entries.mindmemos-memory.config.cli /absolute/path/to/mindmemos
openclaw gateway restart

Then run a turn and check that the gateway log no longer contains ENOENT.

Recall works but nothing is stored

If logs show recall activity such as:

[mindmemos] recall hit N memories, injected M chars

but never show:

[mindmemos] stored N message(s) from last turn

check for an OpenClaw warning like:

typed hook "agent_end" blocked because non-bundled plugins must set
plugins.entries.mindmemos-memory.hooks.allowConversationAccess=true

Fix it with:

openclaw config set plugins.entries.mindmemos-memory.hooks.allowConversationAccess true
openclaw gateway restart

Storage only runs at agent_end, so it appears after the next completed turn, not while a turn is still running.

Search or add fails

CLI errors are logged by the gateway as:

[mindmemos] memory search failed: ...
[mindmemos] memory add failed: ...

Run the same operation manually with the configured CLI path:

/absolute/path/to/mindmemos config show
/absolute/path/to/mindmemos doctor
/absolute/path/to/mindmemos memory search "test" --json

If addMode is async, the plugin can only observe CLI-level enqueue failures. Server-side processing errors that happen after the CLI exits need to be checked in MindMemOS service logs or worker observability.