Context engine

A context engine controls how OpenClaw builds model context for each run: which messages to include, how to summarize older history, and how to manage context across subagent boundaries.

OpenClaw ships with a built-in

Quick start

text
Copy
<Tabs>
  <Tab title="From npm">
    ```bash}
    openclaw plugins install @martian-engineering/lossless-claw
    ```
  </Tab>

  <Tab title="From a local path">
    ```bash}
    openclaw plugins install -l ./my-context-engine
    ```
  </Tab>
</Tabs>

text
Copy
Restart the gateway after installing and configuring.

How it works

Every time OpenClaw runs a model prompt, the context engine participates at four lifecycle points:

For the bundled non-ACP Codex harness, OpenClaw applies the same lifecycle by projecting assembled context into Codex developer instructions and the current turn prompt. Codex still owns its native thread history and native compactor.

Subagent lifecycle (optional)

OpenClaw calls two optional subagent lifecycle hooks:

System prompt addition

The

The legacy engine

The built-in

• Ingest: no-op (the session manager handles message persistence directly).
• Assemble: pass-through (the existing sanitize → validate → limit pipeline in the runtime handles context assembly).
• Compact: delegates to the built-in summarization compaction, which creates a single summary of older messages and keeps recent messages intact.
• After turn: no-op.

The legacy engine does not register tools or provide a

When no

Plugin engines

A plugin can register a context engine using the plugin API:

ts
Copy
import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function register(api) {
  api.registerContextEngine("my-engine", (ctx) => ({
    info: {
      id: "my-engine",
      name: "My Context Engine",
      ownsCompaction: true,
    },

    async ingest({ sessionId, message, isHeartbeat }) {
      // Store the message in your data store
      return { ingested: true };
    },

    async assemble({ sessionId, messages, tokenBudget, availableTools, citationsMode }) {
      // Return messages that fit the budget
      return {
        messages: buildContext(messages, tokenBudget),
        estimatedTokens: countTokens(messages),
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },

    async compact({ sessionId, force }) {
      // Summarize older context
      return { ok: true, compacted: true };
    },
  }));
}

The factory

Then enable it in config:

json5
Copy
{
  plugins: {
    slots: {
      contextEngine: "my-engine",
    },
    entries: {
      "my-engine": {
        enabled: true,
      },
    },
  },
}

The ContextEngine interface

Required members:

Optional members:

ownsCompaction

That means there are two valid plugin patterns:

A no-op

Configuration reference

json5
Copy
{
  plugins: {
    slots: {
      // Select the active context engine. Default: "legacy".
      // Set to a plugin id to use a plugin engine.
      contextEngine: "legacy",
    },
  },
}

Relationship to compaction and memory

Tips

• Use
  text

  Copy

  openclaw doctor
  to verify your engine is loading correctly.
• If switching engines, existing sessions continue with their current history. The new engine takes over for future runs.
• Engine errors are logged and surfaced in diagnostics. If a plugin engine fails to register or the selected engine id cannot be resolved, OpenClaw does not fall back automatically; runs fail until you fix the plugin or switch
  text

  Copy

  plugins.slots.contextEngine
  back to
  text

  Copy

  "legacy"
  .
• For development, use
  text

  Copy

  openclaw plugins install -l ./my-engine
  to link a local plugin directory without copying.

Related

• Compaction — summarizing long conversations
• Context — how context is built for agent turns
• Plugin Architecture — registering context engine plugins
• Plugin manifest — plugin manifest fields
• Plugins — plugin overview