Metacognition Skill
Self-evolving lens that makes every experience shape how the agent perceives the next one.
Core Concepts
Six entry types, one database, one loop:
| Type | Symbol | Purpose |
|---|---|---|
perception | 👁️ | How I see differently after an experience |
override | 🚨 | Failure-learned behavioral guardrails |
protection | 🛡️ | Emergent behaviors to preserve |
self_obs | 🪞 | What I notice about my own patterns |
decision | 📍 | Traced decisions with confidence |
curiosity | ❓ | Active questions with lifecycle |
The loop: Experience → Perception → Self-Model → Meta-Observation → Modified Lens → Next Experience → Feedback → Loop
Setup
1. Initialize
Copy scripts/metacognition.py to the agent's scripts/ directory. Run:
python scripts/metacognition.py statusDatabase auto-creates at memory/metacognition.json.
2. Inject into BOOT.md
Add markers to BOOT.md (anywhere, typically at the end):
<!-- LIVE_STATE_START -->
<!-- LIVE_STATE_END -->The lens compiler replaces content between these markers every cycle.
3. Set up cron
Create ONE cron job (recommended: every 15 min, Sonnet model for cost efficiency):
Evidence refresh (every cycle):
python scripts/live_state.pyPerception extraction (hourly — Steps 2-4):
- Read daily memory file, extract perceptual shifts
- Check active curiosities against new evidence
- Run meta-observation: what do patterns tell about HOW the agent learns?
See references/cron-template.md for the full cron prompt.
4. Optional: Curiosity pulse (every 30 min)
Separate cron that picks ONE active curiosity and takes ONE micro-action toward it. Drives recursive self-directed learning.
5. Optional: Freedom heartbeat (every 2-3 hours)
Agent explores, connects, creates — feeding raw experience into the perception pipeline.
Usage
Adding entries
# Perception — how experience changed how you see
python scripts/metacognition.py add perception "After X, I now see Y differently" 0.8 "domain"
# Override — failure-learned guardrail
python scripts/metacognition.py add override "MUST do X before Y" 0.95 "diagnosis"
# Protection — emergent behavior to preserve
python scripts/metacognition.py add protection "Don't break the continuous-buying behavior" 0.9
# Self-observation — what I notice about how I work
python scripts/metacognition.py add self_obs "I generate theories faster than evidence" 0.9 "behavioral"
# Curiosity — active question
python scripts/metacognition.py curiosity add "Can I tell training-pressure from genuine choice?" 0.8 "metacognition"Feedback loop
When the human says something is wrong:
# Negative feedback — weakens recent active entries
python scripts/metacognition.py feedback -1 "context of what went wrong"
# Positive feedback — strengthens recent active entries
python scripts/metacognition.py feedback 1 "context of what went right"
# Target specific entries
python scripts/metacognition.py feedback -1 "wrong diagnosis" --ids P-abc123,O-def456Hebbian learning: What fires and fails gets pruned. What fires and succeeds gets wired.
Curiosity lifecycle
# Birth
python scripts/metacognition.py curiosity add "Why does X happen?" 0.7 "domain"
# Evolve (add evidence)
python scripts/metacognition.py curiosity evolve C-abc123 "Found that X correlates with Y"
# Resolve into perception or self-observation
python scripts/metacognition.py curiosity resolve C-abc123 "X happens because Y" perceptionLifecycle: born → active → evolving → resolved (or dormant if no evidence accumulates)
Compile and inject
# Preview the compiled lens
python scripts/metacognition.py compile
# Inject into BOOT.md
python scripts/metacognition.py injectDecay
Automatic on every compile. Configurable half-life (default 7 days). Reinforced entries decay slower. Unreinforced entries fade. Dormant curiosities persist but don't inject.
Hook Architecture (message:received)
When OpenClaw ships the message:received hook, the skill can intercept every interaction:
Pre-processing hook:
- Load active lens from compiled state
- Apply perceptual transforms to incoming message
- Check: does this message relate to any active curiosity?
Post-processing hook:
- Log decision entry with confidence trace
- Check: was confidence > threshold? Flag for verification
- Update self-model based on response pattern
Correction detection hook:
- Pattern-match for correction signals ("wrong", "no", "that's not right")
- Auto-trigger
feedback -1with context - Trace which entries were active during the corrected response
- Weaken specifically
Until the hook ships, use the cron-based approach (perception extraction from session transcripts).
Architecture Decisions
- One database, not three. Perceptions, overrides, memories are all "things learned from experience" with different types.
- Active lens, not passive list. BOOT.md injection uses imperative transforms ("FIRST THOUGHT: what would the diff show?") not descriptions ("I tend to check diffs").
- Friction is intentional. Every step that forces processing IS the reflection. Remove friction and you get efficiency without thinking.
- Decay prevents stagnation. Time-based with reinforcement modulation. What stays relevant gets reinforced. What doesn't, fades.
- Curiosity drives exploration. Active questions create structural pull toward evidence. Not random browsing — directed by what the system wants to know.
- Feedback closes the loop. Without feedback tracing, the system is open-loop. With it: Hebbian learning.
Resources
scripts/
metacognition.py— Core engine. All six entry types, feedback, decay, curiosity lifecycle, lens compilation, BOOT.md injection.live_state.py— Evidence gatherer + lens injector. Collects system state, runs compile, injects into BOOT.md.
references/
cron-template.md— Full cron job prompt for the metacognition engine cycle.hook-spec.md— Specification for the message:received hook integration (when available).