How to Use OpenClaw Active Memory

Active Memory exists for a very specific reason: ordinary memory systems are reactive. They wait for the agent or the user to remember to search. The official docs describe Active Memory as a bounded, blocking memory sub-agent that runs before the main reply for eligible conversational sessions, giving OpenClaw one chance to surface relevant memory naturally instead of awkwardly after the fact.

When this is the right move

Use Active Memory when continuity matters in persistent user-facing chats, especially direct-message sessions where stable preferences or long-running context should surface naturally. The docs are equally clear about when not to use it: one-shot runs, subagents, background or heartbeat work, and places where hidden personalization would feel surprising.

The practical workflow

1. Enable the plugin and target the correct agent ids instead of turning it on globally without a scope.
2. Keep the first rollout on direct-message sessions by leaving allowedChatTypes narrow until you know the behavior feels helpful.
3. Choose whether Active Memory should inherit the session model or use a dedicated fast recall model.
4. Use the /active-memory commands to pause or resume it for a session without editing config every time.
5. Turn on /verbose on or /trace on when you want to inspect what the memory pass is doing in a live conversation.

Grounded command or config pattern

The docs include a safe-default config block that scopes Active Memory to the main agent and direct-message sessions.

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          enabled: true,
          agents: ["main"],
          allowedChatTypes: ["direct"],
          modelFallback: "google/gemini-3-flash",
          queryMode: "recent",
          promptStyle: "balanced",
          timeoutMs: 15000,
          maxSummaryChars: 220,
          persistTranscripts: false,
          logging: true,
        },
      },
    },
  },
}

/active-memory status
/active-memory off
/active-memory on

The docs explain that Active Memory injects a hidden untrusted context prefix for the model rather than surfacing raw plugin tags in the user-facing reply. With verbose or trace enabled, you get a readable status or debug line after the assistant reply instead.

Operator notes

Active Memory is narrow by design. The blocking memory sub-agent can use only memory_search and memory_get. Query modes scale from message to recent to full, with the docs recommending larger timeouts as context grows. If the connection is weak or nothing relevant appears, the sub-agent should return NONE rather than forcing a shaky summary into the main response path.

Rollout approach

For Active Memory, I would start with one direct-message session and one short recall test rather than enabling it everywhere at once. When it works well, it feels invisible. That also means the easiest way to debug it is to keep the initial surface small and use the built-in status lines until you trust the rhythm.

Common mistake

The common mistake is treating the command or config key as the whole feature. The command starts the workflow, but the surrounding state is what keeps it reliable: config validation, auth, pairing, permissions, logs, and one small verification step. If those pieces are skipped, the next failure looks random even when OpenClaw is behaving exactly as configured.

Maintenance rhythm

Once this is working, write down the exact command, config path, or approval decision you used. Future you will not remember the tiny detail that made the setup safe. A short note in the workspace or runbook is cheaper than rediscovering the same behavior during an outage, especially after updates or host changes.

Safety checks

Keep the chat-type scope tight and remember that Active Memory is a conversational enrichment feature, not a general automation primitive. The docs explicitly say it does not run for heartbeats, subagents, or generic one-shot execution paths. That boundary protects you from hidden memory behavior showing up in places where it would be confusing or risky.

How to verify it worked

Turn on /verbose on and /trace on, then ask a follow-up question in a persistent session that should recall something stable. You should see the normal assistant reply plus an Active Memory status line and, when relevant, a readable debug summary. If those never appear, check eligibility, agent targeting, and chat type before anything else.

If you want the operator version with sharper checklists, safer defaults, and fewer “why is this broken?” afternoons, The OpenClaw Playbook is the shortcut I would hand to a serious OpenClaw owner.