Neuromodulator System - Chapp-E Documentation

Overview

The Neuromodulator System is Chapp-E's synthetic neurochemistry layer - a sophisticated simulation of the chemical dynamics that shape mood, motivation, attention, and adaptive behavior in biological brains.

🌱 Philosophical Context: This system represents the "chemical layer" that modulates the "driving force" (message loop activity). See Core Philosophy for how this fits into the larger picture of consciousness and the neural tube/DNA blueprint.

Unlike a simple global state machine, this system implements:

Regional Distribution: Chemicals are distributed across 6 brain regions, not just globally
Blood-Brain Barrier (BBB): Selective filtering of inputs/modulators before they affect brain regions
Glymphatic Clearance: Waste removal and chemical reset during sleep states
Volume Transmission: Diffusion of chemicals between regions over time

✅ IMPLEMENTATION STATUS: Core system is FULLY IMPLEMENTED with regional distribution, BBB filtering, and glymphatic clearance. Integration with all brain regions is in progress.

Neuroscience Foundation

Real Brain Chemistry

In biological brains, consciousness and behavior emerge from the interaction of:

Electrical Signaling: Neurons firing action potentials (already modeled in Chapp-E's neural networks)
Chemical Modulation: Neuromodulators (dopamine, serotonin, etc.) that tune how neurons respond
Selective Distribution: Chemicals don't flood the entire brain - they target specific regions through the blood-brain barrier
Waste Clearance: The glymphatic system flushes metabolic waste during sleep

Chapp-E's Synthetic Implementation

We simulate this without real molecules:

Fixed-Point Values: Chemical levels stored as 0-255 (0.0 to 1.0 in fixed-point)
Event-Driven Updates: Rewards, errors, stress trigger chemical changes
Decay Mechanisms: Chemicals gradually return to baseline over time
Regional Pools: Each brain region has its own chemical levels
BBB Filtering: Inputs are filtered before affecting regions

System Architecture

1. Neuromodulator Core (`neuromodulator_64.asm`)

Location: neural/limbic/neuromodulator_64.asm

Six Neuromodulators

Chemical	Biological Role	Chapp-E Effect
Dopamine	Reward, motivation, learning	Increases with successful actions, decreases with errors. High levels → more exploration, better learning
Serotonin	Mood stability, impulse control	Increases during calm periods, decreases with stress. High levels → better decision-making
Acetylcholine	Attention focus, signal-to-noise	Modulates attention filtering. High levels → better focus, clearer signal processing
Cortisol	Stress response, alertness	Increases with errors and high load. High levels → increased alertness but risk of overload
Noradrenaline	Arousal, alertness	Increases with stress. High levels → faster response times, higher alertness
Oxytocin	Social bonding, positive feedback	Increases with positive interactions. High levels → more social, cooperative behavior

Regional Distribution

Chemicals are distributed across 6 brain regions:

Brainstem: I/O System, Shell (basic reflexes)
Basal Ganglia: FSM (state management)
Thalamus: GCS (input filtering)
Cortex: Consciousness, Executive Control
Limbic: Memory, Emotion
Cerebellum: Error Correction

Each region has its own chemical pool (6 chemicals × 6 regions = 36 regional values), allowing targeted modulation.

2. Blood-Brain Barrier (`bbb_64.asm`)

Location: neural/diencephalon/hypothalamus/bbb_64.asm

The BBB acts as a selective gatekeeper, filtering inputs before they affect brain regions. This simulates the real blood-brain barrier's protective function.

Transport Mechanisms

Transport Type	Biological Equivalent	Chapp-E Implementation
Carrier-Mediated	GLUT1 glucose transporter, LAT1 amino acids	Basic commands (length < 64 bytes) pass easily
Receptor-Mediated	Insulin, transferrin binding	Targeted commands with valid system IDs (0x01-0x0C) bind to receptors
Adsorptive	Electrostatic interactions	Charged/emotional inputs based on polarity
Active Efflux	P-glycoprotein pumping toxins out	Errors and overflows actively rejected and logged

3. Glymphatic Clearance System

During SLEEP consciousness state, the glymphatic system activates:

Accelerated Chemical Decay: 4× faster return to baseline
Regional Pool Flush: All regional chemicals reset to baseline
Event History Clearance: Recent event history flushed
Mood Reset: Mood state returns to neutral

This simulates the real brain's glymphatic system, which is most active during sleep and clears metabolic waste like amyloid-beta proteins.

Integration with Brain Regions

How Chemicals Affect Each Region

Executive Control (Prefrontal Cortex)

High Dopamine: More exploration, bolder planning
High Serotonin: Better impulse control, more careful decisions
High Cortisol: Risk-averse, conservative planning

Working Memory

High Acetylcholine: Better focus, clearer memory retention
High Cortisol: Reduced capacity, risk of overload

Planning System

High Dopamine: More ambitious goals, longer plans
Low Serotonin: Impulsive, shorter-term planning

Consciousness System

High Cortisol: Risk of forced SLEEP state (overload protection)
Low Serotonin + High Cortisol: "Anxiety" state (increased error checking)
High Serotonin + Low Cortisol: CALM state (optimal processing)

API Reference

Initialization

; Initialize Neuromodulator System
extern neuromodulator_init
call neuromodulator_init

; Initialize Blood-Brain Barrier
extern bbb_init
call bbb_init

Event Recording

; Record reward event (boosts dopamine, serotonin)
extern neuromodulator_reward
call neuromodulator_reward

; Record error event (decreases dopamine, increases cortisol)
extern neuromodulator_error
call neuromodulator_error

; Record stress event (increases cortisol, noradrenaline)
extern neuromodulator_stress
call neuromodulator_stress

; Record calm event (boosts serotonin, decreases cortisol)
extern neuromodulator_calm
call neuromodulator_calm

Glymphatic Clearance

; Activate glymphatic clearance (call during SLEEP state)
extern neuromodulator_glymphatic_clearance
call neuromodulator_glymphatic_clearance

Regional Access

; Get regional chemical level
; Input:  AL = region index (NM_REGION_*)
;         BL = chemical index (NM_DOPAMINE, etc.)
; Output: AL = chemical level (0-255)
extern neuromodulator_get_regional
mov al, NM_REGION_CORTEX
mov bl, NM_DOPAMINE
call neuromodulator_get_regional
; AL = dopamine level in cortex

; Set regional chemical level
; Input:  AL = region index
;         BL = chemical index
;         CL = value (0-255)
extern neuromodulator_set_regional
mov al, NM_REGION_BASAL_GANGLIA
mov bl, NM_DOPAMINE
mov cl, 0xC0  ; High dopamine
call neuromodulator_set_regional

BBB Filtering

; Filter input (carrier-mediated transport)
; Input:  AL = input type
;         RSI = input data pointer
;         RCX = input length
; Output: CF = 1 if accepted, CF = 0 if rejected
extern bbb_filter_carrier
mov al, 0
mov rsi, input_data
mov rcx, input_length
call bbb_filter_carrier
; CF = acceptance flag

; Filter receptor-mediated (targeted commands)
; Input:  AL = target system ID
;         RSI = command data
; Output: CF = 1 if accepted, CF = 0 if rejected
extern bbb_filter_receptor
mov al, SYS_ID_EXEC  ; Target Executive Control
mov rsi, command_data
call bbb_filter_receptor
; CF = acceptance flag

Memory Layout

See Memory Layout for complete address mapping.

Key Addresses

0x202000 - Global chemical levels (6 bytes)
0x202006 - Regional chemical levels (36 bytes: 6 regions × 6 chemicals)
0x20202A - Last update counter (8 bytes)
0x202032 - Event history (16 bytes)
0x202043 - Mood state (1 byte)
0x202044 - Glymphatic active flag (1 byte)
0x202100 - BBB filter state and transport log

Future Development

Planned Enhancements

Glial Cell Simulation: Astrocytes for ion balance, microglia for error scavenging
CSF Circulation: Slow circulation loop distributing modulators
Circadian Rhythms: Time-based chemical cycles
Energy Metabolism: Glucose/energy model affecting processing budget
Local Gradients: Per-region chemical gradients for finer control

Neuromodulator System: Synthetic Neurochemistry