self-reflection

# 🪞 Self-Reflection

A skill for continuous self-improvement. The agent tracks mistakes, lessons learned, and improvements over time through regular heartbeat-triggered reflections.

## Quick Start

```bash
# Check if reflection is needed
self-reflection check

# Log a new reflection
self-reflection log "error-handling" "Forgot timeout on API call" "Always add timeout=30"

# Read recent lessons
self-reflection read

# View statistics
self-reflection stats
```

## How It Works

```
Heartbeat (60m) → Agent reads HEARTBEAT.md → Runs self-reflection check
                                                      │
                                            ┌─────────┴─────────┐
                                            ▼                   ▼
                                           OK              ALERT
                                            │                   │
                                       Continue            Reflect
                                                               │
                                                     ┌─────────┴─────────┐
                                                     ▼                   ▼
                                                   read               log
                                              (past lessons)     (new insights)
```

## Commands

| Command | Description |
|---------|-------------|
| `check [--quiet]` | Check if reflection is due (OK or ALERT) |
| `log <tag> <miss> <fix>` | Log a new reflection |
| `read [n]` | Read last n reflections (default: 5) |
| `stats` | Show reflection statistics |
| `reset` | Reset the timer |

## OpenClaw Integration

Enable heartbeat in `~/.openclaw/openclaw.json`:

```json
{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "60m",
        "activeHours": { "start": "08:00", "end": "22:00" }
      }
    }
  }
}
```

Add to your workspace `HEARTBEAT.md`:

```markdown
## Self-Reflection Check (required)
Run `self-reflection check` at each hea...

# 🪞 Self-Reflection

A continuous self-improvement skill for AI agents. Track mistakes, log lessons learned, and build institutional memory over time.

## Why?

AI agents make mistakes. Without memory, they repeat them. This skill creates a structured feedback loop where agents regularly pause, reflect on their performance, and document learnings.

```
"The only real mistake is the one from which we learn nothing."
                                                    — Henry Ford
```

## Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                         OPENCLAW GATEWAY                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────┐    Heartbeat     ┌──────────────────────────────┐ │
│  │             │    (every 60m)   │                              │ │
│  │   AGENT     │ ───────────────► │  HEARTBEAT.md                │ │
│  │             │                  │  └─► "self-reflection check" │ │
│  │             │                  │                              │ │
│  └──────┬──────┘                  └──────────────────────────────┘ │
│         │                                                           │
│         │ executes                                                  │
│         ▼                                                           │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    SELF-REFLECTION SKILL                     │   │
│  ├─────────────────────────────────────────────────────────────┤   │
│  │                                                             │   │
│  │   $ self-reflection check                                   │   │
│  │         │                                                   │   │
│  │         ▼                                                   │   │
│  │   ┌─────────────┐...