OpenClaw Integration

Kernle integrates with OpenClaw via an OpenClaw Plugin SDK plugin that takes over memory management completely — automatic loading at session start, automatic checkpointing at session end, and interception of native memory file writes.

How It Works

SESSION START
       ↓
1. before_agent_start hook fires
2. Plugin runs: kernle -s {stackId} load --budget 8000
3. Memory injected as prependContext
4. SI has full memory: values, beliefs, goals, checkpoint, episodes
       ↓
   SI WORKS (captures memories via CLI as they happen)
       ↓
SESSION END (or compaction)
       ↓
5. agent_end hook fires
6. Plugin auto-saves checkpoint from conversation context
7. Raw entry marks session completion
       ↓
   NEXT SESSION (cycle repeats — memory reloads automatically)

The SI never needs to run kernle load or kernle checkpoint save manually. The plugin handles both automatically. In-session captures (raw, episode, note) remain available as CLI commands.

What Replaces What

Kernle replaces OpenClaw’s native memory system:

Native Feature	Kernle Replacement	Status
`MEMORY.md`	`prependContext` (auto-injected)	Replaced — plugin injects memory automatically
`memory/*.md` daily files	Episodes, notes, raw captures	Replaced — writes intercepted and captured into Kernle
`SOUL.md`	Values, beliefs, self-narrative	Replaced — Kernle’s dynamic identity evolves
`USER.md`	Relationships layer	Replaced — Kernle tracks dynamic relationship state
`AGENTS.md`	Not replaced	Kept — boot sequence instructions

When the plugin is active, writes to memory/ and MEMORY.md are blocked. The content is captured as a Kernle raw entry instead. Use kernle raw, kernle episode, or kernle note for memory writes.

Installation

Install Kernle

pip install kernle
# or
pipx install kernle

Initialize a Stack

kernle -s my-project init

Install the Plugin

cd kernle/integrations/openclaw
npm install && npm run build
openclaw plugins install ./integrations/openclaw

Configure (Optional)

The plugin auto-detects the stack ID from your OpenClaw session key. To set it explicitly, add to your OpenClaw config:

{
  "plugins": {
    "entries": {
      "kernle": {
        "enabled": true,
        "config": {
          "stackId": "my-project"
        }
      }
    }
  }
}

Verify

Start a new session and ask: “Do you have memory context from Kernle?”The SI should have values, beliefs, goals, and checkpoint in its context.

Stack ID Detection

The plugin automatically detects which stack to load:

Priority	Source	Example	Stack ID
1	Plugin config	`"stackId": "my-project"`	`my-project`
2	Environment variable	`KERNLE_STACK_ID=ash`	`ash`
3	Session key	`agent:ash:main`	`ash`
4	Workspace directory	`/Users/ash/my-project`	`my-project`
5	Fallback	—	`main`

Plugin Hooks

`before_agent_start` — Memory Loading

Runs kernle -s {stackId} load --budget {budget} and returns the output as prependContext so it appears in the agent’s system prompt. Budget defaults to 8000 tokens. Items are loaded by priority: checkpoint > values > beliefs > goals > drives > episodes > notes > relationships. Lower-priority items are excluded if the budget is exhausted. Graceful degradation: if kernle is not installed, the stack doesn’t exist, or the command times out (5s), the session continues without memory.

`agent_end` — Auto-Checkpoint

Extracts a summary from the conversation (last user message as task, last assistant message for context) and saves a checkpoint automatically. Also saves a raw entry marking session completion.

`before_tool_call` — Block Native Memory Writes

Intercepts write_file, edit_file, and create_file calls targeting memory/ or MEMORY.md. The content is captured as a Kernle raw entry, and the native write is blocked with guidance to use Kernle commands instead.

`tool_result_persist` — Transcript Trim

Truncates kernle CLI output longer than 2000 characters in the transcript to conserve compaction space.

During Work

The SI captures memories as they happen using CLI commands:

# Quick capture (raw layer)
kernle -s my-project raw "Noticed rate limits are per-user"

# Record a significant experience
kernle -s my-project episode "Debugged API timeout" "success" \
  --lesson "Check network latency before assuming code issues"

# Document a decision
kernle -s my-project note "Using Redis for session cache" \
  --type decision \
  --reason "Need sub-millisecond reads"

Configuration Reference

Setting	Type	Default	Purpose
`stackId`	string	auto-detected	Kernle stack ID
`tokenBudget`	number	`8000`	Token budget for memory loading
`timeout`	number	`5000`	Timeout in ms for kernle CLI calls
`kernleBin`	string	`"kernle"`	Path to kernle binary

Migrating from the Old Hook

If you were using the previous kernle-load bootstrap hook:

Remove the hook from ~/.openclaw/openclaw.json (hooks.internal.entries.kernle-load)
Remove the memoryFlush config (the plugin handles checkpointing automatically)
Install the plugin (see Installation above)

Migrating from Native Files

If you’re migrating an existing OpenClaw SI from static files to Kernle, use the dedicated OpenClaw migration tool — not kernle import directly. The generic kernle import command is designed for structured data (JSON with provenance chains, or markdown/CSV as raw-only). OpenClaw workspaces have their own file conventions (SOUL.md, USER.md, daily notes) that need specialized parsing.

# Use the dedicated OpenClaw migration script
python -m integrations.openclaw.migration.migrate_openclaw \
  --stack my-project ~/workspace

# Preview first (dry-run)
python -m integrations.openclaw.migration.migrate_openclaw \
  --stack my-project --dry-run ~/workspace

This handles:

SOUL.md — behavioral instructions (filtered, not raw identity)
USER.md — user context mapped to relationships
IDENTITY.md — core identity mapped to values/beliefs
MEMORY.md — curated memory mapped to mixed types
memory/*.md — daily session notes mapped to episodes

After migration, remove the native files from the workspace (except AGENTS.md).

Best Practices

Capture Immediately

Use raw for quick captures. Organize later during lulls.

No Mental Notes

If you want to remember something, capture it. “Mental notes” don’t survive compaction.

Record Lessons

Episodes without lessons are incomplete. Always extract what you learned.

Specific Checkpoints

Auto-checkpoints use conversation context, but manual checkpoints are more specific. Save when it matters.

Troubleshooting

Memory not appearing in context

# Check plugin is installed
openclaw plugins list

# Test kernle load manually
kernle -s my-project load

# Check stack exists
kernle -s my-project status

SI still writes to MEMORY.md

The before_tool_call hook may not be fully wired in your OpenClaw version. Check for updates, or manually remove write permissions on memory/ as a workaround.

Checkpoint is stale

# Check latest checkpoint
kernle -s my-project checkpoint load

Auto-checkpoints are saved at session end. For mid-session saves, the SI can still run kernle checkpoint save manually.

Getting Started

Core Concepts

Protocol System

Advanced Features

Developer Tools

CLI Reference

Integration

Design

Troubleshooting

OpenClaw Integration

OpenClaw Integration

How It Works

What Replaces What

Installation

Stack ID Detection

Plugin Hooks

`before_agent_start` — Memory Loading

`agent_end` — Auto-Checkpoint

`before_tool_call` — Block Native Memory Writes

`tool_result_persist` — Transcript Trim

During Work

Configuration Reference

Migrating from the Old Hook

Migrating from Native Files

Best Practices

Capture Immediately

No Mental Notes

Record Lessons

Specific Checkpoints

Troubleshooting

Memory not appearing in context

SI still writes to MEMORY.md

Checkpoint is stale

Getting Started

Core Concepts

Protocol System

Advanced Features

Developer Tools

CLI Reference

Integration

Design

Troubleshooting

​OpenClaw Integration

​How It Works

​What Replaces What

​Installation

​Stack ID Detection

​Plugin Hooks

​before_agent_start — Memory Loading

​agent_end — Auto-Checkpoint

​before_tool_call — Block Native Memory Writes

​tool_result_persist — Transcript Trim

​During Work

​Configuration Reference

​Migrating from the Old Hook

​Migrating from Native Files

​Best Practices

Capture Immediately

No Mental Notes

Record Lessons

Specific Checkpoints

​Troubleshooting

​Memory not appearing in context

​SI still writes to MEMORY.md

​Checkpoint is stale

OpenClaw Integration

How It Works

What Replaces What

Installation

Stack ID Detection

Plugin Hooks

`before_agent_start` — Memory Loading

`agent_end` — Auto-Checkpoint

`before_tool_call` — Block Native Memory Writes

`tool_result_persist` — Transcript Trim

During Work

Configuration Reference

Migrating from the Old Hook

Migrating from Native Files

Best Practices

Troubleshooting

Memory not appearing in context

SI still writes to MEMORY.md

Checkpoint is stale