OpenClaw Integration

OpenClaw is an open-source framework for building conversational AI agents. It uses a modular plugin system with named slots — each slot controls a specific part of the agent pipeline.

The most important slot is contextEngine. This is the plugin responsible for deciding what context gets injected into the system prompt before every LLM call. It controls what your agent remembers, knows, and feels.

OpenClaw's plugin system works like middleware. Each plugin implements lifecycle hooks that fire at specific points during a conversation turn:

By default, OpenClaw ships with a basic context engine that stores memories as local Markdown files. The Sonzai plugin replaces this with the Mind Layer — giving your agent persistent memory, personality evolution, mood tracking, and relationship modeling with zero additional code.

How plugin registration works

When you install @sonzai-labs/openclaw-context, the package exports a register() function as its default export. On startup, OpenClaw loads all installed plugins and calls their register functions. Ours registers a context engine factory under the name "sonzai":

// Inside @sonzai-labs/openclaw-context (you don't write this)
export default function register(api) {
  api.registerContextEngine("sonzai", () => {
    return new SonzaiContextEngine(client, config);
  });
}

Then in openclaw.json, you tell OpenClaw which registered engine to use for the contextEngine slot. The name "sonzai" must match what the plugin registered:

{
  "plugins": {
    "slots": {
      "contextEngine": "sonzai"    // ← matches the name from register()
    },
    "entries": {
      "sonzai": {                  // ← config passed to the plugin
        "enabled": true,
        "apiKey": "sk-your-api-key",
        "agentId": "your-agent-uuid"
      }
    }
  }
}

So the flow is: install the npm package → OpenClaw discovers and calls register() → the plugin registers under "sonzai" → your config assigns it to the contextEngine slot.

1. Get Your API Key

Get an API key from your Sonzai project settings. You'll paste it during the setup wizard, and it will be saved to your openclaw.json.

2. Install the Plugin

# Install via OpenClaw CLI
openclaw plugins install @sonzai-labs/openclaw-context

# Or install directly with your package manager
npm install @sonzai-labs/openclaw-context
# bun add @sonzai-labs/openclaw-context

3. Run the Setup Wizard

The setup wizard walks you through connecting your OpenClaw project to the Mind Layer:

npx @sonzai-labs/openclaw-context setup

The wizard will:

• Ask for your API key (or detect SONZAI_API_KEY from the environment)
• Ask if you have an existing agent ID, or create a new one with a name you choose
• Validate the API key against the Mind Layer
• Save your API key and plugin config to openclaw.json

After setup, your openclaw.json will look like this:

{
  "plugins": {
    "slots": {
      "contextEngine": "sonzai"
    },
    "entries": {
      "sonzai": {
        "enabled": true,
        "apiKey": "sk-your-api-key",
        "agentId": "a1b2c3d4-..."
      }
    }
  }
}

4. Start Chatting

Launch OpenClaw as usual. The plugin registers as the sonzai context engine and takes over context assembly automatically:

openclaw chat

That's it. Every conversation now flows through the Mind Layer — your agent has persistent memory, personality, and mood from the first message.

All settings go in openclaw.json under plugins.entries.sonzai. Environment variables are supported as overrides.

You can selectively disable specific context sources via the disablemap. This is useful when you want the Mind Layer for memory but don't need mood tracking, or when you want to reduce token usage:

{
  "plugins": {
    "entries": {
      "sonzai": {
        "enabled": true,
        "apiKey": "sk-your-api-key",
        "agentId": "your-agent-uuid",
        "disable": {
          "mood": true,
          "personality": false,
          "relationships": true,
          "memory": false,
          "goals": true,
          "interests": true,
          "habits": true
        }
      }
    }
  }
}

With the config above, only personality and memory context will be injected — ideal for using the Mind Layer as a pure memory and personality store.

On each turn, the plugin injects a structured <sonzai-context> block into the system prompt. Sections are ordered by priority and dropped lowest-first if the token budget is exceeded:

The plugin automatically extracts user identity from OpenClaw's session key format. This enables per-user memory and relationships without any configuration:

For multi-tenant deployments where you provision agents programmatically, use the setup() function directly:

import { setup } from "@sonzai-labs/openclaw-context";

const result = await setup({
  apiKey: "sk-project-key",
  agentName: "customer-support-bot",
  configPath: "/path/to/openclaw.json",
});

console.log(result.agentId);   // deterministic UUID (SHA1 of tenantID + agentName)
console.log(result.written);   // true — config file updated

The Sonzai context engine plugs into OpenClaw's lifecycle hooks. Here's the flow for a single conversation turn:

OpenClaw Runtime                SonzaiContextEngine              Sonzai Mind Layer
      |                                    |                                |
      |-- bootstrap(sessionId) ----------->|                                |
      |                                    |-- resolve agent + session ---->|
      |                                    |<-- session state cached -------|
      |                                    |                                |
      |-- assemble(messages, budget) ----->|                                |
      |                                    |-- fetch context (memory,       |
      |                                    |   personality, mood,           |
      |                                    |   relationships) ------------>|
      |                                    |<-- ranked context blocks ------|
      |                                    |                                |
      |<-- systemPromptAddition -----------|   (priority-ordered,           |
      |                                    |    budget-trimmed)             |
      |                                    |                                |
      |  [LLM call with enriched prompt]   |                                |
      |                                    |                                |
      |-- afterTurn(sessionId) ----------->|                                |
      |                                    |-- send conversation ---------> |
      |                                    |   Mind Layer extracts facts,   |
      |                                    |   updates mood, evolves        |
      |                                    |   personality automatically    |
      |                                    |                                |
      |-- compact(sessionId) ------------->|                                |
      |                                    |-- merge short-term → long-term>|
      |                                    |<-- compacted ------------------|

The context engine handles all communication with the Mind Layer. During assemble, it fetches context sources (memory, personality, mood, relationships, goals, interests, habits), ranks them by priority, and trims to the token budget. During afterTurn, it sends the conversation back for fact extraction and state updates. The engine never runs LLM calls locally — all intelligence lives on the Sonzai side.

The package exports the following for advanced usage: