OpenClaw context engines

Everything the model sees is assembled by something. In OpenClaw that something is a context engine, and it is pluggable. The built-in one preserves the original behaviour, but the interface underneath is where retrieval-heavy or summary-heavy strategies plug in. Here are the lifecycle points, the contract a plugin has to honour, and the two failure behaviours that keep a bad engine from silencing the agent.

Four lifecycle points

• Ingest is called when a new message joins the session so the engine can store or index it; assemble is called before each model run and returns an ordered set of messages plus an optional system prompt addition that fits the token budget; compact is called when the window is full or the user asks for it; and an after-turn hook lets the engine persist state, start background compaction or update indexes.
• An optional maintain method performs transcript maintenance after bootstrap, a successful turn or compaction, using a safe rewrite helper, and it can be declared as background work so it does not block the reply; queued budget compaction that accepts background maintenance keeps the prepared runtime alive through maintenance, reruns and disposal, so acceptance does not mean cleanup finished.
• Two optional subagent hooks prepare shared state before a child run starts and clean up when it ends; the preparation hook receives parent and child session keys, the context mode, available transcript identifiers and an optional lifetime, and can return a rollback handle that OpenClaw calls when the spawn fails afterwards.
• The built-in legacy engine is deliberately thin: ingest is a no-op because the session manager persists messages, assemble passes through to the existing sanitize, validate and limit pipeline, compact delegates to built-in summarization, and the after-turn hook does nothing; it registers no tools and adds nothing to the system prompt.

ownsCompaction: false does not mean OpenClaw automatically falls back to the legacy engine's compaction path.

Writing an engine

A plugin registers an engine with an id, a name, whether it owns compaction, and the host parameters it accepts; OpenClaw intersects that declaration with the fields available for each lifecycle method so undeclared or unknown keys are never injected, and an engine that omits the declaration receives every current host field. For durable admitted turns an engine declares both transcript semantics and implements a commit method as one atomic idempotent write keyed by an advancement key, returning a committed status for the first write and a duplicate status when a host retry presents the same key; the payload covers only the range from the admitted user entry through the accepted terminal entry, and earlier history is read through the transcript cursor. Without the full declaration and method, OpenClaw uses the legacy path for that whole logical turn including retries, leaves the configured slot unchanged, and tries the engine again next turn. The assemble result carries the messages, an estimated token count, an optional system prompt addition, a prompt authority flag that decides which estimate the overflow precheck uses, and an optional projection lifecycle for hosts with persistent backend threads.

Requirements and failure

• An engine can declare host capability requirements, for example that it must control the actual prompt through assemble; native and embedded agent runs satisfy that capability while generic command-line backends do not, so an engine that requires it is rejected before the process starts, failing closed with a descriptive message.
• If a non-legacy engine is missing, fails contract validation, throws during creation or throws from a lifecycle method, OpenClaw quarantines it for the current gateway process, downgrades context work to legacy so replies continue, and logs the error with the failed operation so the operator can repair, update or disable the plugin.
• Owning compaction disables the built-in in-attempt auto-compaction and the generic pre-prompt overflow precheck for that run, making the engine responsible for manual compaction, overflow recovery and any proactive work; not owning it leaves built-in auto-compaction available but still routes manual compaction and overflow recovery to the engine, which is why a no-op compact method is unsafe.

OpenClaw compaction is the behaviour the legacy engine delegates to and OpenClaw context explained the thing being assembled.

Selecting and unselecting

The slot is exclusive at run time: only one registered engine is resolved for a given run or compaction, although other enabled engine plugins still load and run their registration code. Uninstalling the plugin currently selected in the slot resets it to the default, and the same reset applies to the memory slot, so no manual config edit is required. Switching engines does not rewrite existing sessions; they continue with their current history while the new engine takes over future runs. Memory plugins are a separate slot that provides search and retrieval, and an engine can draw on them during assembly through the documented helper rather than reaching into their layout. OpenClaw plugins covers the plugin system and OpenClaw memory search the retrieval side.

On Diali

On Diali the runtime configuration is generated from the dashboard and replaced at each release, so the engine selection is part of that generated configuration rather than a file customers edit by hand. Hosted OpenClaw on Diali describes the hosted assistant and Diali security the boundary around each runtime.

• Ingest, assemble, compact, after turn: four points, one contract.
• A broken engine is quarantined; legacy keeps the agent answering.
• Declare the transcript semantics or the turn silently uses legacy.