escalate mode runs its blocking recall sub-agent only when the
message asks about the past and the deterministic memory lane found no strong
trusted trigger match. This keeps ordinary replies fast while preserving a
deeper search path for prior decisions, conversations, and temporal or
multi-hop questions.
Flat retrieval is strongest for direct fact matches and weaker on temporal and
multi-session questions. LongMemEval (arXiv:2410.10813)
measures that gap, while the PrefEval benchmark highlights the value of
preference-adjacent reminders. Escalation by default spends the blocking model
call where those harder recall shapes are actually present.
Remember across conversations
For a personal or fully trusted agent, enable bounded recall across its other private conversations with one per-agent setting:session.dmScope must be
unset or "main", and no binding may override session.dmScope. Any configured
DM isolation defaults it off. An explicit true or false always wins. When
enabled, OpenClaw indexes that agent’s session transcripts and runs an Active
Memory retrieval pass before eligible private replies. The pass can read
relevant transcript excerpts from the same agent’s other private conversations.
It excludes the conversation already being answered.
The privacy boundary is fixed:
- private direct and persistent explicit UI conversations can recall one another
- groups and channels are neither recall sources nor recall destinations
- another agent’s transcripts are never eligible
- unknown or archived transcripts without enough conversation metadata are rejected
tools.sessions.visibility, or grant broader sessions_* tool access. Shared
workspace memory (MEMORY.md and memory/*.md) keeps its existing behavior.
Active Memory must remain enabled. Retrieval adds a bounded blocking step to
eligible replies; timeout, unavailable search, and empty results all continue
the reply without recalled transcript context. OpenClaw’s built-in memory
provider supports this protected transcript-recall path with both the builtin
and QMD backends. Other memory providers keep their own recall behavior but do
not automatically receive private transcript authorization. openclaw doctor
reports an unsupported provider or missing memory_search tool.
Advanced Active Memory quick start
Paste intoopenclaw.json for an advanced safe default: plugin on, scoped to
main, direct-message sessions only, model inherited from the session.
plugins.entries.* (including active-memory.config) is in the no-restart
config category:
the Gateway reloads the plugin runtime automatically and no manual restart is
needed. If you want to force a full restart anyway, run:
plugins.entries.active-memory.enabled: trueturns the plugin onconfig.mode: "escalate"runs deep recall only for recall intent without a strong deterministic hitconfig.agents: ["main"]opts only themainagent inconfig.allowedChatTypes: ["direct"]scopes it to direct-message sessions (opt in groups/channels explicitly)config.model(optional) pins a dedicated recall model; unset inherits the current session modelconfig.modelFallbackis used only when no explicit or inherited model resolvesconfig.fastModeoptionally overrides fast mode for recall without changing the main agentconfig.promptStyle: "balanced"is the default forrecentmode- active memory still runs only for eligible interactive persistent chat sessions (see When it runs)
How it works
The deep-recall sub-agent can call only the configured memory recall tools (see Memory tools). If the connection between the query and available memory is weak, it returnsNONE and the main reply proceeds
without extra context.
Active memory is a conversational enrichment feature, not a platform-wide
inference feature:
Use it when the session is persistent and user-facing, the agent has
meaningful long-term memory to search, and continuity/personalization matter
more than raw prompt determinism: stable preferences, recurring habits,
long-term context that should surface naturally. It is a poor fit for
automation, internal workers, one-shot API tasks, or anywhere hidden
personalization would be surprising.
When it runs
Active Memory has two targeting paths for the deep-recall lane:- Remember across conversations automatically targets agents whose
effective
memory.search.rememberAcrossConversationssetting is enabled, but only for private direct or persistent explicit UI conversations. - Advanced Active Memory targets agent IDs listed in
plugins.entries.active-memory.config.agentsand applies the plugin’s chat type and chat ID controls.
/active-memory off pauses both
paths for that conversation. If any condition fails, active memory does not run
for that turn, and the main reply is unaffected.
config.mode controls when a targeted turn starts the blocking sub-agent:
The deterministic trusted-trigger lane remains available in
off mode.
rememberAcrossConversations is unchanged: it still controls whether deep
recall may search other private conversations.
Session types
config.allowedChatTypes controls which kinds of conversations may run the
advanced Active Memory path. It cannot widen Remember across conversations:
that product setting remains private-only even when advanced Active Memory is
allowed in groups or channels. Default:
direct, group, channel, explicit (portal-style sessions
with an opaque session id, for example agent:main:explicit:portal-123).
Direct-message sessions run by default; group, channel, and explicit sessions
need to be opted in:
config.allowedChatIds and config.deniedChatIds:
allowedChatIdsis an allowlist of resolved conversation ids. When non-empty, active memory only runs for sessions whose conversation id is in the list — this narrows every allowed chat type at once, including direct messages. To keep all direct messages while narrowing only groups, add the direct peer ids toallowedChatIdstoo, or keepallowedChatTypesscoped to the group/channel rollout you are testing.deniedChatIdsis a denylist that always wins overallowedChatTypesandallowedChatIds.
chat_id/open_id, Telegram chat id, Slack channel id). Matching is
case-insensitive. If allowedChatIds is non-empty and OpenClaw cannot
resolve a conversation id for the session, active memory skips the turn
instead of guessing.
Session toggle
Pause or resume active memory for the current chat session without editing config:plugins.entries.active-memory.config.enabled, an agent’s
memory.search.rememberAcrossConversations setting, or other global
configuration.
To pause/resume for all sessions instead, use the global form (requires
owner or operator.admin):
plugins.entries.active-memory.config.enabled but
leaves plugins.entries.active-memory.enabled on, so the command stays
available to turn active memory back on later.
How to see it
By default, active memory injects a hidden untrusted prompt prefix that is not shown in the normal reply. Turn on the session toggles that match the output you want:/verbose onadds a status line:🧩 Active Memory: status=ok elapsed=842ms query=recent summary=34 chars/trace onadds a debug summary:🔎 Active Memory Debug: Lemon pepper wings with blue cheese.
/trace raw, the traced Model Input (User Role) block shows the raw
hidden prefix:
Query modes
config.queryMode controls how much conversation the blocking sub-agent
sees. Pick the smallest mode that still answers follow-ups well; grow
timeoutMs as context size grows, from message to recent to full.
- message
- recent
- full
Only the latest user message is sent.Use when you want the fastest behavior, the strongest bias toward stable
preference recall, and follow-up turns do not need conversational
context. Start around
3000-5000 ms for config.timeoutMs.Prompt styles
config.promptStyle controls how eager or strict the sub-agent is about
returning memory:
Default mapping when
config.promptStyle is unset:
config.promptStyle always overrides the mapping.
Model fallback policy
Ifconfig.model is unset, active memory resolves a model in this order:
config.modelFallbackPolicy is a deprecated compatibility field kept for
older configs; it no longer changes runtime behavior — modelFallback is
strictly the last resort in the chain above, not a runtime failover that
swaps in another model when the resolved one errors.
Speed recommendations
Leavingconfig.model unset (inherit the session model) is the safest
default: it follows your existing provider, auth, and model preferences. For
lower latency, use a dedicated fast model instead — recall quality matters,
but latency matters more here than on the main answer path, and the tool
surface is narrow (only memory recall tools).
Good fast-model options:
cerebras/gpt-oss-120b, a dedicated low-latency recall modelgoogle/gemini-3-flash, a low-latency fallback without changing your primary chat model- your normal session model, by leaving
config.modelunset
Cerebras setup
chat/completions access for the chosen
model — /v1/models visibility alone does not guarantee it.
Memory tools
config.toolsAllow sets the concrete tool names the blocking sub-agent may
call for advanced Active Memory. Defaults depend on the current memory provider:
If none of the configured tools are available, or the sub-agent run fails,
active memory skips recall for that turn and the main reply continues
without memory context. For custom recall tools, non-empty model-visible
tool output counts as recall evidence unless structured result fields
explicitly report an empty result or failure.
toolsAllow only accepts concrete memory tool names: wildcards, group:*
entries, and core agent tools (read, exec, message, web_search, and
similar) are silently filtered out before the hidden sub-agent starts.
Built-in memory
No explicittoolsAllow needed:
LanceDB memory
After installing and configuring LanceDB, Active Memory automatically usesmemory_recall; no explicit toolsAllow is needed:
memory.search.rememberAcrossConversations does not expose private session
transcripts through memory_recall. Use LanceDB’s auto-recall or the advanced
configuration above when LanceDB is the active memory provider.
Lossless Claw
Lossless Claw is an external context-engine plugin (openclaw plugins install @martian-engineering/lossless-claw) with its own recall tools. Set it up as
a context engine first; see Context engine. Then
point active memory at its tools:
lcm_expand to toolsAllow here; Lossless Claw uses it as a
lower-level tool for delegated expansion, not meant for the top-level
active-memory sub-agent. Lossless Claw changes context assembly without
replacing the current memory provider. Keep memory_search in toolsAllow
when also using rememberAcrossConversations; an LCM-only tool list remains
valid for advanced Active Memory but disables the product transcript-recall
path.
Advanced escape hatches
Not part of the recommended setup.config.thinking overrides the sub-agent’s thinking level (default "off",
since active memory runs in the reply path and extra thinking time directly
adds user-visible latency):
config.fastMode overrides fast mode only for the blocking memory sub-agent.
Use true, false, or "auto"; leave it unset to inherit the normal
agent, session, and model defaults. "auto" uses the recall model’s configured
fastAutoOnSeconds cutoff:
config.promptAppend adds operator instructions after the default prompt
and before the conversation context — pair it with a custom toolsAllow when
a non-core memory plugin needs specific tool order or query shaping:
config.promptOverride replaces the default prompt entirely (conversation
context is still appended afterward). Not recommended unless deliberately
testing a different recall contract — the default prompt is tuned to return
either NONE or compact user-fact context for the main model:
Transcript persistence
Blocking sub-agent runs keep their runtime transcript in the agent’s SQLite store. By default, OpenClaw removes the temporary sub-agent session rows after the run finishes and does not create a JSONL file. To export those transcripts as JSONL artifacts for debugging:config.transcriptDir. Use this
carefully: exports can accumulate quickly on busy sessions, full query mode
duplicates a lot of conversation context, and these artifacts contain hidden
prompt context plus recalled memories.
Configuration
All active memory configuration lives underplugins.entries.active-memory.
Useful tuning fields:
Recommended setup
Start withrecent:
/verbose on for the status line and /trace on for the debug summary
while tuning — both are sent as a follow-up after the main reply, not
before. Use always only when every eligible turn warrants the latency. Keep
escalate for the recommended balance, then choose message, recent, or
full for the deep-recall query itself.
Cold-start grace
Before v2026.5.2 the plugin silently extendedtimeoutMs by an extra 30000
ms during cold start, so model warm-up, embedding-index load, and the first
recall could share one larger budget. v2026.5.2 moved that grace behind an
explicit setupGraceTimeoutMs config: timeoutMs is now the recall-work
budget by default unless you opt in. The blocking hook wraps that budget in
two fixed phases: up to 1500 ms for session/config preflight before recall
starts, then a separate fixed 1500 ms for abort settlement and transcript
recovery after recall work stops. Neither allowance extends model or tool
execution.
If you upgraded from v2026.4.x and tuned timeoutMs for the old
implicit-grace world (the recommended starter timeoutMs: 15000 is one
example), set setupGraceTimeoutMs: 30000 to restore the pre-v5.2 effective
budget:
timeoutMs + setupGraceTimeoutMs + 3000 ms (the
configured recall-work budget, plus up to 1500 ms preflight, plus a fixed
1500 ms post-recall completion allowance). The embedded recall runner uses
the same effective timeout budget, so setupGraceTimeoutMs covers both the
outer prompt-build watchdog and the inner blocking recall run.
For resource-tight gateways where cold-start latency is an accepted
trade-off, lower values (5000-15000 ms) work too — the trade-off is a higher
chance of the very first recall after a gateway restart returning empty
while warm-up finishes.
Debugging
If active memory is not showing up where you expect:- Confirm the plugin is enabled under
plugins.entries.active-memory.enabled. - For Remember across conversations, confirm the agent’s effective
memory.search.rememberAcrossConversationssetting is enabled, runopenclaw doctorto verify the current memory provider supports protected transcript recall, and confirmconfig.toolsAllowincludesmemory_searchwhen explicitly configured. For advanced Active Memory, confirm the agent ID is listed inconfig.agents. - Confirm you are testing through an eligible interactive persistent conversation.
- Remember that groups and channels never use cross-conversation transcript recall.
- Turn on
config.logging: trueand watch the gateway logs. - Verify memory search itself works with
openclaw status --deep.
maxSummaryChars. If active memory is too
slow, lower queryMode, lower timeoutMs, or reduce recent turn counts and
per-turn char caps.
Common issues
Advanced Active Memory rides on the configured memory plugin’s recall pipeline, so most recall surprises are embedding-provider problems, not active-memory bugs. The defaultmemory-core path uses memory_search and
memory_get; the memory-lancedb slot uses memory_recall. If you use another
memory plugin, confirm config.toolsAllow names the tools that plugin actually
registers. Remember across conversations is narrower: the current memory
provider must support OpenClaw’s protected same-agent/private-session recall
path.
Embedding provider switched or stopped working
Embedding provider switched or stopped working
If
memory.search.provider is unset, OpenClaw uses OpenAI embeddings. Set
memory.search.provider explicitly for Bedrock, DeepInfra, Gemini, GitHub
Copilot, LM Studio, local, Mistral, Ollama, Voyage, or OpenAI-compatible
embeddings. If the configured provider cannot run, memory_search may
degrade to lexical-only retrieval; runtime failures after a provider is
already selected do not fall back automatically.Set an optional memory.search.fallback only when you want a deliberate
single fallback. See Memory Search for the full
list of providers and examples.Recall feels slow, empty, or inconsistent
Recall feels slow, empty, or inconsistent
- Turn on
/trace onto surface the plugin-owned Active Memory debug summary in the session. - Turn on
/verbose onto also see the🧩 Active Memory: ...status line after each reply. - Watch gateway logs for
active-memory: ... start|done,memory sync failed (search-bootstrap), or provider embedding errors. - Run
openclaw status --deepto inspect the memory-search backend and index health. - If you use
ollama, confirm the embedding model is installed (ollama list).
First recall after gateway restart returns `status=timeout`
First recall after gateway restart returns `status=timeout`
On v2026.5.2 and later, if cold-start setup (model warm-up + embedding
index load) has not finished by the time the first recall fires, the run
can hit the configured
timeoutMs budget and return status=timeout
with empty output. Gateway logs show active-memory timeout after Nms
around the first eligible reply after a restart.See Cold-start grace under Recommended setup for the
recommended setupGraceTimeoutMs value.