brainmd

File-based nervous system for AI agents. Behaviors that work get stronger. Behaviors that fail get weaker. Unused patterns decay. Mistakes leave scars.

What It Is

brainmd gives your agent a persistent behavioral memory that survives session restarts. It's not a knowledge base — it's muscle memory. It tracks how the agent behaves, not what it knows.

Three layers complement each other:

brainmd is the only layer that self-modifies. The others are written by the agent, not evolved by it.

Installation

clawhub install brainmd

Then initialize the brain in your workspace:

cd ~/.openclaw/workspace
./skills/brainmd/scripts/init-brain.sh brain/

This creates:

brain/
├── reflexes/           # Fast-path decision scripts
├── habits/
│   └── preferences.json
├── weights/
│   └── pathways.json   # ← the core state file
├── cortex/
│   └── review.js       # ← the self-review engine
└── mutations/          # Immutable audit log

Wiring Into OpenClaw

Step 1 — AGENTS.md

Add a startup check so the agent reads its neural state at session start:

## 🧠 brainmd — Consult Your Brain

After reading memory files, check your neural state:

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

Before acting on anything non-trivial, scan for relevant pathways:

• Weak pathways (\x3C 0.5) = you've failed here before. Be careful, double-check.
• Strong pathways (> 0.8) = proven patterns. Trust them, act fast.
• Dying pathways (decaying) = you're forgetting something. Re-evaluate.

After notable outcomes, record them:

node brain/cortex/review.js record "pathway-name" true/false "what happened"

### Step 2 — HEARTBEAT.md

Wire the review cycle into your heartbeat so it runs automatically:

```markdown
## 🧠 brainmd Self-Check (every heartbeat)

```bash
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 \x3Cpathway> false "what happened"
2. Did something work well? → record \x3Cpathway> true "what worked"
3. Did a new pattern emerge? → let neurogenesis create it

### Step 3 — Seed Initial Pathways

Don't hypothesize — seed from real behavior. Run a few sessions first, then record what you observed:

```bash
node brain/cortex/review.js record "reflex:morning-briefing" true "Supplement reminders sent, user confirmed"
node brain/cortex/review.js record "habit:check-files-before-search" true "Read apartment-search.md before googling apartments"
node brain/cortex/review.js record "reflex:safe-file-deletion" false "Used xargs rm with bad grep, deleted workspace files"

Start with 5–10 pathways. Let the system grow from there.

Daily Usage

Check neural state

node brain/cortex/review.js status

Output shows all pathways with visual weight bars, success rate, fire count, and last outcome. Use this to calibrate confidence before non-trivial actions.

Record an outcome

# Something worked
node brain/cortex/review.js record "habit:remote-service-recovery" true "Fixed broken systemd service, used journalctl to diagnose"

# Something failed
node brain/cortex/review.js record "habit:bulk-subagent-spawning" false "Rate limited all 3 models by spawning 2 Opus agents simultaneously"

New pathways are auto-created at weight 0.30 (neurogenesis). Existing pathways update their stats.

Run the review cycle

node brain/cortex/review.js review

The cortex examines all pathways and applies reinforcement rules:

• Strengthen (+0.05): ≥3 fires, ≥80% success rate
• Weaken (−0.10): ≥3 fires, \x3C50% success rate
• Decay (−0.02): unused for 7+ days
• Prune: weight hits 0 (pathway removed)

All changes are logged to mutations/ with timestamp and reason.

Pathway Naming Conventions

reflex:timing          # Automatic, fast-path behaviors
habit:check-files      # Learned patterns from repeated interaction
skill:osint-workflow   # Acquired capabilities
instinct:safe-delete   # Safety behaviors (start at high weight, floor at 0.8)

Reading pathway weights

Tuning the Learning Rate

Edit thresholds in brain/cortex/review.js:

// Strengthen when success rate >= this
const STRENGTHEN_THRESHOLD = 0.8;

// Weaken when success rate \x3C this
const WEAKEN_THRESHOLD = 0.5;

// Days of inactivity before decay starts
const DECAY_ONSET_DAYS = 7;

// Weight change per review cycle
const DECAY_RATE = 0.02;
const STRENGTHEN_DELTA = 0.05;
const WEAKEN_DELTA = 0.10;

Floor weights (prevent over-pruning)

instinct:* pathways should have a minimum weight floor so they can't be trained away:

{
  "id": "instinct:safe-file-deletion",
  "weight": 0.85,
  "floor": 0.80,
  "fires": 1,
  "successes": 0
}

Add a floor field to pathways in pathways.json to protect them from decay.

Architecture Notes

pathways.json — the core state

{
  "version": 42,
  "pathways": {
    "habit:check-files-before-search": {
      "weight": 0.95,
      "fires": 13,
      "successes": 11,
      "lastFired": "2026-03-25T18:00:00.000Z",
      "lastOutcome": "Read AESTHETIC.md before recommending clothes. Saved a web search.",
      "created": "2025-11-01T00:00:00.000Z"
    }
  }
}

mutations/ — the audit log

Every self-modification writes a timestamped JSON file. Never delete these. They're how you trace why the agent's behavior changed over time.

{
  "type": "strengthen",
  "target": "habit:check-files-before-search",
  "from": 0.90,
  "to": 0.95,
  "reason": "11/13 success rate",
  "timestamp": "2026-03-26T07:00:00.000Z"
}

Integration With Auto-Dream

If you're using scripts/dream.js for memory consolidation, the two systems complement each other:

• brainmd answers: how should I behave?
• dream.js answers: what do I know?

Neither replaces the other. Wire both into HEARTBEAT.md for full coverage.

Bootstrapping Checklist

• Run init-brain.sh to create directory structure
• Add brainmd status check to AGENTS.md startup routine
• Add heartbeat entry to HEARTBEAT.md
• Seed 5–10 pathways from real observed behavior (not theory)
• Run one manual review to verify reinforcement logic works
• Check mutations/ after first review to confirm logging
• Set floor weights on any instinct:* pathways

Design Principles

1. Everything is mutable — no file is sacred except the mutation log
2. Use strengthens, disuse weakens — pathways that fire together wire together
3. Outcomes matter — track what worked, what didn't; guesses don't count
4. Failures leave scars — the most valuable pathways come from mistakes
5. Seed from reality — observe first, codify second
6. Small and composable — one pathway per behavior pattern
7. The schedule forces honesty — if it's not in HEARTBEAT.md, you'll skip it