What Is the OpenClaw Context Engine? How Your Agent Builds Model Context

Ask ten engineers what “context engineering” means and you get ten habits: trim the history, retrieve the right docs, summarize when things get long. Good habits, but they live as scattered tricks inside a prompt-building function nobody wants to touch. The OpenClaw context engine takes a different route. It turns that pile of habits into a single, swappable component with a defined contract, a sensible default, and a failsafe that keeps your agent talking even when the fancy version breaks.

This post explains what the context engine is, the four moments it runs on every model call, and why the built-in legacy engine is the one most people should keep. If you run a self-hosted OpenClaw agent, this is the part of the system that decides what your model actually sees.

What is the OpenClaw context engine?

The OpenClaw context engine controls how the gateway builds model context for each run: which messages to include, how to summarize older history, and how to manage context across subagent boundaries. Every time your agent is about to call a model, something has to decide which slice of the conversation, memory, and tool definitions gets sent. That decision is the context engine’s job.

OpenClaw ships with a built-in engine called legacy and uses it by default. You only install and select a plugin engine when you want different assembly, compaction, or cross-session recall behavior. In config it is a single slot:

{
  plugins: {
    slots: {
      contextEngine: "legacy", // the default
    },
  },
}

That one line is the whole idea. Context handling isn’t hardcoded into the runtime anymore. It’s a component you can swap, the way you’d swap a database driver. The default works out of the box, and if you ever need smarter behavior, you point the slot at a plugin instead.

Why context assembly is the hard part

It’s tempting to think a big context window solves this. Just send everything and let the model sort it out. The research says otherwise, and it says so loudly.

Chroma’s “context rot” study tested 18 models, including GPT-4.1, Claude 4, Gemini 2.5, and Qwen3. The finding held across every one of them: model performance varies significantly and degrades as input length grows, even on simple tasks. On the LongMemEval benchmark, models scored noticeably higher on focused prompts of around 300 tokens than on full prompts of roughly 113,000 tokens. Same question, same answer buried inside, worse result. (Source: Chroma, Context Rot.)

Anthropic frames the same problem as an economics one. In their guide on context engineering, they describe an “attention budget” that a model draws down with every token it reads. The reason is baked into the transformer: each token attends to every other token, which creates n² pairwise relationships for n tokens. Double the context and you more than double the work the model does to stay focused. (Source: Anthropic, Effective context engineering for AI agents.)

So the goal isn’t “fit as much as possible.” It’s the opposite. Anthropic puts it as finding the smallest set of high-signal tokens that still gets the job done. A context engine is the machinery that does that selecting, over and over, without you thinking about it.

The four lifecycle points: ingest, assemble, compact, after turn

Here’s the part that makes the context engine a real contract instead of a vague idea. Every model run, OpenClaw calls the engine at four defined moments.

• Ingest: runs when a new message is added to the session. The engine can store or index that message in its own data store.
• Assemble: runs before each model call. The engine returns an ordered set of messages that fit the token budget, plus an optional systemPromptAddition it can prepend to the system prompt.
• Compact: runs when the context window is full, or when someone runs /compact. The engine summarizes older history to free space.
• After turn: runs once a model call completes. The engine can persist state, kick off background compaction, or update its indexes.

Assemble is the one that matters most day to day. It’s where the “select the right tokens” work happens, and it’s why a plugin engine can inject live recall guidance through systemPromptAddition instead of relying on static workspace files. Compact is the safety valve. When the window fills, this is what stops the run from overflowing.

Because these four points are a stable interface, a plugin author knows exactly where their code hooks in. That’s the difference between “context engineering as a discipline” and “context engineering as a component.” OpenClaw picked the component.

The legacy engine: the default that just works

The legacy engine preserves OpenClaw’s original behavior, and it’s worth understanding because it’s what you’re running unless you changed something. It’s deliberately thin:

• Ingest: does nothing. The session manager already persists messages directly.
• Assemble: pass-through. The existing sanitize, validate, and limit pipeline in the runtime handles it.
• Compact: hands off to the built-in summarization, which makes a single summary of older messages and keeps recent ones intact.
• After turn: does nothing.

It doesn’t register tools and it doesn’t add anything to the system prompt. When no contextEngine slot is set, or it’s set to "legacy", this is what runs. For most self-hosted agents that’s the right call. The default is boring, predictable, and battle-tested, and you should need a specific reason to move off it.

Plugin engines and ownsCompaction

When the default isn’t enough, a plugin can register its own engine through the plugin API and implement those lifecycle methods itself. Maybe it stores every message in a vector store and does semantic recall on assemble. Maybe it runs a custom summarizer on compact. The interface is the same either way.

The knob to understand here is ownsCompaction. It decides who’s responsible for shrinking context when things get tight.

• ownsCompaction: true: the engine takes over. OpenClaw disables its built-in auto-compaction for that run, and the plugin’s compact() method becomes responsible for /compact, provider overflow recovery, and any compaction it wants to run ahead of time after a turn.
• ownsCompaction: false (or unset): OpenClaw’s built-in auto-compaction can still run, but the engine’s compact() is still called for /compact and overflow recovery.

There’s a trap worth flagging. A no-op compact() on a non-owning engine is unsafe, because it quietly disables the normal compaction path for that slot. If you’re writing a delegating engine, the docs point you at delegateCompactionToRuntime(...) so you reuse OpenClaw’s built-in behavior instead of leaving a hole. Owning mode means you bring your own algorithm; delegating mode means you borrow the runtime’s. Both are valid. A silent no-op is not.

Subagent context: isolated vs fork

Agents that spawn subagents have a second context problem: what does the child see? OpenClaw exposes two optional hooks, prepareSubagentSpawn and onSubagentEnded, so a context engine can set up and tear down shared state around a child run. The spawn hook receives a contextMode that is either isolated or fork.

The distinction is practical. An isolated child starts from a lightweight bootstrap context and doesn’t inherit the parent’s transcript. A fork hands the child the current context so it continues from where the parent left off. This matches the pattern Anthropic describes, where specialized sub-agents work in clean context windows and hand back a condensed summary, often just 1,000 to 2,000 tokens. Isolation is how you stop a child’s exploration from polluting the parent’s attention budget.

Failure isolation: why a broken engine won’t silence your agent

This is the design decision I’d steal. Context engines are plugins, and plugins break. So OpenClaw treats the selected engine as untrusted code sitting outside the core reply path.

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 and downgrades context work to the built-in legacy engine. The error gets logged with the operation that failed, so you can repair, update, or disable the plugin later. The agent, meanwhile, keeps answering.

Think about the failure mode that avoids. A context engine that crashes on assemble is exactly the thing that would otherwise make an agent go dark mid-conversation, because assembly runs before every single model call. OpenClaw chose “downgrade and keep talking” over “crash and go silent.” For anything running unattended, that’s the correct default, and it’s the reason plugin experimentation here is low-risk: the worst case is you fall back to the engine you’d have used anyway.

One caveat: host requirement failures are handled differently. If an engine declares that it needs a capability the runtime can’t provide, OpenClaw fails closed before the run starts, on purpose, to protect engines that would corrupt state in an unsupported host. Quarantine is for unexpected breakage; fail-closed is for known incompatibility.

Frequently asked questions

Do I need to configure the OpenClaw context engine?

No. If you set nothing, OpenClaw uses the legacy engine, which handles assembly and compaction with the runtime’s original pipeline. You only touch the slot when you want different recall or compaction behavior from a plugin.

How is the context engine different from memory?

Memory is what your agent stores and recalls across sessions. The context engine is the machinery that decides, on each run, which of that memory plus recent messages plus tool definitions actually gets sent to the model. Memory is the library; the context engine is the librarian handing you a stack for this specific question.

What happens to my agent if a context engine plugin crashes?

OpenClaw quarantines the failed engine for the current gateway process and falls back to the built-in legacy engine, logging the error. Your agent keeps responding rather than going silent.

What is compaction and when does it run?

Compaction summarizes older history to free space in the context window. It runs when the window fills or when you run /compact. Which code does the summarizing depends on the engine’s ownsCompaction setting.

Can a context engine change the system prompt?

Yes, indirectly. The assemble method can return a systemPromptAddition string that OpenClaw prepends to the system prompt for that run. It’s how an engine injects live recall or retrieval guidance without static workspace files.

The takeaway

The OpenClaw context engine is worth understanding even if you never write a plugin, because it names the thing that decides what your model sees and it gives that thing a contract. Four lifecycle points, one config slot, a legacy default that just works, and a quarantine-to-legacy failsafe that keeps your agent alive when a plugin doesn’t. Most people should stay on legacy. But when you outgrow it, you’re swapping one clean component for another, not rewriting your runtime.

Running a self-hosted agent and not sure what it’s actually sending to the model? Start with openclaw doctor to see which engine is active, read the context engine docs, and leave the slot on legacy until you have a concrete reason to change it.