OpenClaw v2026.3.7 ContextEngine Guide: From Upgrade to Custom Plugin Development

Your OpenClaw Agent suddenly "forgets" what you discussed five minutes ago mid-conversation? This isn't a random bug. It's a fundamental problem with how long conversations manage context. v2026.3.7 introduces the pluggable ContextEngine architecture, giving you control over how context gets compressed and assembled for the first time. This guide walks you through upgrading, configuration, building your first custom plugin, and patching the ClawJacked security vulnerability along the way.

TL;DR

• ContextEngine is the headline feature of v2026.3.7: a pluggable context management architecture with 7 lifecycle hooks
• No plugins installed = zero behavioral changes, fully backward compatible. Safe to upgrade
• lossless-claw is the most mature ContextEngine plugin, using DAG-based lossless context compression
• ClawJacked vulnerability affects older versions. Upgrading to v2026.3.7 fixes it
• Adds GPT-5.4 and Gemini Flash 3.1 model support

What Problem Does ContextEngine Solve?

If you've run OpenClaw on long tasks, you've probably seen this: the Agent's response at the 30-minute mark completely ignores a key point from minute 5. The model isn't broken. The context compression is.

Previous versions of OpenClaw used hardcoded, lossy context compaction. When conversations hit the token limit, the system would either discard old messages or generate rough summaries, losing critical conversation details and temporal ordering. Worse, this compression logic was baked into the core codebase with no way for developers to customize it.

In practice, this causes two specific problems:

1. Agent drift: After extended sessions, the Agent starts responding to the previous message instead of the current one, derailing the entire conversation
2. Memory black holes: Context gets wiped after resets, history truncated, and all prior work simply evaporates

ContextEngine's design philosophy is straightforward: hand context management control from the core codebase to developers. Through a pluggable interface, you can register your own compression strategies, assembly logic, or replace the default behavior entirely.

ContextEngine Architecture and Lifecycle

ContextEngine uses a slot-based registry with config-driven resolution. In plain terms: you specify which plugin to use in your config file, and the system delegates all context management to it.

At its core are 7 lifecycle hooks, covering the full context lifecycle from creation to teardown:

Hook	Trigger	Purpose
bootstrap	Engine initialization	Load persisted state, establish DB connections
ingest	New message arrives	Preprocess, classify, flag importance
assemble	Before prompt assembly	Decide what goes into the final prompt
compact	Token limit approaching	Compress or summarize older conversations
afterTurn	After each conversation turn	Post-processing, update stats, clean temp data
prepareSubagentSpawn	Before subagent launch	Prepare isolated context scope for subagent
onSubagentEnded	After subagent completes	Collect subagent output, merge back into main context

Practical advice: Most use cases only need the first four core hooks (bootstrap, ingest, assemble, compact). The two subagent-related hooks are only needed when building isolated memory blocks, powered by AsyncLocalStorage for scoped subagent runtime.

Without any plugins, the system automatically loads the LegacyContextEngine wrapper, preserving all previous behavior with zero changes.

Upgrading and Enabling ContextEngine: Step by Step

The whole process takes about 5 minutes. If you're running anything before v2026.2.26, this upgrade also patches the ClawJacked security vulnerability. No reason not to upgrade.

Step 1: Back Up Your Config

cp -r ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
cp -r ~/.openclaw/credentials/ ~/.openclaw/credentials.bak/

Step 2: Run the Upgrade

Use the built-in CLI command:

openclaw update

Pin to a specific version if you prefer:

openclaw update --tag 2026.3.7

Or use npm:

npm i -g openclaw@2026.3.7

Step 3: Health Check

openclaw doctor    # Auto-run migrations and fixes
openclaw health    # Confirm services are running

Breaking Change: If you have both gateway.auth.token and gateway.auth.password set, you must explicitly set gateway.auth.mode to either token or password in your config before upgrading. Otherwise, startup will fail.

Step 4: Install a ContextEngine Plugin

openclaw plugins install lossless-claw

The installer automatically sets plugins.slots.contextEngine to "lossless-claw" in your config.

Step 5: Restart and Verify

openclaw gateway restart

After restart, lossless-claw runs automatically in the background. If you're not ready to use a plugin yet, skip Step 4. The system will behave exactly like the previous version.

Custom Plugin Development and lossless-claw in Practice

How lossless-claw Works

lossless-claw is the most mature ContextEngine plugin, built by Martian Engineering. Its core concept: continuously summarize old messages into a DAG (directed acyclic graph) tree structure in the background while keeping all original messages stored in a SQLite database.

When the AI agent needs to recall details, it can actively "expand" summaries back into the original conversation. According to the project documentation, context stays stable within the 30K to 100K token range after enabling it, eliminating the memory loss problem.

Requirements: Node.js 22+ and a configured LLM provider (OpenAI, Anthropic, etc.).

Performance Tuning

lossless-claw provides several key environment variables:

# Trigger compression early at 75% context capacity (default 100%)
LCM_CONTEXT_THRESHOLD=0.75

# Specify the model for compression (defaults to main system setting)
LCM_SUMMARY_MODEL=openai/gpt-5.4

# Specify the provider
LCM_SUMMARY_PROVIDER=openai

In practice, lowering the threshold to 0.75 reserves more room for AI response generation and reduces information loss during compression.

Learning from lossless-claw to Build Custom Plugins

Want to write your own ContextEngine plugin? Start with the lossless-claw source code and GitHub Discussion #22251 for the fastest path.

Key steps:

1. Declare plugin type: Add kind: "context-engine" to your plugin config
2. Implement hooks: At minimum, implement the four core hooks: bootstrap, ingest, assemble, compact
3. Register the plugin: Set your plugin name in plugins.slots.contextEngine

// Plugin structure example (simplified)
export default {
  kind: "context-engine",
  hooks: {
    bootstrap: async (ctx) => { /* Initialize your storage layer */ },
    ingest: async (ctx, message) => { /* Process incoming messages */ },
    assemble: async (ctx) => { /* Build the final prompt */ },
    compact: async (ctx) => { /* Your compression logic */ },
  }
}

Security Update: ClawJacked Vulnerability and Fix

If you're still running a version before v2026.2.26, beyond the feature upgrade, the security issue demands immediate attention.

ClawJacked is a high-severity vulnerability discovered by Oasis Security. The attack vector: a malicious website uses JavaScript to open a WebSocket connection to your localhost, exploiting the Gateway's rate-limit exemption for local connections to brute-force the admin password at hundreds of attempts per second.

Once successful, the attacker gains full control:

• Steal API keys
• Read private messages (messaging apps, calendars)
• Execute arbitrary shell commands on connected devices

The entire process is completely invisible to the user. According to BleepingComputer's report, successful attackers also auto-register as a trusted device without requiring user confirmation.

Fix: Upgrade to v2026.2.26 or later. If you're upgrading anyway, go straight to v2026.3.7 to get both features and security in one shot.

Conclusion

ContextEngine transforms OpenClaw's context management from "take what you get" to "you decide how it works." Whether you want to fix the long-conversation memory problem, need custom compression strategies for specific use cases, or simply need to patch the ClawJacked vulnerability, upgrading to v2026.3.7 is the most impactful thing you can do right now.

If you're new to OpenClaw, start with our complete setup tutorial to get the basics down. For existing users, start with openclaw update, install lossless-claw to experience lossless context management, and then explore custom plugin development from there.