> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kernle.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw Integration

> Plugin-based automatic memory for OpenClaw SIs

# 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)
```

<Note>
  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.
</Note>

## 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                      |

<Warning>
  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.
</Warning>

## Installation

<Steps>
  <Step title="Install Kernle">
    ```bash theme={null}
    pip install kernle
    # or
    pipx install kernle
    ```
  </Step>

  <Step title="Initialize a Stack">
    ```bash theme={null}
    kernle -s my-project init
    ```
  </Step>

  <Step title="Install the Plugin">
    ```bash theme={null}
    cd kernle/integrations/openclaw
    npm install && npm run build
    openclaw plugins install ./integrations/openclaw
    ```
  </Step>

  <Step title="Configure (Optional)">
    The plugin auto-detects the stack ID from your OpenClaw session key. To set it explicitly, add to your OpenClaw config:

    ```json theme={null}
    {
      "plugins": {
        "entries": {
          "kernle": {
            "enabled": true,
            "config": {
              "stackId": "my-project"
            }
          }
        }
      }
    }
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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:

```bash theme={null}
# 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:

1. Remove the hook from `~/.openclaw/openclaw.json` (`hooks.internal.entries.kernle-load`)
2. Remove the `memoryFlush` config (the plugin handles checkpointing automatically)
3. 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.

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Capture Immediately" icon="bolt">
    Use `raw` for quick captures. Organize later during lulls.
  </Card>

  <Card title="No Mental Notes" icon="brain">
    If you want to remember something, capture it. "Mental notes" don't survive compaction.
  </Card>

  <Card title="Record Lessons" icon="graduation-cap">
    Episodes without lessons are incomplete. Always extract what you learned.
  </Card>

  <Card title="Specific Checkpoints" icon="floppy-disk">
    Auto-checkpoints use conversation context, but manual checkpoints are more specific. Save when it matters.
  </Card>
</CardGroup>

## Troubleshooting

### Memory not appearing in context

```bash theme={null}
# 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

```bash theme={null}
# 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.