mr-memory

Persistent memory for OpenClaw, powered by MemoryRouter.

mr-memory is an AI agent memory plugin that gives OpenClaw relevant context from prior conversations. It retrieves memory before agent/model input and captures the direct user-to-assistant exchange after each run, so useful context remains available across sessions, compaction, and model changes.

Use it when you want OpenClaw memory that does not restart from zero every session. Historical workspace and session data stays opt-in through an explicit upload command.

Install

openclaw plugins install npm:[email protected]

The explicit npm: source and version make the audited install deterministic. [email protected] is published on npm. A ClawHub listing has not been verified and is not required for this path.

Setup

openclaw mr <your-memory-key>   # Get a key at memoryrouter.ai
openclaw mr upload               # Upload workspace + session history

Commands

openclaw mr status           # Vault stats
openclaw mr upload           # Upload workspace + sessions
openclaw mr upload --brain ~/.notopenclaw   # Upload from a different agent
openclaw mr off              # Disable
openclaw mr delete           # Clear vault
openclaw mr <key>            # Enable with key
openclaw mr low              # Up to 21 memories (12 raw + 6 tier 2 + 3 tier 3)
openclaw mr medium           # Up to 43 memories (25 + 12 + 6), balanced default
openclaw mr high             # Up to 87 memories (50 + 25 + 12)

Memory Density

The current density choices are low, medium, and high. New installs and configs without an explicit density use medium, the balanced default. Existing explicit low or high settings are unchanged. Legacy xhigh configs remain valid so upgrades do not break the gateway, but the plugin normalizes xhigh to high and no longer advertises it as a current option.

The totals are tier-aware retrieval budgets, not raw-memory-only limits. Actual results can be lower when fewer relevant memories match.

Upload Options

openclaw mr upload [path]              # Specific file or directory
openclaw mr upload --workspace <dir>   # Custom workspace directory
openclaw mr upload --brain <dir>       # Custom state dir (sessions from another agent)

Historical Import (agent-driven)

Import existing OpenClaw conversation history with a strict division of labor: the server owns the extraction prompt (versioned, fetched at import time), your agent owns discovery/parsing of the local session files, and the CLI owns transport. The agent never uploads; the CLI never parses history.

openclaw mr import --instructions        # print the server's extraction prompt for your agent
openclaw mr import --file extract.jsonl  # validate, preview, price quote, approve, upload
openclaw mr import --file extract.jsonl --yes   # non-interactive approval
openclaw mr import --dismiss             # permanently silence the import nudge

Guarantees: the extract is validated locally (four fields per record, openclaw: prefixed ids, epoch-ms timestamps); the CLI shows record count, date range, estimated tokens, and the server price quote and requires explicit approval before any write; the import id is content-derived and every batch carries an Idempotency-Key, so re-running after any interruption replays committed batches for free and resumes. Duplicates are never re-billed. The memory key never appears in the prompt or the extract file. When a vault is new, injected context includes a one-line import suggestion until an import completes or you --dismiss.

Agent Tools

The plugin registers these tools for the agent:

• memory_search: semantic search across the vault. Supports tiers and importance filters; only reflections (tiers 2 and 3) carry importance ratings.
• memory_date_search: time-window retrieval for questions like "what happened last week" or "most important things this month". Takes concrete ISO from/to dates, optional query for in-window relevance ranking, plus tiers and importance filters.
• memory_get: safe snippet read from local memory files.
• memory_reflect / memory_commit: consolidate raw memories into reflections (checkout and commit pair).
• memory_inspect: read-only consolidation lineage for a memory id.

How It Works

When enabled, relay hooks retrieve memory before agent/model input and capture the direct user-to-assistant conversation at agent_end. Inference and provider API keys remain inside OpenClaw; the plugin does not route provider calls through MemoryRouter and is not a provider-key proxy.

Only direct user-to-AI conversation is stored. Tool use, subagent work, and internal processing are excluded. Historical workspace/session upload is a separate explicit openclaw mr upload operation; installing or enabling the relay does not imply an import already happened.

Keep-warm

Retrieval is fastest against a warm vault, so the plugin keeps yours warm for 3 minutes after each message. Every message re-opens that window; once it lapses with no new activity the warmup timer is cleared entirely, so an idle agent sends no background warmup traffic. There is no startup ping and no always-on keepalive.

Tune it with keepWarmMs (milliseconds, default 180000; 0 disables warmup pings):

{ "plugins": { "entries": { "mr-memory": { "config": { "keepWarmMs": 180000 } } } } }

Automatic consolidation (default on)

MemoryRouter's Reflection Hierarchy consolidates raw memories into higher-tier reflections. The server tracks consolidation debt per vault; when a retrieval response reports debt above the server's threshold, this plugin consolidates automatically:

• It starts a dedicated isolated agent turn through the OpenClaw gateway (a background subagent session, never your main conversation) whose only instruction is to call the plugin's memory_reflect and memory_commit tools. Your agent's model writes the reflections, so the inference is your own model spend; MemoryRouter never calls a provider.
• At most 3 batches per trigger, with a fresh debt check between batches; the run stops when debt drops below the threshold. The threshold always comes from the server response.
• A machine-wide lockfile (~/.memoryrouter/consolidate.lock, stale after 20 minutes) prevents double-firing across sessions and across other MemoryRouter connectors on the same machine, and a 30 minute cooldown follows each completed run.
• The consolidation session is excluded from memory capture/injection and its transcript is deleted afterward. Failures never surface in your conversation; everything is logged to ~/.memoryrouter/consolidate.log.
• MemoryRouter bills the consolidation checkout/commit tokens at the normal 1x raw rate.

Opt out with "autoConsolidate": false in the plugin config (restart the gateway to apply). The in-context consolidation hint and the memory_reflect/memory_commit agent tools keep working; only the automatic background trigger is disabled:

{ "plugins": { "entries": { "mr-memory": { "config": { "autoConsolidate": false } } } } }

Config

After openclaw mr <key>, config is stored at:

{
  "plugins": {
    "entries": {
      "memoryrouter": {
        "enabled": true,
        "config": {
          "key": "mk_xxx",
          "endpoint": "https://api.memoryrouter.ai"
        }
      }
    }
  }
}

Cross-AI and MCP Memory

The OpenClaw plugin uses relay hooks. Separately, the same MemoryRouter vault can connect to supported ChatGPT, Claude, Claude Code, Codex, and compatible MCP clients. Each host follows its own integration contract. Hosted ChatGPT and Claude connectors are model-directed, do not passively capture every conversation, and do not import old conversations just by connecting.

See the cross-AI and MCP memory guide for supported setup paths, permissions, verification steps, and host-specific limits.

Public Links

• MemoryRouter
• MemoryRouter app
• Documentation
• OpenClaw memory guide
• Pricing
• Support
• Public MemoryRouter SDK repository
• MemoryRouter on LinkedIn
• Founder GitHub profile

License

MIT