Metacognition

Self-reflection engine for AI agents. Extracts patterns from session transcripts into a weighted graph with Hebbian learning and time decay. Compiles a token-budgeted lens of active self-knowledge.

Metacognition Skill

A self-reflection engine for AI agents. Extracts patterns from session transcripts into a weighted graph with Hebbian learning and time decay.

What It Does

• Maintains a store of categorized insights (perceptions, overrides, protections, self-observations, decisions, curiosities)
• Uses Hebbian reinforcement: repeated insights get stronger, unused ones decay
• Builds a graph of connections between related insights
• Finds clusters of related knowledge that may represent higher-level principles
• Compiles a "metacognition lens" — a token-budgeted summary of active self-knowledge

Setup

1. Place metacognition.py in your workspace scripts/ directory
2. The script stores data in memory/metacognition.json (relative to workspace)
3. The compiled lens outputs to scripts/metacognition-lens.md
4. Optionally configure a local embeddings endpoint for semantic similarity (falls back to string matching)

Cron Integration

Set up a cron job to run periodically (e.g., every 4 hours):

text

METACOGNITION INTEGRATION. You are the self-reflection engine.

1. Run `cd <WORKSPACE> && python3 scripts/metacognition.py decay` to prune weak entries.

2. Use sessions_list + sessions_history to read the main session's recent conversation.

3. Analyze the conversation for DEEPER patterns:
   - PATTERNS: Am I repeating the same kind of mistake? What does that reveal?
   - ANTICIPATION: What did the human need that I could have predicted?
   - RELATIONSHIP: What did I learn about how the user communicates or what they value?
   - CONFIDENCE: Where was I certain and wrong? Where was I uncertain but right?
   - GROWTH: What's a higher-level principle behind today's specific events?

4. For each genuine insight (1-3, quality over quantity), add it:
   `python3 scripts/metacognition.py add <type> "<insight>"`
   Types: perceptions, overrides, protections, self-observations, decisions, curiosities
   Write insights as PRINCIPLES, not incident reports.

5. Run `python3 scripts/metacognition.py reweave` to build graph connections.

6. Run `python3 scripts/metacognition.py compile` to rebuild the lens.

7. Report only if something genuinely interesting was extracted.

CLI Commands

text

python3 metacognition.py add <type> <text>       # Add or merge an entry
python3 metacognition.py list [type]              # List entries
python3 metacognition.py feedback <id> <pos|neg>  # Reinforce or weaken
python3 metacognition.py decay                    # Apply time-based decay
python3 metacognition.py compile                  # Compile the lens
python3 metacognition.py extract <path>           # Extract from a daily note
python3 metacognition.py resolve <id>             # Mark curiosity resolved
python3 metacognition.py reweave                  # Build graph connections
python3 metacognition.py graph                    # Show graph stats
python3 metacognition.py integrate                # Full cycle

Configuration

Key constants in the script:

Constant	Default	Description
HALF_LIFE_DAYS	7.0	How quickly unreinforced entries decay
STRENGTH_CAP	3.0	Maximum strength an entry can reach
LENS_TOKEN_BUDGET	500	Token budget for compiled lens
EMBEDDING_SIM_THRESHOLD	0.85	Similarity threshold for merging (embeddings)
FALLBACK_SIM_THRESHOLD	0.72	Similarity threshold for merging (string matching)
EDGE_SIM_THRESHOLD	0.35	Threshold for creating graph edges

Entry Types

• perceptions — Things learned from experience
• overrides — Corrections to previous beliefs
• protections — Rules to prevent known failure modes
• self-observations — Patterns in own behavior
• decisions — Policy decisions for future behavior
• curiosities — Open questions with lifecycle (born → active → evolving → resolved)