Adaptive Brain#

A self-improving agent system that doesn't just log — it learns, adapts, and evolves.

Core Philosophy#

The existing self-improving-agent skill logs to markdown. That's a diary. This is an immune system — it detects patterns, builds antibodies, prevents recurring failures, and gets smarter with every interaction.

Quick Start#

bash

python3 scripts/brain.py init          # Initialize brain system
python3 scripts/brain.py learn         # Log a learning
python3 scripts/brain.py error         # Log an error
python3 scripts/brain.py adapt         # Run adaptation cycle
python3 scripts/brain.py dashboard     # Show improvement metrics
python3 scripts/brain.py predict "task description"  # Predict failure risk
python3 scripts/brain.py evolve        # Auto-evolve skill configs

What Makes This Different#

FeatureBasic LoggerAdaptive BrainLog entries✅✅Pattern detection❌✅ Recurring error clusteringConfidence scoring❌✅ Weighted by success rateAuto-adaptation❌✅ Changes behavior automaticallyFailure prediction❌✅ Risk scoring before tasksSkill evolution❌✅ Rewrites SKILL.md based on learningsRollback❌✅ Reverts bad adaptationsPerformance metrics❌✅ Tracks improvement over timeCross-pattern links❌✅ Connects related errorsBehavioral DNA❌✅ Encodes successful patternsOutcome tracking❌✅ Tracks prediction accuracySkill mutation❌✅ Auto-generates prevention rulesContext awareness❌✅ Weighs learnings by recency & areaFeedback loop❌✅ Confirms/contradicts based on outcomes

Architecture#

text

~/.adaptive-brain/
├── brain.json          # Core state: DNA, confidence, metrics
├── learnings.json      # All learnings with scores and links
├── patterns.json       # Detected recurring patterns
├── evolution.json      # History of adaptations and rollbacks
├── metrics.json        # Performance tracking over time
└── predictions.json    # Failure predictions and outcomes

Commands#

learn — Log a learning with auto-classification#

bash

python3 scripts/brain.py learn \
  --type correction \
  --summary "User corrected: weather defaults to UTC not local" \
  --area config \
  --context "Asked for Dhaka weather, got UTC time" \
  --fix "Always check USER.md timezone before reporting weather"

error — Log an error with pattern detection#

bash

python3 scripts/brain.py error \
  --command "pip install pandas" \
  --error "externally-managed-environment" \
  --fix "Use venv or --break-system-packages" \
  --files "signal_engine.py"

The brain automatically checks for similar past errors and links them.

adapt — Run adaptation cycle#

Scans recent learnings and errors, then:

1. Detects recurring patterns (same error 3+ times)
2. Updates behavioral DNA
3. Generates prevention rules
4. Optionally promotes to workspace files

predict — Predict failure risk before a task#

bash

python3 scripts/brain.py predict "deploy to production"

Returns risk score based on:

• Past errors in similar tasks
• Confidence level in relevant skills
• Historical success rate for task type

evolve — Auto-evolve based on accumulated learnings#

bash

python3 scripts/brain.py evolve

The brain reviews all learnings and:

1. Identifies patterns that should become permanent rules
2. Generates optimized SKILL.md patches
3. Creates behavioral DNA mutations
4. Tracks evolution history (for rollback)

dashboard — Learning metrics#

Shows:

• Total learnings by category
• Error recurrence rate
• Adaptation success rate
• Improvement trend (getting better or worse?)
• Top patterns
• Confidence score over time

rollback — Undo a bad adaptation#

bash

python3 scripts/brain.py rollback --to 3

Reverts to a previous evolution state.

Behavioral DNA#

The brain maintains a "DNA" string encoding successful behavioral patterns:

json

{
  "dna": {
    "always_use_venv": true,
    "check_prices_before_trade": true,
    "write_files_then_execute": true,
    "test_before_publish": true,
    "default_timezone": "UTC"
  },
  "mutations": [
    {"timestamp": "...", "gene": "always_use_venv", "reason": "3 pip errors in a row"}
  ]
}

Each gene is backed by learnings. When a gene's backing learnings are resolved, it can be retired.

Pattern Detection#

The brain clusters errors and learnings into patterns:

json

{
  "patterns": [
    {
      "id": "P001",
      "name": "Package install failures",
      "keywords": ["pip", "externally-managed", "venv"],
      "count": 4,
      "first_seen": "2026-03-30",
      "last_seen": "2026-03-31",
      "prevention": "Always use venv or --break-system-packages",
      "confidence": 0.95
    }
  ]
}

Integration with OpenClaw#

The brain reads and writes to workspace files:

Brain ActionTarget FileWhenBehavioral ruleSOUL.mdConfidence > 0.9, seen 3+ timesTool gotchaTOOLS.mdError pattern for specific toolWorkflowAGENTS.mdProcess improvement confirmedLong-termMEMORY.mdMajor insight or decision

Learning Confidence#

Every learning has a confidence score (0-1) that changes over time:

• New learning: 0.5 (neutral)
• Confirmed correct: +0.2 per successful application
• Contradicted: -0.3
• Resolves error: +0.1
• Older than 30 days: decays by 0.1

Only high-confidence learnings (>0.8) get promoted to workspace files.

Automatic Triggers#

After each session, the brain should run:

bash

python3 scripts/brain.py adapt

Or set up a cron job:

text

Schedule: daily at 23:00
Command: python3 scripts/brain.py adapt

See Also#

For basic markdown logging (complementary to this skill), see the self-improving-agent skill. This skill is an enhanced superset with adaptation, prediction, and evolution capabilities.