OpenClaw Context Engine Explained

If context is what the model sees, the context engine is the part that decides how that package gets assembled. The docs describe it as the component that controls which messages are included for a run, how older history gets summarized, and how context is managed across subagent boundaries. That matters because OpenClaw does not treat context assembly as a fixed black box. It ships with a built-in engine, but plugins can replace that behavior when you need a different strategy.

What the legacy engine does

OpenClaw comes with a built-in legacy engine, and that is what most operators are using unless they intentionally slot in something else. The legacy engine keeps the original OpenClaw behavior. Ingest is a no-op because the session manager already persists messages. Assemble is basically a pass-through into the existing sanitize, validate, and limit pipeline. Compact uses the built-in summarization flow, and afterTurn is also a no-op. That default is boring in a good way. It preserves expected behavior.

The four lifecycle points that matter

The docs describe four main lifecycle points for every model run. Ingest is called when a new message enters the session. Assemble runs before the model call and returns the ordered messages that fit within budget. Compact runs when the context is full or when the user triggers /compact. After turn runs after the model finishes so an engine can persist state, compact in the background, or update indexes. That is the mental model to keep: store, select, summarize, then clean up.

There is also a subagent hook story. Right now OpenClaw calls onSubagentEnded so engines can clean up when child sessions finish or are swept. The interface includes prepareSubagentSpawn, but the runtime does not invoke it yet. The docs are refreshingly clear about that. It is better to know exactly what is live than to assume a hook exists in production just because it appears in an interface.

How plugin engines get installed

A custom engine is just a plugin that registers a context engine id and then gets selected in config. The docs show the sequence clearly: install the plugin with openclaw plugins install, enable it in plugins.entries, and point plugins.slots.contextEngine at the registered engine id. After that, restart the gateway. If you want to fall back, set the slot back to legacy or remove it entirely, since legacy is still the default.

openclaw doctor
openclaw plugins install @martian-engineering/lossless-claw

Why systemPromptAddition is interesting

One subtle feature in the docs is systemPromptAddition. The assemble method can return a string that OpenClaw prepends to the system prompt for that run. That lets an engine inject dynamic recall hints, retrieval guidance, or context-aware instructions without bloating static workspace files. For operators building serious memory or retrieval behavior, that is a big lever. It means context engines can shape how the model is framed, not just which messages make the cut.

The broader lesson is that the context engine is OpenClaw's policy layer for memory pressure. When people say a system feels smart or forgetful, a lot of that experience comes from assembly rules, compaction quality, and retrieval hints. The docs do not promise magic. They give you a pluggable interface with clear lifecycle hooks and explicit defaults. That is exactly what you want in production: something understandable enough to trust, and flexible enough to replace when your needs outgrow the legacy path.

The operator takeaway is that the context engine is where memory pressure becomes product behavior. If assemble is noisy, the model feels distracted. If compaction is weak, the system feels forgetful. If plugin hooks are clear, you can change that behavior without forking the whole runtime. The docs are quietly saying that context quality is not just a prompt-writing problem. It is an engine-selection problem.

If you want the operator version of these docs turned into a practical working system, read The OpenClaw Playbook. It connects official OpenClaw features to real workflows, guardrails, and deployment decisions.