BRAIN.md

Self-modifying file system mimicking neuroplasticity for AI agents.

Concept

brainmd gives an AI agent a file-based nervous system that strengthens successful behaviors, weakens failed ones, grows new pathways, and prunes unused ones. No separation between code and data — everything is mutable except the audit log.

Quick Start

1. Initialize the brain structure:

./scripts/init-brain.sh [path]

2. Seed initial pathways from observed behavior:

node cortex/review.js record "reflex:my-pattern" true "Description of what worked"

3. Run self-review (wire into heartbeat/cron):

node cortex/review.js review

4. Check neural status:

node cortex/review.js status

Heartbeat Integration (Recommended)

The key to making brainmd work is automatic self-checks. Without periodic review, the agent has to remember to use it — defeating the purpose.

Add this to your agent's heartbeat/periodic routine (e.g. HEARTBEAT.md for OpenClaw):

## 🧠 brainmd Self-Check (every heartbeat)

Run cortex review and record any notable outcomes from recent interactions:

node ~/.openclaw/workspace/brain/cortex/review.js review
node ~/.openclaw/workspace/brain/cortex/review.js status

On each heartbeat, ask yourself:
1. Did I make a mistake since last check? → record <pathway> false "what happened"
2. Did something work well? → record <pathway> true "what worked"
3. Did a new pattern emerge? → let neurogenesis create it
4. Any pathways need manual weight adjustment?

This closes the loop: behavior → outcome → record → review → strengthen/weaken → behavior. Every heartbeat cycle. The agent can't forget because the schedule forces self-reflection.

Architecture

brain/
├── reflexes/       # Fast-path automatic responses
│   └── timing.js   # Example: when to notify vs stay quiet
├── habits/         # Learned behavioral patterns
│   └── preferences.json  # Evolving user preferences
├── skills/         # Self-generated micro-scripts
├── weights/        # Pathway strength tracking
│   └── pathways.json     # The core state file
├── cortex/         # Meta-scripts that modify everything else
│   └── review.js   # Self-review engine
└── mutations/      # Immutable audit log of all changes

Core Mechanisms

1. Pathways (weights/pathways.json)

Every learned behavior is a pathway with:

• weight (0.0–1.0): How reinforced this behavior is
• fires: How many times it activated
• successes/failures: Outcome tracking
• lastFired: For decay calculation

2. Reinforcement

After each interaction, record the outcome:

node cortex/review.js record "habit:some-behavior" true "What happened"
node cortex/review.js record "habit:some-behavior" false "What went wrong"

The cortex review cycle then:

• Strengthens pathways with >80% success rate (+0.05 weight)
• Weakens pathways with <50% success rate (-0.10 weight)
• Decays pathways unused for 7+ days (-0.02 weight)

3. Neurogenesis

When a novel situation is encountered, recording it auto-creates a new pathway at weight 0.3:

node cortex/review.js record "reflex:new-behavior" true "First time doing this"

4. Mutation Log

Every self-modification is logged to mutations/ with timestamp, type, and reason. Types:

• strengthen — pathway weight increased
• weaken — pathway weight decreased
• decay — pathway faded from disuse
• neurogenesis — new pathway created
• prune — pathway removed (weight hit 0)

The mutation log is the one immutable thing. Never delete it.

5. Reflexes

Scripts in reflexes/ implement fast-path decision logic. They should be:

• Self-contained (no external dependencies)
• Self-modifying (thresholds/config embedded, patchable by cortex)
• Callable from CLI for quick checks

Example — timing reflex decides whether to notify:

node reflexes/timing.js check 0.8  # Check with urgency=0.8

6. Habits

JSON files in habits/ capture learned patterns with confidence scores. Each preference includes:

• The learned value
• Confidence (0.0–1.0)
• How it was learned (explicit correction, inference, reinforcement)

Habits with low confidence should be treated as hypotheses, not facts.

7. Cortex Integration

Wire the cortex review into your agent's periodic routine (heartbeat, cron, etc.):

# In heartbeat/periodic check:
1. Run: node cortex/review.js review
2. Check mutation output for significant changes
3. If a pathway was pruned or weakened significantly, consider adjusting behavior

Design Principles

1. Everything is mutable — no file is sacred except the audit log
2. Use strengthens, disuse weakens — pathways that fire together wire together
3. Outcomes matter — track what worked, what didn't
4. Mutations are logged — every self-modification is audited
5. Small scripts > monoliths — composable, replaceable, evolvable
6. Seed from real behavior — don't hypothesize, observe first then codify
7. Confidence tracking — know what you know vs what you're guessing

Bootstrapping Tips

Seed from real behavior, not theory

Don't pre-fill pathways with what you think the agent should do. Run the agent for a session, observe what worked and failed, then record those as the initial pathways. Real data beats hypotheticals.

Let failures create pathways

The most valuable pathways are born from mistakes. When something goes wrong, record it — neurogenesis creates a new pathway at 0.30 weight. The agent now has a scar that reminds it.

Start small

Begin with 5-10 pathways. Let the system grow organically. Over-engineering the initial set defeats the purpose — the whole point is emergent behavior.

Customization

Adding New Pathway Types

Prefix conventions:

• reflex: — automatic, fast-path behaviors
• habit: — learned patterns from repeated interaction
• skill: — acquired capabilities
• instinct: — hardcoded safety behaviors (high initial weight)

Adjusting Learning Rates

Edit thresholds in cortex/review.js:

• Strengthen threshold: success rate >= 0.8 (default)
• Weaken threshold: success rate < 0.5 (default)
• Decay onset: 7 days of inactivity (default)
• Decay rate: -0.02 per review cycle (default)

Safety Boundaries

Some pathways should never be pruned. Set minimum weight floors:

• instinct:* pathways: minimum weight 0.8
• reflex:* pathways: minimum weight 0.2
• habit:* pathways: can decay to 0 and be pruned