commit cb760941816a15ca2a10170b3e02e08f58a24c49 Author: zlei9 Date: Sun Mar 29 09:46:03 2026 +0800 Initial commit with translated description diff --git a/README.md b/README.md new file mode 100644 index 0000000..59cc4be --- /dev/null +++ b/README.md @@ -0,0 +1,292 @@ +# 🪞 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 + +```bash +# 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`: + +```json +{ + "agents": { + "defaults": { + "heartbeat": { + "every": "60m", + "activeHours": { + "start": "08:00", + "end": "22:00" + } + } + } + } +} +``` + +Add to your `HEARTBEAT.md`: + +```markdown +## 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 ` | 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 + +```bash +$ 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 + +```bash +$ 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 + +```bash +$ 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 + +```bash +$ 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`: + +```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: + +```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](LICENSE) for details. + +## Author + +Created by [hopyky](https://github.com/hopyky) + +## Contributing + +Issues and PRs welcome at [github.com/hopyky/self-reflection](https://github.com/hopyky/self-reflection) diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..67fab25 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,99 @@ +--- +name: self-reflection +description: "通过结构化反思和记忆实现持续自我改进。" +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 + +```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 ` | 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 heartbeat. +If ALERT: read past lessons, reflect, then log insights. +``` + +## Configuration + +Create `~/.openclaw/self-reflection.json`: + +```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](https://github.com/hopyky) + +## License + +MIT diff --git a/_meta.json b/_meta.json new file mode 100644 index 0000000..fb20c58 --- /dev/null +++ b/_meta.json @@ -0,0 +1,6 @@ +{ + "ownerId": "kn7epewtzkj36r7ga3x618xejd7zqskn", + "slug": "self-reflection", + "version": "1.1.1", + "publishedAt": 1769841628025 +} \ No newline at end of file diff --git a/self-reflection.example.json b/self-reflection.example.json new file mode 100644 index 0000000..42a9543 --- /dev/null +++ b/self-reflection.example.json @@ -0,0 +1,6 @@ +{ + "threshold_minutes": 60, + "memory_file": "~/workspace/memory/self-review.md", + "state_file": "~/.openclaw/self-review-state.json", + "max_entries_context": 5 +}