OpenClaw Supermemory: Cloud-Backed Long-Term Memory for OpenClaw Agents

What OpenClaw Supermemory actually adds to an agent

An OpenClaw agent without a memory slot starts every turn with whatever is in the current context window. Anything said last week is gone. OpenClaw Supermemory plugs into that gap by registering itself as the memory plugin and then running two hooks around each AI turn. The README describes the result as automatic: conversations are remembered, relevant context is recalled, and a persistent user profile is built over time.

The target user is someone running a personal or small-team OpenClaw bot who wants continuity without operating a database, an embedding pipeline, or a retrieval service. The README is explicit that everything runs in the cloud and that no local infrastructure is required. That is the whole value proposition, and it is also the whole constraint: the plugin does not ship a local index, so if the Supermemory API is unreachable, there is no fallback path described in the documentation.

The README also states that a Supermemory Pro subscription or above is required. That is a hard gate, not a soft recommendation, and it sits in a blockquote near the top of the page.

Auto-recall and auto-capture: the two hooks that do the work

The mechanism is easier to reason about than the marketing language suggests. Two hooks bracket each turn.

Auto-recall runs before the AI turn. It queries Supermemory for memories relevant to the current conversation and injects them as context. According to the README, the model sees the user profile plus semantically similar past conversations. The number of injected memories is capped by maxRecallResults, which defaults to 10. Separately, profileFrequency controls how often the full profile is injected, and it defaults to 50, meaning the profile lands in context every fiftieth turn rather than on every turn. That split is a sensible cost control: a profile is large, and injecting it each turn would burn context for little gain.

Auto-capture runs after the AI turn. The conversation is sent to Supermemory, which extracts and stores what it considers worth keeping. The extraction, deduplication and profile building all happen server-side, which is why the plugin has so few moving parts locally. The repository layout matches that picture: hooks/, tools/, commands/, plus a client.ts and a memory.ts. There is no vector store directory, no embedding model, no migration folder.

One detail worth reading twice is captureMode. The default is "all", which the README says filters short texts. Setting it to "everything" captures all. If you are debugging why an offhand remark never came back in a later session, captureMode is the first setting to check, before you suspect the search path.

Installing the OpenClaw Supermemory plugin and running a first recall

Installation is a single plugin command. The package name is scoped, so it must be quoted exactly as written.

openclaw plugins install @supermemory/openclaw-supermemory

The README then gives a two-step setup: run the setup command, which prompts for an API key from app.supermemory.ai, and restart the gateway so the plugin loads.

openclaw supermemory setup
openclaw gateway restart

If you want to change container tags, recall limits, or capture mode at setup time rather than editing JSON by hand, the README points to the advanced variant, followed by the same restart.

openclaw supermemory setup-advanced
openclaw gateway restart

For a first real use, the slash commands are the fastest way to confirm the wiring. Save a fact, then search for it and check that a similarity score comes back.

/remember <text>
/recall <query>

The same operations are available outside a chat session through the CLI, which is useful when you want to confirm the plugin is configured before blaming the model for forgetting something.

openclaw supermemory status
openclaw supermemory search <query>
openclaw supermemory profile

If you prefer file-based configuration, the README documents an environment variable path and a JSON path. The environment variables are SUPERMEMORY_OPENCLAW_API_KEY and, for self-hosted instances, SUPERMEMORY_BASE_URL, which defaults to https://api.supermemory.ai.

export SUPERMEMORY_OPENCLAW_API_KEY="sm_..."
export SUPERMEMORY_BASE_URL="http://localhost:8000"

The JSON equivalent lives in ~/.openclaw/openclaw.json and uses a plugins.slots.memory entry pointing at openclaw-supermemory. Note that the README's full example sets both allowPromptInjection and allowConversationAccess to true under hooks. Those two flags are what let the plugin read the conversation and write into the prompt. If your OpenClaw configuration restricts hooks, the plugin will install but the automatic behaviour will not fire.

Custom container tags and the routing decision handed to the model

Custom container tags are the most interesting design choice in the plugin. By default there is one root namespace, containerTag, which defaults to openclaw_{hostname}. Turn on enableCustomContainerTags and you can declare separate containers with a tag and a description, for example work and personal. Every tool then accepts a containerTag parameter, and the README says the AI picks the right container based on your instructions when using memory tools.

That means routing is a model decision driven by customContainerInstructions, a free-text field. It is flexible and it costs you nothing to set up. It is also non-deterministic. If a message is ambiguous, the model chooses, and the README does not describe a confirmation step, a default fallback container, or a way to audit misroutes after the fact. For a personal bot this is fine. For anything where memories must land in a specific bucket for compliance or retrieval reasons, the routing layer is a place where the documentation is thin, and you should treat container selection as best-effort rather than guaranteed.

The same caveat applies to supermemory-forget. The tool deletes a memory by query or ID, which means a fuzzy query can match more than you intended. The CLI exposes a separate openclaw supermemory wipe command, and the README notes it requires confirmation. Neither path is described as reversible.

The deprecated tool names and the 3.0 deadline

The README carries a migration note that is easy to skim past. The current tool names are hyphenated: supermemory-save, supermemory-search, supermemory-forget and supermemory-profile. The older forms, supermemory_store, supermemory_search, supermemory_forget and supermemory_profile, still resolve to the same tools but are deprecated and, per the README, will be removed in 3.0.

The package.json currently lists version 2.1.17, so the removal has not happened yet. If your OpenClaw configuration uses tool allowlists, this is the concrete action item: update the allowlist entries to the hyphenated names now. A configuration that allowlists only the older names will keep working today and break on the 3.0 upgrade, and the failure will look like the agent silently stopped saving memories rather than like a version error.

Where OpenClaw Supermemory is the wrong tool

The clearest limitation is the one stated up front: this plugin is a client for a paid cloud service. There is no offline mode described in the README. The baseUrl option can point at a self-hosted instance, which softens the dependency, but you are then running Supermemory yourself and the no local infrastructure pitch no longer applies to you.

The second limitation is data flow. Auto-capture sends conversation content to Supermemory after every turn by default. If your agent handles material you cannot ship to a third-party API, autoCapture needs to be false, and at that point the plugin is doing much less for you. The README does not document a redaction step, a local pre-filter, or a per-container exclusion rule, so the control you have is a boolean.

The third is version coupling. The peer dependency is openclaw >=2026.5.7, and the plugin metadata declares pluginApi and minGatewayVersion of 2026.5.7. This is not a plugin you can drop onto an older gateway and expect to work.

Finally, consider whether you want a probabilistic memory layer at all. Auto-recall injects up to maxRecallResults memories chosen by similarity. For a coding assistant that needs exact file contents, similarity search is the wrong retrieval model, and a plain file read beats it every time.

How it compares with OpenClaw's built-in file memory

The obvious alternative is OpenClaw's own memory slot backed by local files. The difference is not quality, it is where the work happens. A file-based memory keeps everything on disk, gives you a deterministic retrieval path, and costs nothing per turn. It also requires you to decide what to write and when, and it has no concept of a user profile built from accumulated conversations.

OpenClaw Supermemory inverts that. You give up determinism and local control, and in exchange the plugin decides what to extract, deduplicates it, and maintains a profile that gets injected periodically. The README's claim is that this is state of the art memory, and the architecture supports the claim in the sense that extraction and profile building are genuinely server-side work you would otherwise have to build. Whether that trade is worth a Pro subscription depends on how much you value automatic capture over exact retrieval. They are not substitutes for the same job.

A second alternative is running Supermemory yourself and pointing baseUrl at it. You keep the plugin's hooks and tools, and you take back control of the data. The README lists the environment variable and the config key for exactly this, and does not elaborate further on what self-hosting involves.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-09. The package is published at version 2.1.17 with no releases retrieved, so version tracking happens through the package itself rather than through release notes.

The licence is MIT according to package.json. The README does not state a licence, and the repository metadata does not either, so the package manifest is the source to trust here. MIT is permissive, but it covers the plugin code only. The Supermemory service it talks to is a separate commercial product with its own terms, and the README's requirement of a Pro subscription means the effective cost of adopting this plugin is a service subscription, not a licence review. That is not legal advice, just the shape of the dependency.

Upgrade cost is concentrated in two places. Peer dependency on openclaw >=2026.5.7 means gateway upgrades need to be checked against the plugin's declared pluginApi and minGatewayVersion. And the 3.0 tool rename means any allowlist still using the older names needs editing before that release lands. The build itself is unremarkable: esbuild bundles index.ts to dist/index.js with openclaw and supermemory marked external, and the package ships both the TypeScript entry and the built runtime extension.

Editorial conclusion

Adopt OpenClaw Supermemory if your agent runs on OpenClaw 2026.5.7 or later and you already pay for Supermemory Pro, since the plugin is a client and the extraction, deduplication and profile building happen on Supermemory's servers. Do not adopt it if you need local-only storage, if you cannot send conversation text to a third party, or if you are staying on the deprecated tool names past 3.0. Verify first that your gateway version satisfies the peer dependency, that captureMode is set the way you want before the first long session, and that your tool allowlists use the hyphenated names.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. supermemoryai/openclaw-supermemory on GitHub