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

CODEBLOCK0

Then initialize the brain in your workspace:

CODEBLOCK1

This creates:

CODEBLOCK2

Wiring Into OpenClaw

Step 1 — AGENTS.md

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

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

Before acting on anything non-trivial, scan for relevant pathways:
- Weak pathways (< 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:

Step 2 — HEARTBEAT.md

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

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

Step 3 — Seed Initial Pathways

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

CODEBLOCK8

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

Daily Usage

Check neural state

CODEBLOCK9

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

CODEBLOCK10

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

Run the review cycle

CODEBLOCK11

The cortex examines all pathways and applies reinforcement rules:

• - Strengthen (+0.05): ≥3 fires, ≥80% success rate
• Weaken (−0.10): ≥3 fires, <50% 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

CODEBLOCK12

Reading pathway weights

Tuning the Learning Rate

Edit thresholds in brain/cortex/review.js:

CODEBLOCK13

Floor weights (prevent over-pruning)

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

CODEBLOCK14

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

Architecture Notes

pathways.json — the core state

CODEBLOCK15

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.

CODEBLOCK16

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. 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