MemoClaw OpenClaw Memory Plugin

@memoclaw/openclaw-memory lets OpenClaw use MemoClaw Product Memory through a MemoClaw API key. The API key is the isolation boundary: MemoClaw decides the tenant from the key, and OpenClaw fields such as workspaceId, sourceProduct, userId, sessionId, and agentId are treated as metadata.

By default the package does not automatically capture conversation text. It registers memory capabilities and performs recall when configured, but prompt and assistant-message capture require you to explicitly enable autoCapture. The ClawHub package is API-key only: it does not bundle the embedded local MemoClaw runtime, does not read transcript files from disk, and uses the OpenClaw/host fetch implementation for network requests.

Alpha Notice

This package is for technical Alpha testing. Do not paste real production API keys, real customer secrets, or sensitive private data into smoke tests or shared issue reports. Use a dedicated Alpha API key from the MemoClaw dashboard, revoke it when testing ends, and rotate it if it was copied into logs.

Install

Install from ClawHub:

openclaw --dev plugins install clawhub:@memoclaw/openclaw-memory

For local development from this repository:

cd src/adapters/openclaw
npm run build
npm pack
openclaw --dev plugins install ./memoclaw-openclaw-memory-2.0.6.tgz

The package can also be installed with npm when testing inside a Node-based OpenClaw host:

npm install @memoclaw/openclaw-memory

Hermes Support

MemoClaw also provides a Hermes memory provider plugin under src/adapters/hermes. Hermes users should use the GitHub repository or the standalone Hermes plugin repository after it is split out.

ClawHub remains the distribution channel for OpenClaw users installing @memoclaw/openclaw-memory.

Configuration

Create an API key in the MemoClaw dashboard, then configure OpenClaw:

openclaw --dev config set 'plugins.entries["@memoclaw/openclaw-memory"].enabled' true --strict-json
openclaw --dev config set 'plugins.entries["@memoclaw/openclaw-memory"].config.apiKey' '<USER_API_KEY>'
openclaw --dev config set 'plugins.entries["@memoclaw/openclaw-memory"].config.baseUrl' '<MEMOCLAW_API_URL>'
openclaw --dev config set 'plugins.entries["@memoclaw/openclaw-memory"].config.workspaceId' '<WORKSPACE_ID>'
openclaw --dev config set 'plugins.entries["@memoclaw/openclaw-memory"].config.sourceProduct' 'openclaw'
openclaw --dev config set 'plugins.entries["@memoclaw/openclaw-memory"].config.autoCapture' true --strict-json
openclaw --dev config set 'plugins.entries["@memoclaw/openclaw-memory"].config.capturePolicy' 'salient'
openclaw --dev config set 'plugins.entries["@memoclaw/openclaw-memory"].config.autoRecall' true --strict-json
openclaw --dev config set 'plugins.entries["@memoclaw/openclaw-memory"].config.topK' 5 --strict-json
openclaw --dev config set 'plugins.entries["@memoclaw/openclaw-memory"].hooks.allowConversationAccess' true --strict-json
openclaw --dev config set 'plugins.slots.memory' '@memoclaw/openclaw-memory'

Configuration reference:

The ClawHub package reads configuration from OpenClaw plugin config only. It does not read credentials from shell environment variables, does not start a local HTTP server, does not read local transcript files, does not include local database mode, and does not send hidden telemetry.

OpenClaw Config File

The slot path is plugins.slots.memory.

module.exports = {
  plugins: {
    entries: {
      '@memoclaw/openclaw-memory': {
        enabled: true,
        hooks: {
          allowConversationAccess: true
        },
        config: {
              apiKey: '<USER_API_KEY>',
              baseUrl: '<MEMOCLAW_API_URL>',
          workspaceId: '<WORKSPACE_ID>',
          sourceProduct: 'openclaw',
          autoCapture: true,
          capturePolicy: 'salient',
          autoRecall: true,
          topK: 5
        }
      }
    },
    slots: {
      memory: '@memoclaw/openclaw-memory'
    }
  }
};

For OpenClaw versions that gate raw conversation hooks, hooks.allowConversationAccess must be enabled before conversation capture can work. Without autoCapture: true, the plugin will not subscribe to prompt, assistant, or transcript capture hooks.

Hosts that expose native capability registration can call the package register(openclaw, options) entrypoint. The plugin registers a Product Memory capability with:

• capture / store for writing product events into MemoClaw.
• recall, retrieve, and getContext for fetching Product Memory context bundles.
• flush as a no-op compatibility method for OpenClaw memory adapters that expect it.

Product Memory Flow

Capture requests are sent to POST /api/product-memory/events and context requests are sent to POST /api/product-memory/context. The adapter always sends the API key as X-Api-Key.

When autoCapture is explicitly enabled, the adapter can capture user prompts and final assistant answers:

• User prompts use sourceType: openclaw_prompt_message.
• Final assistant answers use sourceType: openclaw_assistant_reply.
• With the default capturePolicy: salient, low-value turns such as short acknowledgements or "continue" prompts are skipped before they become long-term memory. Important preferences, setup decisions, install/configuration steps, smoke markers, and structured fact/decision events are still stored.
• Set capturePolicy: all only when you are debugging capture/backfill and intentionally want raw conversation retention.

Workspace Files vs MemoClaw

OpenClaw workspace files such as MEMORY.md are injected directly into the system prompt every turn. Use them for small, explicit, hand-maintained notes that should always be visible to the model.

MemoClaw Product Memory is external long-term memory. It recalls context on demand and applies MemoClaw Context Policy before injecting a MemoClaw Product Memory Context block. The plugin logs startup, recall counts, policy mode, and capture skips/captures so users can tell MemoClaw is active without confusing it with workspace-file memory.

Do not let MemoClaw automatically rewrite MEMORY.md. If a fact should always be present, pin it manually in workspace files; otherwise let MemoClaw store it as Product Memory with source, workspace, role, and session metadata.

The /context endpoint is intentionally generic. OpenClaw does not need Codex-specific routes: any plugin with a valid API key can ask MemoClaw for a scoped context bundle.

Smoke Test

Start the MemoClaw bridge in one terminal:

npm run local:codex-bridge

Then run the OpenClaw plugin smoke script from the MemoClaw repository:

npm run local:openclaw-smoke -- --api-key '<USER_API_KEY>' --base-url 'http://127.0.0.1:3100' --workspace-id 'demo-openclaw' --json

The smoke path verifies:

• prompt capture: a user-style OpenClaw event is imported into Product Memory.
• assistant capture: the plugin can capture final assistant text when allowConversationAccess is enabled.
• context recall: recall, retrieve, and getContext can request a Product Memory context bundle for the same API-key tenant.

Useful flags:

• --json: print the raw capture, recall, and retrieve result payloads.
• --expect-context: fail when the recall call returns no context bundle.

Example:

npm run local:openclaw-smoke -- --json --expect-context

Context Policy

Product Memory Context Policy still decides whether a context bundle may be returned. A smoke run can capture successfully and still recall an empty bundle when policy is in preview-only mode or the source/workspace is not allowed for live context.

Use --expect-context only when the current Product Memory Context Policy is configured to allow OpenClaw live context for the target workspace. Do not bypass policy checks in the plugin.

Privacy

MemoClaw stores Product Memory events for the tenant associated with the API key. Treat workspaceId, sourceProduct, userId, sessionId, and agentId as metadata, not authorization. Revoking an API key stops future plugin requests made with that key.

For Alpha testing, use synthetic conversations or clearly approved test data. Do not include real private user messages in GitHub issues, screenshots, or smoke-test examples.

FAQ

Can I change workspaceId to read another user's memory?

No. Tenant isolation is enforced by MemoClaw from the API key. workspaceId only scopes metadata and Context Policy inside the same tenant.

Capture works but recall returns an empty context.

Check Product Memory Context Policy. Empty context is expected when live context is disabled or the OpenClaw source/workspace is not allowlisted.

Where is the release package built from?

Run npm pack in src/adapters/openclaw. The package whitelist keeps the ClawHub/npm-pack artifact focused on the OpenClaw adapter files and avoids bundling tests, build output, or old tarballs.

Packaging Metadata

openclaw.plugin.json declares this package as a memory plugin and marks apiKey as sensitive. package.json also exposes openclaw.extensions.memoclaw metadata so OpenClaw package discovery can identify the Product Memory capability without loading user secrets.