self-reflection – OpenClaw Skill

---

name: self-reflection description: Continuous self-improvement through structured reflection and memory version: 1.1.1 metadata: {"openclaw":{"emoji":"🪞","requires":{"bins":["jq","date"]}}}

🪞 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

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

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

Add to your workspace HEARTBEAT.md:

## Self-Reflection Check (required)
Run `self-reflection check` at each heartbeat.
If ALERT: read past lessons, reflect, then log insights.

Configuration

Create ~/.openclaw/self-reflection.json:

{
  "threshold_minutes": 60,
  "memory_file": "~/workspace/memory/self-review.md",
  "state_file": "~/.openclaw/self-review-state.json",
  "max_entries_context": 5
}

Author

Created by hopyky

License

MIT

🪞 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                                   │   │
│  │         │                                                   │   │
│  │         ▼                                                   │   │
│  │   ┌─────────────┐                                           │   │
│  │   │ < 60 min ?  │                                           │   │
│  │   └──────┬──────┘                                           │   │
│  │          │                                                  │   │
│  │    YES   │   NO                                             │   │
│  │    ┌─────┴─────┐                                            │   │
│  │    ▼           ▼                                            │   │
│  │  ┌───┐    ┌─────────┐                                       │   │
│  │  │OK │    │ ALERT   │──► Agent reflects                     │   │
│  │  └───┘    └─────────┘    └──► self-reflection read          │   │
│  │    │                          └──► self-reflection log      │   │
│  │    ▼                                     │                  │   │
│  │  Continue                                ▼                  │   │
│  │  normally                         ┌────────────┐            │   │
│  │                                   │ MEMORY.md  │            │   │
│  │                                   │ (lessons)  │            │   │
│  │                                   └────────────┘            │   │
│  │                                                             │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

                        ┌──────────────────┐
                        │   STATE FILE     │
                        │ (last_reflection │
                        │  timestamp)      │
                        └──────────────────┘

How It Works

1. Heartbeat triggers → OpenClaw runs heartbeat every 60 minutes (08:00-22:00)
2. Agent reads HEARTBEAT.md → Sees instruction to run self-reflection check
3. Skill checks timer → Compares current time with last reflection
4. If ALERT → Agent reviews past lessons and logs new insights
5. Memory persists → Lessons stored in markdown for future reference

Quick Start

Installation

# Clone the skill
git clone https://github.com/hopyky/self-reflection.git ~/.openclaw/skills/self-reflection

# Add to PATH
ln -sf ~/.openclaw/skills/self-reflection/bin/self-reflection ~/bin/self-reflection

# Create config
cp ~/.openclaw/skills/self-reflection/self-reflection.example.json ~/.openclaw/self-reflection.json

OpenClaw Integration

Add heartbeat to your ~/.openclaw/openclaw.json:

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

Add to your HEARTBEAT.md:

## Self-Reflection Check (required)

Run `self-reflection check` at each heartbeat.

- If **OK**: Continue normally.
- If **ALERT**: Run `self-reflection read`, reflect, then `self-reflection log`.

Commands

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

Usage Examples

Check Status

$ self-reflection check
OK: Status good. Next reflection due in 45 minutes.

# When reflection is needed:
$ self-reflection check
ALERT: Self-reflection required. Last reflection was 65 minutes ago.

Log a Reflection

$ self-reflection log "error-handling" \
    "Forgot to handle API timeout" \
    "Always add timeout parameter to requests"

Reflection logged successfully.
  Tag:  error-handling
  Miss: Forgot to handle API timeout
  Fix:  Always add timeout parameter to requests

Read Past Lessons

$ self-reflection read 3
=== Last 3 reflections (of 12 total) ===

## 2026-01-30 14:30 | error-handling

**Miss:** Forgot to handle API timeout
**Fix:** Always add timeout parameter to requests

---

## 2026-01-30 10:15 | communication

**Miss:** Response was too verbose
**Fix:** Lead with the answer, then explain

---

View Statistics

$ self-reflection stats
=== Self-Reflection Statistics ===

Last reflection: 2026-01-30 14:30:00
Total reflections: 12

Entries in memory: 12

Top tags:
  error-handling: 4
  communication: 3
  api: 2

Threshold: 60 minutes
Memory file: ~/workspace/memory/self-review.md

Configuration

Create ~/.openclaw/self-reflection.json:

{
  "threshold_minutes": 60,
  "memory_file": "~/workspace/memory/self-review.md",
  "state_file": "~/.openclaw/self-review-state.json",
  "max_entries_context": 5
}

Option	Default	Description
threshold_minutes	60	Minutes between required reflections
memory_file	~/workspace/memory/self-review.md	Where reflections are stored
state_file	~/.openclaw/self-review-state.json	Timer state file
max_entries_context	5	Default entries shown by read

Memory Format

Reflections are stored in human-readable Markdown:

# Self-Review Log

This file contains lessons learned and improvements for continuous growth.

---

## 2026-01-30 14:30 | error-handling

**Miss:** Forgot to handle API timeout
**Fix:** Always add timeout parameter to requests

---

## 2026-01-30 10:15 | communication

**Miss:** Response was too verbose
**Fix:** Lead with the answer, then explain

---

Recommended Tags

Tag	Use for
error-handling	Missing try/catch, unhandled edge cases
communication	Verbose responses, unclear explanations
api	API usage mistakes, wrong endpoints
performance	Slow code, inefficient algorithms
ux	Poor user experience decisions
security	Security oversights
testing	Missing tests, untested edge cases

File Structure

~/.openclaw/
├── skills/
│   └── self-reflection/
│       ├── bin/
│       │   └── self-reflection     # CLI script
│       ├── README.md
│       ├── SKILL.md                # OpenClaw manifest
│       ├── LICENSE
│       └── self-reflection.example.json
├── self-reflection.json            # Your config
└── self-review-state.json          # Timer state (auto-created)

~/workspace/
└── memory/
    └── self-review.md              # Lessons (auto-created)

Dependencies

• bash (4.0+)
• jq (JSON processing)
• date (GNU coreutils)

License

MIT License - See LICENSE for details.

Author

Created by hopyky

Contributing

Issues and PRs welcome at github.com/hopyky/self-reflection