Maximem Memory Plugin for OpenClaw

Persistent, cross-channel memory for OpenClaw (formerly MoltBot / ClawdBot) agents. Memories captured on Slack are recallable from Telegram, WhatsApp, Discord, and every other channel your agent runs on.

The plugin itself is stateless — all storage and retrieval happens on the Maximem backend. You bring an API key; the plugin handles the rest.

What you get

• Auto-recall — relevant memories are injected into the agent's context before each turn (before_agent_start hook, runs early).
• Auto-capture — conversations are stored after each turn (agent_end hook, debounced).
• Slash commands — /remember <text> and /recall <query> work in any chat channel that supports plugin commands.
• Agent tools — opt-in maximem_store, maximem_search, maximem_forget for LLM-driven memory operations.
• CLI — openclaw maximem search/stats/wipe/help for terminal-based memory management.

Quickstart

1. Install

openclaw plugins install @maximem/memory-plugin

2. Set your API key

Get a key from app.maximem.ai. Then either:

# Recommended — environment variable (env > config for sensitive values)
export MAXIMEM_API_KEY="mx_..."

Or, if you prefer a config file, edit ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "memory-plugin": {
        "enabled": true,
        "config": { "apiKey": "mx_..." }
      }
    }
  }
}

3. Verify

openclaw plugins doctor
openclaw maximem search "ping" --limit 1   # light round-trip; needs a valid key

If both succeed, you're done. Auto-recall and auto-capture are on by default.

Slash commands

Slash commands work in any chat channel where OpenClaw dispatches plugin commands (Telegram, Slack, WhatsApp, Discord, and other auto-reply-pipeline channels).

/remember

Save information to long-term memory.

/remember My favorite programming language is TypeScript
/remember Project deadline is March 15, 2026 --importance high
/remember I prefer dark themes for IDEs --category preference

Trailing flags (all optional):

| Flag | Values | Default | Notes | |---|---|---|---| | --importance | low \| medium \| high | high | Explicit /remembers are treated as high-importance signals; opt down with --importance medium for casual notes. | | --category | preference \| fact \| task \| relationship \| context | inferred by backend | Forces a category instead of letting the backend infer one. |

Flags must appear at the end of the message and only known flag names are consumed — text like remember to run with --legacy-peer-deps is preserved intact.

/recall

Search long-term memory.

/recall favorite programming language
/recall budget --limit 10
/recall preferences --min-score 0.5

Trailing flags (all optional):

| Flag | Values | Default | Notes | |---|---|---|---| | --limit | integer 1–20 | 5 (configurable) | Max results to return. | | --min-score | number 0.0–1.0 | 0.3 (configurable) | Minimum relevance score; lower for broader recall. |

Defaults come from recallSlashLimit and recallSlashMinScore config options (see Configuration below).

CLI commands

The plugin registers an openclaw maximem namespace.

openclaw maximem search <query>

openclaw maximem search "favorite color"
openclaw maximem search "deadlines" --limit 20
openclaw maximem search "preferences" --category preference --json

| Flag | Values | Default | |---|---|---| | -l, --limit <n> | integer 1–20 (clamped to 20 with a stderr warning if higher) | 10 | | -c, --category <cat> | preference \| fact \| task \| relationship \| context | none | | --json | output as JSON | off |

Invalid --limit values (abc, 0, -3, 1.5) and unknown --category values are rejected client-side before any API call.

openclaw maximem stats

Report the number of memories on the account.

openclaw maximem stats
# Memories on this account: 1000+ (capped — see dashboard for exact total)

Implementation note: the backend currently doesn't expose a dedicated /stats endpoint, so this is implemented as a count via the forget dry-run path. Counts above 1000 are reported as 1000+ (capped) until a real stats endpoint is available — see the dashboard at app.maximem.ai for an exact total.

openclaw maximem wipe

Delete all memories on the account.

openclaw maximem wipe --dry-run         # preview the count without deleting
openclaw maximem wipe                   # interactive confirmation
openclaw maximem wipe --yes             # skip confirmation

Use with care. There is no undo.

openclaw maximem help

Print the setup-and-usage cheat sheet.

openclaw maximem help

Agent tools

The plugin ships three optional, LLM-callable tools. They're opt-in — add them to your agent's allowlist to enable.

{
  "agents": {
    "list": [{
      "id": "main",
      "tools": {
        "allow": ["maximem_store", "maximem_search", "maximem_forget"]
      }
    }]
  }
}

maximem_store

Store information in long-term memory.

| Param | Type | Notes | |---|---|---| | text | string (required) | Up to 10,000 characters. | | category | enum | preference, fact, task, relationship, context. | | importance | enum | low, medium, high. |

Returns isError: true if the backend reports stored: false, so your agent can react instead of treating a partial failure as success.

maximem_search

Search long-term memory.

| Param | Type | Notes | |---|---|---| | query | string (required) | Natural-language query. | | limit | number | Default 5, clamped to 20. | | category | enum | Filter by category. |

maximem_forget

Delete memories. Defaults to dryRun: true as a safety guard against an LLM mass-deleting memory by mistake. Pass dryRun: false explicitly to actually delete.

| Param | Type | Notes | |---|---|---| | query | string | Query to match memories to delete. Omit to target all. | | dryRun | boolean | Default true. Set false to delete for real. |

Configuration

All options live under plugins.entries["memory-plugin"].config in ~/.openclaw/openclaw.json. Environment variables take precedence for sensitive values (apiKey).

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | — | Maximem API key. Prefer the MAXIMEM_API_KEY env var. | | endpoint | string | https://agenticrouter-prod.maximem.ai | API base URL. Override for dev/staging. | | autoRecall | boolean | true | Inject relevant memories before each agent turn. | | autoCapture | boolean | true | Capture conversations after each agent turn. | | maxRecallTokens | number (100–10000) | 1000 | Token budget for injected recall context. | | minPromptLength | number | 5 | Skip recall for prompts shorter than this. | | captureDebounceMs | number | 2000 | Debounce window for batching agent_end events. | | recallSlashLimit | number (1–20) | 5 | Default --limit for /recall when no flag is passed. | | recallSlashMinScore | number (0–1) | 0.3 | Default --min-score for /recall when no flag is passed. |

Setting the API key per-shell

zsh:

echo 'export MAXIMEM_API_KEY="mx_..."' >> ~/.zshrc && source ~/.zshrc

bash:

echo 'export MAXIMEM_API_KEY="mx_..."' >> ~/.bashrc && source ~/.bashrc

Windows PowerShell:

[System.Environment]::SetEnvironmentVariable("MAXIMEM_API_KEY", "mx_...", "User")

Cross-channel behaviour

/remember records the source channel (ctx.channel) as metadata on the memory entry. /recall and auto-recall search across all channels — memories captured on Telegram are recallable from Slack and vice versa. This is intentional. Channel is metadata, not a filter.

If the channel scoping ever becomes configurable, it'll be opt-in with explicit documentation.

Troubleshooting

/recall finds nothing even though I just /remember-ed something

This is most likely a backend index lag or a backend search issue, not a plugin bug. Try:

1. Wait 10–30 seconds and retry — there can be brief indexing latency between store and search.
2. Lower the relevance threshold: /recall <query> --min-score 0.1 or openclaw maximem search "<query>" --limit 20.
3. Check the dashboard at app.maximem.ai to confirm the memory persisted.
4. If the dashboard shows the memory but /recall still returns nothing, that's a backend search issue worth reporting at the support links below.

/remember says "Failed to store memory"

The backend may have returned a 5xx error. Try again in a few seconds. If failures persist, the request ID is logged at error level in the gateway logs (openclaw logs) — include it when reporting.

/remember says "Memory was not stored. Please try again."

The backend acknowledged the request but reported stored: false. This usually means a duplicate was deduplicated, or a backend-side validation rejected the content. Try storing slightly different text or check the dashboard.

openclaw maximem search returns "Search failed: HTTP 422"

You probably passed an invalid query — empty string, or whitespace only. The plugin guards against --limit and --category issues client-side; this 422 is the backend rejecting the query body itself.

openclaw plugins info memory-plugin shows duplicates

If you see entries like Tools: maximem_store, maximem_store, ..., you're on plugin version <0.4.0. Upgrade to ≥0.4.0 (openclaw plugins update).

Slash commands aren't firing in openclaw agent --local or openclaw tui

Plugin slash commands are dispatched per-channel by OpenClaw — Telegram, Discord, and channels routed through the auto-reply pipeline (Slack/WhatsApp/etc.) all dispatch them. The local agent CLI and TUI currently don't, so openclaw agent --local --message "/recall foo" sends /recall foo straight to the LLM as a chat message. This is a known OpenClaw core gap — track upstream at moltbot/moltbot.

For local development, you can drive the slash handlers directly via a small Node harness — see docs for the pattern.

Backend status (known limitations)

Some product features depend on the Maximem backend. As of plugin v0.4.0:

• Search retrieval can return empty for queries that should match. If /recall and openclaw maximem search consistently return nothing for queries that match content visible in your dashboard, this is a backend search issue. Surface area: /v1/memory/search.
• /store may return 500 even when the memory persists. The plugin reports failure faithfully; check the dashboard to see whether the data actually saved.
• auto-capture may return captured: 0 even on valid input, depending on backend extraction state. Auto-recall therefore depends on what was successfully captured to-date.
• maximem stats and wipe --dry-run counts are capped at 1000 by the backend. The plugin labels this honestly (1000+ (capped)).

The Maximem team is actively working on fixes for these. The plugin will surface improvements as soon as the backend ships them — no plugin upgrade should be needed for backend bug fixes alone.

Versioning

The plugin follows semver. Breaking changes (CLI flag changes that break scripts, config-key removals, API-contract bumps) trigger a minor version bump until 1.0.0.

See CHANGELOG.md.

Support

• Docs: www.maximem.ai/openclaw
• Issues (plugin-side): GitHub Issues
• Issues (OpenClaw core / channels): moltbot/moltbot
• Email: [email protected]