Metacognition Engine

A self-reflective memory system for AI agents. Hebbian learning with time decay, graph connections between related insights, and reweaving to find higher-level patterns.

What It Does

Agents forget between sessions. This gives them persistent self-knowledge that evolves over time:

• Entries — observations, corrections, protections, decisions, curiosities extracted from daily work
• Hebbian reinforcement — repeated insights get stronger, neglected ones decay
• Graph connections — related-but-distinct insights are linked, forming clusters
• Reweave — periodic pass that finds connections, clusters related insights, and mutually reinforces them
• Lens compilation — distills the strongest insights into a compact markdown "lens" for context injection

Entry Types

Type	Purpose
perceptions	Things learned about the world
overrides	Corrections to previous beliefs
protections	Guardrails and "never do this" rules
self-observations	Patterns in own behavior
decisions	Policy decisions for future behavior
curiosities	Open questions with lifecycle tracking

Commands

# Add an insight
python3 metacognition.py add self-observations "I skip verification when I think I already know the answer"

# List entries (optionally filtered by type)
python3 metacognition.py list
python3 metacognition.py list protections

# Reinforce or weaken an entry
python3 metacognition.py feedback <id> positive
python3 metacognition.py feedback <id> negative

# Apply time decay and prune weak entries
python3 metacognition.py decay

# Build graph connections and find insight clusters
python3 metacognition.py reweave

# Show graph statistics
python3 metacognition.py graph

# Compile the metacognition lens (markdown output)
python3 metacognition.py compile

# Extract entries from a daily note using pattern matching
python3 metacognition.py extract path/to/note.md

# Mark a curiosity as resolved (decays faster)
python3 metacognition.py resolve <id>

# Full cycle: decay → extract → reweave → compile
python3 metacognition.py integrate

The Graph

Entries aren't just a flat list — they form a graph. When two entries are related but not identical (above similarity threshold but below merge threshold), an edge is created between them. Edges have weights that decay over time.

Connected components form clusters — groups of insights that reinforce a common theme. During reweave, entries in a cluster get a small strength boost from their neighbors. This means patterns that show up across multiple observations naturally rise to the top.

The compiled lens shows these clusters, making higher-level principles visible even when individual entries are specific incidents.

Similarity

Supports two modes:

• Embeddings (preferred): Uses a local embeddings endpoint for semantic similarity
• Fallback: SequenceMatcher for lexical similarity when embeddings aren't available

Configure the embeddings URL via EMBEDDINGS_URL in the script.

Integration

Designed to run as a cron job in an AI agent's workflow:

1. Extract — pattern-match insights from daily notes or conversation logs
2. Reweave — build/update graph connections between entries
3. Compile — produce a compact lens for context injection
4. Decay — old, unreinforced insights fade naturally

The integrate command runs the full cycle.

Storage

• metacognition.json — entry store + graph edges (keep private, may contain personal context)
• metacognition-lens.md — compiled output, safe to share/inject into agent context

License

MIT