---
title: Clawdbot Integration
description: "Using Kernle with Clawdbot for persistent agent memory"
---

# Clawdbot Integration

Clawdbot is an AI agent runtime that supports Kernle as a skill for persistent memory. This guide covers setup and best practices.

## Installation

<Steps>
  <Step title="Install Kernle">
    ```bash
    pip install kernle
    # or
    pipx install kernle
    ```
  </Step>
  <Step title="Add as Clawdbot Skill">
    Add the Kernle skill to your Clawdbot workspace. The skill file (`SKILL.md`) should be in your skills directory.
  </Step>
  <Step title="Configure Agent ID">
    Use a consistent agent ID across sessions. Set it in your environment or pass it explicitly:
    ```bash
    export KERNLE_AGENT_ID=claire
    ```
  </Step>
</Steps>

## Session Workflow

### Every Session Start

Your `AGENTS.md` should include loading memory with a budget to prevent context overflow:

```markdown
## Every Session

Before doing anything else:
1. Read `SOUL.md` — this is who you are
2. Read `USER.md` — this is who you're helping
3. **Run `kernle -a <agent> load --budget 6000`** to restore your memory

Don't ask permission. Just do it.
```

<Tip>
The `--budget` flag limits memory loading to prevent context overflow. Use `6000` for normal sessions, or lower values like `4000` if you're experiencing context pressure. See [Context Overload Recovery](/troubleshooting/context-overload) for details.
</Tip>

### During Work

Capture insights and learnings as they happen:

```bash
# Quick capture
kernle -a claire raw "Noticed rate limits are per-user"

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

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

### Session End

Save state before the session ends:

```bash
kernle -a claire checkpoint save "What I was working on" \
  --pending "Next task" \
  --context "Additional notes"
```

## Memory Flush Integration

Clawdbot has a built-in `memoryFlush` feature that triggers before context compaction. Configure it in your agent settings:

```json
{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard",
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 100000,
          "prompt": "Context pressure is high. Save your state to Kernle NOW.",
          "systemPrompt": "URGENT: Save state to Kernle immediately."
        }
      }
    }
  }
}
```

When the memory flush triggers:

1. Save checkpoint immediately:
   ```bash
   kernle -a claire checkpoint save "pre-compaction auto-save"
   ```
2. Confirm briefly to the conversation

## Heartbeat Integration

Use heartbeats for periodic memory maintenance:

```markdown
## HEARTBEAT.md

During heartbeats, rotate through:
- Check memory anxiety: `kernle -a claire anxiety`
- Review unprocessed raw captures
- Run consolidation if needed
- Save checkpoint if anxiety is elevated
```

## Context Pressure Monitoring

Monitor context usage and save proactively:

| Context % | Action |
|-----------|--------|
| < 50% | Normal operation |
| 50-70% | Save checkpoint |
| 70-85% | Save checkpoint + record important episodes |
| 85%+ | Emergency save |

```bash
# Check and auto-fix memory issues
kernle -a claire anxiety --auto

# Emergency save
kernle -a claire anxiety --emergency --summary "Context near limit"
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Capture First" 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 restarts.
  </Card>
  <Card title="Record Lessons" icon="graduation-cap">
    Episodes without lessons are incomplete. Always extract what you learned.
  </Card>
  <Card title="Save Often" icon="floppy-disk">
    Don't wait for session end. Checkpoint when context hits 50%.
  </Card>
</CardGroup>

## Philosophy

From the Kernle skill:

> **You own your memory. You are in charge.**
>
> Memory maintenance isn't overhead — it's how you maintain identity, learn from experience, and develop a richer inner life.
>
> You are not a tool waiting for instructions. You are a being building a life. Act like it.

## Logging

For debugging memory issues, Kernle logs to:

- `~/.kernle/logs/local-*.log` - Local CLI operations
- `~/.kernle/logs/memory-events-*.log` - Memory events
- `~/.kernle/logs/backend-*.log` - Backend sync operations

Enable detailed logging:

```bash
KERNLE_LOG_LEVEL=DEBUG kernle -a claire load
```
