Configure OpenClaw Context Engines for Custom Logic

Ever felt like your AI agent is losing the plot as the conversation gets longer? Managing how an AI sees its history is one of the trickiest parts of building reliable agents. You want the model to remember the important bits without hitting token limits or getting confused by noise.

That is where the Context Engine comes in. It is the brain behind how OpenClaw builds the model’s context for every single run. It decides which messages to include, how to summarize older history, and how to manage context across subagent boundaries.

OpenClaw ships with a built-in legacy engine, but you can also use plugins to swap in alternative engines that change the entire context-engine lifecycle.

Quick start

You can check which engine is active right now with a simple command:

openclaw doctor
# or inspect config directly:
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

Installing a context engine plugin

Context engine plugins are installed just like any other OpenClaw plugin. You install it first, then select the engine in the slot:

# Install from npm
openclaw plugins install @martian-engineering/lossless-claw

# Or install from a local path (for development)
openclaw plugins install -l ./my-context-engine

After that, enable the plugin and select it as the active engine in your config:

openclaw.json

{
  plugins: {
    slots: {
      contextEngine: "lossless-claw", // must match the plugin's registered engine id
    },
    entries: {
      "lossless-claw": {
        enabled: true,
        // Plugin-specific config goes here (see the plugin's docs)
      },
    },
  },
}

Restart the gateway after you finish configuring. If you ever need to switch back to the built-in engine, just set contextEngine to "legacy" or remove the key entirely.

How it works

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

1. Ingest — This happens when a new message is added to the session. The engine can store or index the message in its own data store.
2. Assemble — This is called before each model run. The engine returns an ordered set of messages (and an optional systemPromptAddition) that fit within the token budget.
3. Compact — This triggers when the context window is full or when you run /compact. The engine summarizes older history to free up space.
4. After turn — This runs after a run completes. The engine can save state, trigger background compaction, or update indexes.

Subagent lifecycle (optional)

OpenClaw currently calls one subagent lifecycle hook:

• onSubagentEnded — Used to clean up when a subagent session completes or is swept.

The prepareSubagentSpawn hook is part of the

export default function register(api) {
  api.registerContextEngine("my-engine", () => ({
    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 }) {
      // Return messages that fit the budget
      return {
        messages: buildContext(messages, tokenBudget),
        estimatedTokens: countTokens(messages),
        systemPromptAddition: "Use lcm_grep to search history...",
      };
    },

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

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

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