Initial commit with translated description
This commit is contained in:
292
README.md
Normal file
292
README.md
Normal file
@@ -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 <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
|
||||
|
||||
```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)
|
||||
99
SKILL.md
Normal file
99
SKILL.md
Normal file
@@ -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 <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 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
|
||||
6
_meta.json
Normal file
6
_meta.json
Normal file
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"ownerId": "kn7epewtzkj36r7ga3x618xejd7zqskn",
|
||||
"slug": "self-reflection",
|
||||
"version": "1.1.1",
|
||||
"publishedAt": 1769841628025
|
||||
}
|
||||
6
self-reflection.example.json
Normal file
6
self-reflection.example.json
Normal file
@@ -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
|
||||
}
|
||||
Reference in New Issue
Block a user