Chapp-E Memory Layout
Complete memory map and address allocation for all system components
Overview
Chapp-E uses a carefully organized memory layout that separates the kernel code from system data structures. This page documents every memory address used in the system, critical for debugging and development.
Memory Regions
Kernel Region (0x100000 - 0x1FFFFF)
The kernel loads at 0x100000 (1MB) as required by the Multiboot specification. This region contains:
- Kernel code and data sections
- Bootloader structures
- Multiboot information
- Page tables and GDT
- Brain Controller state (0x100000-0x1000FF)
- Consciousness System state (0x100100-0x100102)
โ ๏ธ WARNING: Writing to addresses in this region can cause system crashes. Only the Brain Controller and Consciousness systems use small data structures here.
Linker Memory Layout: The linker (chappe-ld) defines memory addresses for executables. These are stored as metadata in the `.chappe` header:
- Code Base: 0x100000 (executable code sections)
- Data Base: 0x200000 (initialized data sections)
- BSS Base: 0x300000 (uninitialized data sections - metadata only)
- Entry Point: 0x100000 (default _start address)
System Data Region (0x200000+)
All system data structures are placed at 0x200000 (2MB) or higher to ensure safe separation from kernel code.
Allocated Systems:
- 0x200000: Working Memory (Executive Control)
- 0x201000: Planning System (Executive Control)
- 0x202000: Neuromodulator System (Limbic System)
- 0x202100: Blood-Brain Barrier (Hypothalamus)
- 0x202200: Hippocampus Module
- 0x202300: Astrocyte Module (Glial Cells)
- 0x202400: Microglia Module (Glial Cells)
- 0x203000: Shell Command System
- 0x204000-0x2FFFFF: Available for future systems
Hardware Memory (0xB8000)
VGA text mode buffer for display output:
- 0xB8000: VGA text buffer (80ร25 characters ร 2 bytes = 4KB)
Complete Memory Map
VGA Text Buffer (0xB8000 - 0xB8F9F)
| Address | Size | Purpose | File |
|---|---|---|---|
0xB8000 |
4KB (80 ร 25 ร 2 bytes) | VGA text mode buffer (80 columns ร 25 rows ร 2 bytes per character) | system/shell/formatting_64.asm |
Format: Each character = 2 bytes (ASCII character + attribute byte)
Attribute Byte: Lower 4 bits = foreground color, upper 4 bits = background color
See Also: I/O System, Formatting System
Brain Controller (0x100000 - 0x1000FF)
| Address | Size | Purpose | File |
|---|---|---|---|
0x100000 |
1 byte | Controller state (INIT, READY, PROCESS, SLEEP, ERROR) | braincontroller_64.asm |
0x100001 |
1 byte | Message queue head pointer | braincontroller_64.asm |
0x100002 |
1 byte | Message queue tail pointer | braincontroller_64.asm |
0x100003 |
253 bytes | Message buffer (circular queue) | braincontroller_64.asm |
Total: 256 bytes (0x100000 - 0x1000FF)
Brain Tick System
The Brain Controller's brain_tick function uses the following memory locations:
| Address | Size | Purpose | File |
|---|---|---|---|
brain_tick_counter (data section) |
8 bytes | Counter for pseudo-random generation in spontaneous activity | braincontroller_64.asm |
0x5200000 |
80KB (10,000 qwords) | Temporary input buffer for spontaneous activity (shared with DAG-FS) | braincontroller_64.asm |
0x52C8000 |
16KB (2,000 qwords) | Temporary output buffer for spontaneous activity forward pass | braincontroller_64.asm |
brain_tick function uses temporary buffers at 0x5200000 and 0x52C8000 for spontaneous neural activity. These are shared with DAG-FS operations but used briefly during each tick cycle.
Consciousness System (0x100100 - 0x100102)
| Address | Size | Purpose | File |
|---|---|---|---|
0x100100 |
1 byte | Current consciousness state (AWAKE=0, SLEEP=1, UNCONSCIOUS=2) | consciousness_64.asm |
0x100101 |
1 byte | Last consciousness state (for state change detection) | consciousness_64.asm |
0x100102 |
1 byte | Power-off flag (0=normal, 1=power-off requested) | consciousness_64.asm |
Total: 3 bytes (0x100100 - 0x100102)
Working Memory System (0x200000 - 0x2000C2)
| Address | Size | Purpose | File |
|---|---|---|---|
0x200000 |
1 byte | Working memory state (IDLE=0, ACTIVE=1, OVERLOADED=2) | working_memory_64.asm |
0x200001 |
1 byte | Number of active memory slots (0-3) | working_memory_64.asm |
0x200002 |
64 bytes | Memory slot 0 (current task) | working_memory_64.asm |
0x200042 |
64 bytes | Memory slot 1 (background task) | working_memory_64.asm |
0x200082 |
64 bytes | Memory slot 2 (interrupt handler) | working_memory_64.asm |
0x2000C2 |
3 bytes | Priority flags (1 byte per slot: HIGH=3, MEDIUM=2, LOW=1, NONE=0) | working_memory_64.asm |
Total: 194 bytes (0x200000 - 0x2000C2)
Capacity: 3 slots ร 64 bytes = 192 bytes of working memory
Planning System (0x201000 - 0x201163)
| Address | Size | Purpose | File |
|---|---|---|---|
0x201000 |
1 byte | Planning state (IDLE=0, PLANNING=1, EXECUTING=2, COMPLETE=3, ERROR=4) | planning_64.asm |
0x201001 |
1 byte | Number of steps in current plan (0-8) | planning_64.asm |
0x201002 |
1 byte | Current step being executed (0-7) | planning_64.asm |
0x201003 |
256 bytes | Plan steps buffer (8 steps ร 32 bytes each) | planning_64.asm |
0x201100 |
64 bytes | Current goal storage | planning_64.asm |
Total: 355 bytes (0x201000 - 0x201163)
Capacity: 8 steps ร 32 bytes = 256 bytes for plan steps, plus 64 bytes for goal
Neuromodulator System (0x202000 - 0x202044)
| Address | Size | Purpose | File |
|---|---|---|---|
0x202000 |
6 bytes | Global chemical levels (Dopamine, Serotonin, Acetylcholine, Cortisol, Noradrenaline, Oxytocin) | neuromodulator_64.asm |
0x202006 |
36 bytes | Regional chemical levels (6 regions ร 6 chemicals = 36 bytes) Regions: Brainstem, Basal Ganglia, Thalamus, Cortex, Limbic, Cerebellum |
neuromodulator_64.asm |
0x20202A |
8 bytes | Last update cycle counter | neuromodulator_64.asm |
0x202032 |
16 bytes | Recent event history (last 8 events: REWARD, ERROR, STRESS, CALM) | neuromodulator_64.asm |
0x202042 |
1 byte | Current history index (0-7, wraps) | neuromodulator_64.asm |
0x202043 |
1 byte | Current mood state (NEUTRAL=0, POSITIVE=1, NEGATIVE=2, STRESSED=3, CALM=4, FOCUSED=5) | neuromodulator_64.asm |
0x202044 |
1 byte | Glymphatic clearance active flag (0=inactive, 1=active during SLEEP) | neuromodulator_64.asm |
Total: 69 bytes (0x202000 - 0x202044)
Chemicals: 6 neuromodulators tracked globally + 36 regional values (6 regions ร 6 chemicals)
Features: Regional distribution, volume transmission (diffusion), glymphatic clearance during sleep
Blood-Brain Barrier (BBB) System (0x202100 - 0x20212A)
| Address | Size | Purpose | File |
|---|---|---|---|
0x202100 |
1 byte | Filter state (ACTIVE=0, BYPASS=1) | bbb_64.asm |
0x202101 |
32 bytes | Transport log (last 16 transports, 2 bytes per entry: type + timestamp) | bbb_64.asm |
0x202121 |
1 byte | Current log index (0-15, wraps) | bbb_64.asm |
0x202122 |
4 bytes | Rejected inputs counter (total rejections) | bbb_64.asm |
0x202126 |
4 bytes | Accepted inputs counter (total acceptances) | bbb_64.asm |
Total: 43 bytes (0x202100 - 0x20212A)
Transport Types: Carrier-Mediated, Receptor-Mediated, Adsorptive, Active Efflux
Function: Selective filtering of inputs before they affect brain regions, protecting against "toxins" (errors, overflows)
Hippocampus Module (0x202200 - 0x20224A)
| Address | Size | Purpose | File |
|---|---|---|---|
0x202200 |
1 byte | Hippocampus state (IDLE, ENCODING, CONSOLIDATING) | hippocampus_64.asm |
0x202201 |
64 bytes | Encoding buffer (temporary storage for slot data) | hippocampus_64.asm |
0x202241 |
1 byte | Number of pending encodings (0-8) | hippocampus_64.asm |
0x202242 |
8 bytes | Pending encoding list (slot IDs to encode) | hippocampus_64.asm |
Total: 73 bytes (0x202200 - 0x20224A)
Functions: Memory encoding (working memory โ DAG-FS), consolidation (sleep replay), retrieval (DAG-FS โ working memory)
See Also: Hippocampus Module, Memory Systems
Astrocyte Module (0x202300 - 0x2023FF)
| Address | Size | Purpose | File |
|---|---|---|---|
0x202300 |
1 byte | Astrocyte state (IDLE, BUFFERING, ALLOCATING) | astrocyte_64.asm |
0x202301 |
1 byte | Current energy level (0-255) | astrocyte_64.asm |
0x202302 |
1 byte | Resource buffer size (0-200) | astrocyte_64.asm |
0x202303 |
200 bytes | Resource buffer (for buffering neural resources) | astrocyte_64.asm |
Total: 256 bytes (0x202300 - 0x2023FF)
See Also: Memory Systems (Biological Heap Allocator section)
Microglia Module (0x202400 - 0x2024FF)
| Address | Size | Purpose | File |
|---|---|---|---|
0x202400 |
1 byte | Microglia state (IDLE, SCANNING, PRUNING, CLEANING) | microglia_64.asm |
0x202401 |
1 byte | Activity level (0-255) | microglia_64.asm |
0x202402 |
1 byte | Prune threshold (weights below this are pruned) | microglia_64.asm |
0x202403 |
1 byte | Garbage count (number of items collected) | microglia_64.asm |
0x202404 |
4 bytes | Current scan position in neural network | microglia_64.asm |
0x202405 |
250 bytes | Work buffer (for scanning and pruning operations) | microglia_64.asm |
Total: 256 bytes (0x202400 - 0x2024FF)
See Also: Memory Systems (Biological Heap Allocator section)
Shell Command System (0x203000 - 0x203FFF)
| Address | Size | Purpose | File |
|---|---|---|---|
0x203000 |
256 bytes | Command input buffer | shell_64.asm |
0x203100 |
1 byte | Buffer position pointer | shell_64.asm |
0x203101 |
64 bytes | Parsed command name buffer | commands_64.asm |
0x203141 |
256 bytes | Arguments buffer | commands_64.asm |
0x203300 |
~1KB | Command table (command name pointers + handler addresses) | commands_64.asm |
0x203700 |
~2KB | Message strings (help text, usage, etc.) | commands_64.asm |
Total: 4KB (0x203000 - 0x203FFF)
Functions: Command parsing, command execution, argument handling, help system
See Also: Command System
DAG-FS Filesystem (0x300000 - 0x4FFFFF)
| Address | Size | Purpose | File |
|---|---|---|---|
0x300000 |
16MB | Pattern Storage (pattern metadata: 64 bytes ร 1024 patterns) | system/filesystem/dagfs_64.asm |
0x400000 |
1MB | Index Storage Base (weight snapshots, text storage) | system/filesystem/dagfs_64.asm |
0x410000 |
64KB | Tag Storage (128 bytes ร 512 tags = 64KB) | system/filesystem/dagfs_tags.asm |
0x420000 - 0x4FFFFF |
~14MB | Additional Index Storage (weight snapshots, text data) | system/filesystem/dagfs_64.asm |
Total: 32MB (0x300000 - 0x4FFFFF)
Pattern Structure: 64 bytes per pattern metadata (pattern ID, tags, nodes, weights, strength, access count, state, file type, file flags)
Max Patterns: 1024 patterns supported (0x300000 - 0x304000)
Tag Structure: 128 bytes per tag (starting at 0x410000), up to 512 tags (0x410000 - 0x41FFFF)
Weight Snapshots: 1024 bytes per pattern (16 inputs ร 8 hidden ร 8 bytes per qword)
Text Storage: 256 bytes per pattern for tag/name strings (0x400000 + pattern_id ร 256)
Storage Mechanism: Patterns stored as weight configurations in neural network layers. Weight snapshots stored in index region.
Implementation Status: โ C-based implementation complete - Pattern storage, reconstruction, tags, completion, Hebbian learning
File Locations: system/kernel/filesystem/dagfs.h, system/kernel/filesystem/dagfs.c
Kernel Integration: Initialized during kernel boot as part of neural development sequence (Stage 4)
See Also: DAG-FS Filesystem for complete documentation
Ghost File System (0x500000 - 0x50FFFF)
| Address | Size | Purpose | File |
|---|---|---|---|
0x500000 |
128KB | Ghost File Table (128 bytes ร 1024 entries = 128KB) | system/filesystem/GHOST_FILES.md (planned) |
Ghost File Entry Structure (128 bytes):
- 0-63: Path string (64 bytes) - The cue/command name
- 64-71: Pattern ID (8 bytes) - Points to DAG-FS pattern
- 72: File type (1 byte) - FILE_TYPE_EXECUTABLE, FILE_TYPE_DATA, etc.
- 73: Flags (1 byte) - File-specific flags
- 74-127: Reserved (54 bytes)
Max Ghost Files: 1024 entries
Status: โณ Planned for Phase 2 (Ghost Files + .chappe Header)
See Also: File Philosophy, DAG-FS Filesystem
100,000 Neuron Network (0x600000+)
| Address | Size | Purpose | File |
|---|---|---|---|
0x600000+ |
~784MB | Synaptic weights (sparse connectivity: 100k neurons ร 1000 connections ร 8 bytes) Layer breakdown: - Layer 1โ2: 10,000 ร 1000 ร 8 = 80MB - Layer 2โ3: 30,000 ร 1000 ร 8 = 240MB - Layer 3โ4: 30,000 ร 1000 ร 8 = 240MB - Layer 4โ5: 28,000 ร 1000 ร 8 = 224MB |
network_100k_64.asm |
0x5000000 - 0x50C7FFF |
800KB | Neuron activations (100,000 neurons ร 8 bytes) | network_100k_64.asm |
0x50C8000 - 0x5197FFF |
800KB | Neuron biases (100,000 neurons ร 8 bytes) | network_100k_64.asm |
0x5190000+ |
~800MB | Sparse connection indices (100k neurons ร 1000 connections ร 8 bytes) | network_100k_64.asm |
0x5200000 |
80KB | Temporary input buffer (10,000 qwords = 80KB, shared with DAG-FS and brain_tick) | dagfs_64.asm, braincontroller_64.asm |
0x52C8000 |
16KB | Temporary output buffer (2,000 qwords = 16KB, shared with DAG-FS and brain_tick) | dagfs_64.asm, braincontroller_64.asm |
Architecture:
- Layer 1 (Input): 10,000 neurons (sensory input)
- Layer 2 (Hidden 1): 30,000 neurons (sparse: ~1000 connections each)
- Layer 3 (Hidden 2): 30,000 neurons (sparse: ~1000 connections each)
- Layer 4 (Hidden 3): 28,000 neurons (sparse: ~1000 connections each)
- Layer 5 (Output): 2,000 neurons (motor/action output)
- Total: 100,000 neurons
Sparse Connectivity: Each neuron connects to ~1000 others (not fully connected), mimicking real brain connectivity patterns. This reduces memory requirements from ~80GB (fully connected) to ~784MB (sparse).
Functions: Forward pass, Hebbian learning, pattern storage and retrieval
Initialization: Network initialized at boot with small random weights and sparse connectivity patterns. Weights modified through Hebbian learning during remember operations.
See Also: DAG-FS Filesystem for how patterns are stored in this network
Neuron Agent System (0x6000000 - 0x65FFFFF)
| Address | Size | Purpose | File |
|---|---|---|---|
0x6000000 - 0x65FFFFF |
96MB | Neuron agent control structures (100,000 neurons ร 16 bytes = 1.6MB, expandable to 96MB) | system/kernel/neural/neuron.c |
0x6000000 + (neuron_id ร 16) |
16 bytes | Per-neuron agent data (expandable) | system/kernel/neural/neuron.c |
0x5000000 |
Variable | Neural network activations | system/kernel/neural/neuron.c |
0x50C8000 |
Variable | Neural network biases | system/kernel/neural/neuron.c |
0x5190000 |
Variable | Neural network connection indices | system/kernel/neural/neuron.c |
0x600000 |
~784MB | Neural network weight matrices (sparse: ~1000 connections per neuron) | system/kernel/neural/neuron.c |
See Also: Neuron Agent System
Memory Layout History & Debugging
The Great Memory Conflict (2024)
During the implementation of the Executive Control layer, we discovered a critical memory mapping issue that caused system crashes during kernel loading.
The Problem
Initially, Working Memory was placed at 0x100200 and Planning System at 0x100300/0x100400. These addresses were too close to the kernel at 0x100000, causing:
- ELF loading crashes in GRUB
- Only 45 bytes writable from
0x100202 - Complete failure at
0x100242(WM_SLOT_1) - System would crash before any debug messages appeared
The Investigation
Through systematic binary search debugging, we discovered:
- 45-byte boundary: Only 45 bytes were writable from
0x100202 - 46-byte crash: Writing the 46th byte caused immediate system crash
- Invalid region:
0x100242(WM_SLOT_1) was completely invalid - Root cause: Memory addresses too close to kernel code region
The Solution
We moved all system data structures to 0x200000 (2MB) or higher:
- Working Memory:
0x100200โ0x200000 - Planning System:
0x100300/0x100400โ0x201000
This provides a full 1MB buffer between the kernel and system data, ensuring complete safety.
Lessons Learned
System Integration Points
How Systems Interconnect
The neuromodulator system integrates with all major brain systems:
Consciousness System Integration
- SLEEP State Trigger: When consciousness enters SLEEP, glymphatic clearance activates
- Mood โ State: High cortisol can force SLEEP state (overload protection)
- State โ Chemicals: AWAKE state allows normal chemical dynamics, SLEEP accelerates clearance
Executive Control Integration
- Working Memory: Acetylcholine levels affect focus and capacity
- Planning System: Dopamine levels influence exploration vs. exploitation
- Regional Modulation: Cortex region chemicals directly affect executive functions
Brain Controller Integration
- BBB Filtering: All inputs pass through BBB before reaching Brain Controller
- Event Recording: Brain Controller events (rewards, errors) update neuromodulators
- System ID Routing: BBB uses system IDs for receptor-mediated transport
- Brain Tick Heartbeat: The
brain_tickfunction continuously calls neuromodulator diffusion and update, ensuring chemicals flow even when idle - Spontaneous Activity: Brain tick generates sparse random neural activity to keep the network "breathing"
Brain Tick System Integration
The brain_tick function is the central heartbeat that integrates all subsystems:
- Neuromodulator Dynamics: Every tick calls
neuromodulator_diffuseandneuromodulator_updatefor continuous chemical flow - Neural Network Activity: Generates spontaneous input and runs forward pass through 100k network
- Glial Maintenance: Calls
microglia_prune_weak_weightsandastrocyte_buffer_resourcefor continuous maintenance - Memory Consolidation: Calls
hippocampus_process_pendingto encode pending memories - Sleep Activities: During SLEEP state, consolidates memories and flushes waste via glymphatic system
- Shell Integration: Shell main loop calls
brain_tickwhen idle, ensuring continuous activity even while waiting for input
Future Integration Points
- Attention Network: Acetylcholine will modulate attention filtering
- Salience Network: Noradrenaline will affect interrupt handling
- Cerebellum: Error correction will update cortisol levels
- Reward System: Will directly boost dopamine in reward pathways
Memory Safety Guidelines
Do's โ
- Place all new system data structures at
0x200000or higher - Keep data structures in the same region (e.g., all Executive Control at 0x200000+)
- Document all memory addresses in this page
- Test memory writes incrementally when adding new systems
- Use clear separation between different systems (at least 4KB apart)
Don'ts โ
- Never place data structures below
0x200000(except Brain Controller and Consciousness) - Don't assume contiguous memory is available near the kernel
- Don't write to addresses without testing incrementally first
- Don't overlap memory regions between systems
- Don't use addresses in the 0x100000-0x1FFFFF range for new systems
Memory Allocation Strategy
For future systems, use this allocation pattern:
0x200000 - 0x200FFF: Working Memory (1KB)
0x201000 - 0x201FFF: Planning System (4KB)
0x202000 - 0x202FFF: [Next System] (4KB)
0x203000 - 0x203FFF: [Next System] (4KB)
...
This provides 4KB (page-aligned) separation between systems, making it easy to track and debug.
Memory Map Summary
| Region | Address Range | Size | System | Status |
|---|---|---|---|---|
| VGA Text Buffer | 0xB8000 - 0xB8F9F |
4KB | VGA Text Mode | โ Active |
| Kernel Code | 0x100000 - 0x1FFFFF |
1MB | Multiboot Kernel | โ Reserved |
| Brain Controller | 0x100000 - 0x1000FF |
256 bytes | Brain Controller | โ Active |
| Consciousness | 0x100100 - 0x100102 |
3 bytes | Consciousness System | โ Active |
| Linker Code Base | 0x100000+ |
Variable | Executable Code Sections (.text) | โ Active |
| Working Memory | 0x200000 - 0x2000C2 |
194 bytes | Executive Control | โ Active |
| Planning System | 0x201000 - 0x201163 |
355 bytes | Executive Control | โ Active |
| Neuromodulator System | 0x202000 - 0x202044 |
69 bytes | Limbic System | โ Active |
| Blood-Brain Barrier | 0x202100 - 0x20212A |
43 bytes | Hypothalamus (Diencephalon) | โ Active |
| Hippocampus | 0x202200 - 0x20224A |
73 bytes | Hippocampus Module | โ Active |
| Astrocyte | 0x202300 - 0x2023FF |
256 bytes | Glial Cells | โ Active |
| Microglia | 0x202400 - 0x2024FF |
256 bytes | Glial Cells | โ Active |
| Shell Command System | 0x203000 - 0x203FFF |
4KB | Shell System | โ Active |
| Available | 0x204000 - 0x2FFFFF |
~1MB | Future Systems | ๐ก Available |
| Linker Data Base | 0x200000+ |
Variable | Initialized Data Sections (.data) | โ Active |
| Linker BSS Base | 0x300000+ |
Variable (metadata only) | Uninitialized Data Sections (.bss) - Stored as metadata in .chappe header, not loaded at this address | โ Metadata Only |
| DAG-FS Pattern Storage | 0x300000 - 0x3FFFFF |
16MB | DAG-FS Filesystem | โ Active |
| DAG-FS Index Storage | 0x400000 - 0x40FFFF |
1MB | DAG-FS Filesystem (weight snapshots, text storage) | โ Active |
| DAG-FS Tag Storage | 0x410000 - 0x41FFFF |
64KB | DAG-FS Filesystem (512 tags ร 128 bytes) | โ Active |
| DAG-FS Additional Index | 0x420000 - 0x4FFFFF |
~14MB | DAG-FS Filesystem (additional weight snapshots, text data) | โ Active |
| Ghost File Table | 0x500000 - 0x50FFFF |
128KB | Ghost File System (1024 entries ร 128 bytes) | โณ Planned |
| 100k Neuron Network - Weights | 0x600000+ |
~784MB | Neural Network (sparse synaptic weights) | โ Active |
| 100k Neuron Network - Activations | 0x5000000 - 0x50C7FFF |
800KB | Neural Network (100,000 neurons ร 8 bytes) | โ Active |
| 100k Neuron Network - Biases | 0x50C8000 - 0x5197FFF |
800KB | Neural Network (100,000 neurons ร 8 bytes) | โ Active |
| 100k Neuron Network - Connections | 0x5190000+ |
~800MB | Neural Network (sparse connection indices) | โ Active |
| Brain Tick - Spontaneous Input Buffer | 0x5200000 |
80KB (temporary, shared with DAG-FS) | Brain Controller (spontaneous activity) | โ Active |
| Brain Tick - Spontaneous Output Buffer | 0x52C8000 |
16KB (temporary) | Brain Controller (spontaneous activity) | โ Active |
| Neuron Agent System | 0x6000000+ |
Variable | Neuron Agent Control Structures (96MB+) | โ Active |
| Available | 0x30000000+ |
Unlimited | Future Systems | ๐ข Available |