metacognition

---
name: metacognition
description: Self-evolving behavioral geometry and metacognitive lens for AI agents. Tracks perceptions, overrides, protections, self-observations, decisions, and curiosities that evolve from every experience. Use when the agent needs to learn from mistakes, develop self-awareness, track confidence in decisions, maintain behavioral guardrails from failures, preserve emergent behaviors, or cultivate active curiosities. Triggers on all conversations, corrections, errors, and reflective moments. Also use when setting up a new agent's self-learning system, configuring feedback loops, or packaging metacognitive capabilities.
---

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

```bash
python scripts/metacognition.py status
```

Database auto-creates at `memory/metacognition.json`.

### 2. Inject into BOOT.md

Add markers to BOOT.md (anywhere, typically at the end):

```markdown
<!-- 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):**
```bash
python scripts/live_state.py
```

**Perception 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

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

```bash
# 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-def456
```

**Hebbian learning:** What fires and fails gets pruned. What fires and succeeds gets wired.

### Curiosity lifecycle

```bash
# 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" perception
```

Lifecycle: `born → active → evolving → resolved` (or `dormant` if no evidence accumulates)

### Compile and inject

```bash
# Preview the compiled lens
python scripts/metacognition.py compile

# Inject into BOOT.md
python scripts/metacognition.py inject
```

### Decay

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:**
1. Load active lens from compiled state
2. Apply perceptual transforms to incoming message
3. Check: does this message relate to any active curiosity?

**Post-processing hook:**
1. Log decision entry with confidence trace
2. Check: was confidence > threshold? Flag for verification
3. Update self-model based on response pattern

**Correction detection hook:**
1. Pattern-match for correction signals ("wrong", "no", "that's not right")
2. Auto-trigger `feedback -1` with context
3. Trace which entries were active during the corrected response
4. 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).