SYSTEM.md — head_2 Technical Documentation
CPUAI Bare-Metal Intelligence Simulation
"We're not building AI. We're simulating the idea that intelligence can form — from nothing but reactions, memory, feedback, and curiosity." — Ali (amuzetnoM), April 2025
Version: 1.0 (Phase 1 Complete) Language: C (C11, POSIX) Platform: Linux x86_64 Author: Ali Shakil (amuzetnoM), Artifact Virtual Implementation: AVA Date: 2026-02-15
Table of Contents
- Architecture Overview
- File Interconnections
- Data Structures
- The Sense-Think-Act-Remember-Grow Loop
- Learning System
- Hardware Probing
- Module Loader
- Build Instructions
- Configuration
- Known Limitations
- Future Work
1. Architecture Overview
head_2 implements a digital creature that lives in a simulated 2D grid world. The creature starts with zero knowledge — all response weights are uniform — and develops behavior exclusively through experience and reinforcement. Intelligence (or its approximation) is not programmed; it emerges from the interaction between simple stimulus-response mechanics and a weight-adjustment feedback loop.
The system is decomposed into five subsystems, each in its own source file:
┌──────────────────────────────────────────────────────────────────┐
│ lifeform.c │
│ (Creature + World + Main Loop) │
│ │
│ SENSE → THINK → ACT → REMEMBER → LEARN → GROW │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐ │
│ │ harware_ │ │ thoughts.c │ │ pnp_loader.c │ │
│ │ probe.c │ │ (Cognitive │ │ (Dynamic Module │ │
│ │ (Hardware │ │ Engine) │ │ Loading) │ │
│ │ Self- │ │ │ │ │ │
│ │ Awareness) │ │ │ │ │ │
│ └──────────────┘ └──────────────┘ └────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ memory.h │ │
│ │ (MemoryChain + ResponseWeights + ConceptNodes + │ │
│ │ ThoughtRecords — the creature's complete identity) │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
Design principle: The world is intentionally simple. Complexity emerges from the creature's behavior, not the environment. The world provides stimuli; the creature provides agency.
2. File Interconnections
Dependency Graph
memory.h ─────────────────────────────────────────┐
│ │
▼ │
thoughts.c ──────────────────────────────┐ │
│ (implements all memory.h funcs) │ │
│ (exports name arrays) │ │
▼ ▼ ▼
lifeform.c ◄─── harware_probe.c pnp_loader.c
│ │ │
│ (extern declarations) │
│ (compiled together) │
▼ │
[lifeform binary] ◄─────────────────────┘
File Roles
| File | Size | Role | Dependencies |
|---|---|---|---|
memory.h |
~12KB | Type definitions, constants, function declarations. The "contract" that defines what the creature IS. | None (header-only) |
thoughts.c |
~19KB | Implements all memory_*() functions: recording, learning, concept extraction, action selection, thought generation. The cognitive core. |
memory.h |
lifeform.c |
~47KB | Main simulation: world creation, creature birth, the 6-phase life loop, sensing, thinking, acting, state updates, logging. The orchestrator. | memory.h, extern declarations from harware_probe.c, thoughts.c, pnp_loader.c |
harware_probe.c |
~14KB | Reads CPU, RAM, temperature, uptime from /proc and /sys. Returns a HardwareProfile and a behavior modifier float. |
None (self-contained) |
pnp_loader.c |
~11KB | Scans directories for .so shared libraries, loads them via dlopen/dlsym, manages a module registry. |
<dlfcn.h>, <dirent.h> |
Compilation Model
All five files are compiled together into a single binary via GCC. There are no separate .h files for harware_probe.c or pnp_loader.c — lifeform.c uses extern declarations and forward-declared opaque structs to access their functions. This is a deliberate simplification for Phase 1.
3. Data Structures
3.1 World Representation
typedef struct {
float temperature; // 0-100. Below 20 = cold. Above 70 = hot.
float light_level; // 0-1. 0 = dark. 1 = bright.
int has_food; // 1 = food present
int has_obstacle; // 1 = blocked
float danger; // 0-1. Probability of pain
} WorldCell;
typedef struct {
WorldCell cells[20][20];
int cycle;
float ambient_temp;
float day_night; // 0-1 sinusoidal cycle
} World;
The world is a 20×20 grid with:
- Temperature gradients: Left is cooler, right is warmer, top has a hot zone (≥60°C)
- Light distribution: Center is brightest, edges are darker, modulated by day/night cycle
- Food patches: Sparse scatter plus a central "food garden" (8-12, 8-12)
- Obstacles: Border walls + interior walls at fixed positions
- Danger zones: Correlated with high temperature (>70°C → 0.6 danger, >85°C → 0.9) plus a fixed trap at (5,5)
- Dynamic changes: Day/night cycle (sinusoidal light), ambient temperature drift, 0.5% food regrowth per cell per cycle
3.2 The Creature
typedef struct {
int x, y; // Position in world
int direction; // 0=N, 1=E, 2=S, 3=W
float energy; // 0-100 (death at 0)
float max_energy; // Grows with age (+5 every 500 cycles)
float energy_metabolism; // 0.3 per cycle (breathing cost)
float curiosity; // 0-1, regenerates +0.005/cycle
float fear; // 0-1, decays ×0.98/cycle
float satisfaction; // 0-1, decays ×0.99/cycle
float hunger; // 0-1, computed from energy ratio
float age; // Cycle counter
int alive; // Death flag
MemorySystem memory; // The creature's entire mind
int hw_probed; // Has probed hardware at least once
float hw_modifier; // Behavior modifier from hardware
int hw_probe_cooldown; // Cycles until next probe allowed
} Creature;
3.3 Memory System (the creature's identity)
typedef struct {
MemoryBlock blocks[4096]; // Circular buffer of experiences
uint32_t block_count;
uint32_t block_cursor;
ResponseWeights weights; // Learned stimulus→action mappings
ConceptNode concepts[256]; // Compressed patterns
uint32_t concept_count;
ThoughtRecord thoughts[32]; // Recent internal thoughts
uint32_t thought_count;
uint32_t thought_cursor;
uint64_t total_experiences;
uint64_t total_positive;
uint64_t total_negative;
float lifetime_energy;
time_t birth_time;
uint32_t chain_hash; // Running hash (integrity chain)
} MemorySystem;
3.4 MemoryBlock (a single experience)
Each block captures one moment: what the creature sensed, what it did, what happened, and how it felt at the time. Blocks are hash-chained (each block's hash includes the previous block's hash) creating a tamper-evident, append-only experience log.
typedef struct {
uint32_t id;
uint32_t hash; // FNV-1a hash of this block
uint32_t prev_hash; // Previous block's hash (chain)
time_t timestamp;
StimulusType stimulus;
float stimulus_intensity;
ActionType action_taken;
float confidence;
Outcome outcome;
float energy_delta;
float energy_level;
float curiosity_level;
float fear_level;
float age;
} MemoryBlock;
3.5 ResponseWeights (the creature's learned soul)
typedef struct {
float weights[12][8]; // weights[stimulus][action]
float learning_rate; // Starts 0.15, decays ×0.995 per 100 updates
float exploration_rate; // Starts 0.25, decays ×0.99 per 200 updates
float decay_rate; // 0.001 — uniform regression speed
uint64_t total_updates;
} ResponseWeights;
This 12×8 matrix IS the creature's personality. Each cell is the probability weight for choosing action a when stimulus s is detected. Initially all 1/8 = 0.125 (uniform). Over time, positive outcomes inflate weights and negative outcomes deflate them, creating an asymmetric preference landscape.
3.6 ConceptNode (compressed wisdom)
typedef struct {
uint32_t id;
StimulusType stimulus;
ActionType best_action;
float confidence;
uint32_t supporting_memories;
float avg_outcome;
time_t last_updated;
int active;
} ConceptNode;
Concepts are extracted every 50 cycles by scanning the most recent 500 memories. For each stimulus type, the system finds the action with the highest average outcome score and records it as a concept with confidence proportional to that average.
3.7 Enumerations
Stimulus Types (12): NONE, HEAT, COLD, LIGHT, DARK, OBSTACLE, FOOD, PAIN, COMFORT, CURIOSITY, HARDWARE, UNKNOWN
Action Types (8): NOTHING, MOVE_FORWARD, MOVE_BACK, TURN_LEFT, TURN_RIGHT, CONSUME, PROBE, WAIT
Outcomes (4): NEUTRAL (0), POSITIVE (+1), NEGATIVE (-1), FATAL (-2)
Thought Types (8): INSTINCT, REFLECTION, PREDICTION, CURIOSITY, FEAR, SATISFACTION, CONFUSION, SELF_AWARE
4. The Sense-Think-Act-Remember-Grow Loop
Each simulation cycle executes six phases:
Phase 1: SENSE (creature_sense())
The creature examines the world cell it occupies and determines the dominant stimulus — the most intense signal from the environment or its internal state. Stimuli are evaluated in this priority order:
- Temperature extremes — Heat (>65°C) or cold (<25°C)
- Food — Amplified by hunger (
0.5 + 0.5 × hunger) - Obstacle — When facing a wall/obstacle (intensity 0.7)
- Danger/Pain — Probabilistic based on danger level
- Light/Dark — Only registered when nothing else is dominant (intensity <0.3)
- Internal curiosity — When curiosity >0.7 and nothing else pressing
- Hardware curiosity — Triggered when not yet probed and curiosity >0.5, or after cooldown with curiosity >0.8
- Comfort — Default when nothing bad is happening and energy >50
The function returns the dominant StimulusType and its intensity (0.0–1.0).
Phase 2: THINK (creature_think())
The creature generates internal thoughts that influence (but don't determine) action selection:
- Hunger instinct: When hunger >0.6, suggests seeking food
- Fear response: Pain stimulus triggers fear increase (+0.2) and suggests retreat
- Curiosity drive: Unknown or hardware stimuli trigger investigation thoughts
- Reflection: Checks formed concepts — "I remember: when I sense X, doing Y works"
- Prediction: Fear >0.5 + heat/obstacle → "This could hurt, be careful"
- Satisfaction: Comfort + good energy → satisfaction increase
- Self-awareness: Hardware stimulus → "What am I? What is this body made of?"
- Near-death realization: Energy <15 → fear thought about dying
Thoughts are recorded in the ThoughtChain (circular buffer of 32) via memory_think().
Phase 3: ACT (creature_act() + memory_choose_action())
Action selection uses the ResponseWeights matrix with two mechanisms:
Exploration (probability =
exploration_rate): Random action selection. This is pure curiosity — "what if I try something new?" Modified by:- Fear >0.5 → exploration rate ×0.3
- Hunger >0.8 → exploration rate ×0.2
Exploitation (probability =
1 - exploration_rate): Weighted probabilistic selection from the learned weight distribution for the current stimulus. Not argmax — still stochastic, but biased toward high-weight actions.
Instinct override: When standing on food with hunger >0.5, an instinct override may force ACT_CONSUME. This override probability decreases with age: 0.8 - (age/max_cycles × 0.6), simulating the transition from instinct to learned behavior.
Action consequences:
| Action | Energy Cost | Outcome |
|---|---|---|
| MOVE_FORWARD | -0.5 | Positive if food at destination; negative if danger or wall |
| MOVE_BACK | -0.5 | Neutral; positive if retreating from danger |
| TURN_LEFT/RIGHT | -0.1 | Neutral |
| CONSUME | +25.0 (food) / -0.2 (no food) | Positive/negative |
| PROBE | -1.0 | Positive if food nearby; neutral otherwise |
| WAIT | -0.15 | Positive if energy >60 |
| NOTHING | -0.3 (metabolism) | Neutral |
Energy costs are modified by the hardware behavior modifier: delta × (2.0 - hw_modifier).
Phase 4: REMEMBER (memory_record())
The experience is recorded as a MemoryBlock in the circular buffer (capacity: 4096). The block includes:
- Stimulus type and intensity
- Action taken and confidence (current weight for that stimulus-action pair)
- Outcome and energy delta
- Internal state snapshot (energy, curiosity, fear, age)
- Hash chain link (prev_hash → this block's hash → next block's prev_hash)
The hash chain uses FNV-1a (seed: 0xDEAD), creating an immutable history.
Phase 5: LEARN (memory_learn())
This is the most critical function in the system. Learning modifies the ResponseWeights matrix:
POSITIVE outcome:
w[stimulus][action] += lr × (1.0 - w[stimulus][action]) // Reinforce
w[stimulus][other] *= (1.0 - lr × 0.1) // Slightly suppress alternatives
NEGATIVE outcome:
w[stimulus][action] *= (1.0 - lr) // Punish
w[stimulus][other] += lr × 0.05 // Slightly boost alternatives
FATAL outcome:
w[stimulus][action] *= (1.0 - lr × 3.0) // Strong punishment
w[stimulus][MOVE_BACK] += lr × 0.5 // Boost retreat
w[stimulus][TURN_*] += lr × 0.2 // Boost turning
NEUTRAL outcome:
All weights regress toward uniform (1/8) at decay_rate // Slow forgetting
After every update, weights are normalized to sum to 1.0 (probability distribution). No weight drops below 0.001 — there's always a chance of any action.
Adaptive rates:
- Learning rate decays ×0.995 every 100 updates (young brains learn fast → crystallized intelligence)
- Exploration rate decays ×0.99 every 200 updates (newborns explore everything → elders stick to what works)
- Minimum learning rate: 0.02
- Minimum exploration rate: 0.05
Phase 6: GROW (creature_update_state() + world_update())
Creature updates:
- Metabolism: energy -= 0.3 per cycle
- Hunger:
1.0 - (energy / max_energy) - Curiosity regeneration: +0.005/cycle (capped at 1.0)
- Fear decay: ×0.98/cycle (time heals)
- Satisfaction decay: ×0.99/cycle (hedonic treadmill)
- Max energy growth: +5 every 500 cycles (fitness)
- Death check: energy ≤ 0 → creature dies
- Hardware probe cooldown decrement
World updates:
- Day/night cycle:
0.5 + 0.5 × sin(cycle × 0.02) - Ambient temperature drift:
40 + 15 × sin(cycle × 0.005) - Food regrowth: 0.5% chance per empty non-obstacle cell per cycle
- Temperature and danger recalculation based on ambient
Concept extraction runs every 50 cycles via memory_extract_concepts(), scanning the 500 most recent memories to find the best-performing action for each stimulus type.
5. Learning System
5.1 Reinforcement Learning Model
The system implements a form of tabular reinforcement learning where:
- States = stimulus types (12 discrete categories)
- Actions = 8 discrete choices
- Rewards = outcome values (+1, 0, -1, -2)
- Policy = normalized weight distribution per stimulus (the ResponseWeights matrix)
- Update rule = custom multiplicative/additive reinforcement (not Q-learning or SARSA)
The update rule differs from standard RL in several ways:
- Multiplicative punishment (instead of additive): negative outcomes multiply the weight by
(1 - lr), creating exponential decay - Cross-action influence: outcomes affect alternative actions too (positive suppresses alternatives; negative boosts them)
- FATAL outcome hardcoding: near-death experiences specifically boost retreat and turning actions regardless of the stimulus, creating an innate survival instinct
- Neutral decay toward uniform: without reinforcement signals, preferences slowly fade — modeling biological forgetting
5.2 Concept Formation
Concepts are a second level of knowledge representation above raw weights. Every 50 cycles, the system:
- Scans the 500 most recent memory blocks
- For each stimulus type, tallies action counts and cumulative outcome scores
- Finds the action with the highest average outcome (requires ≥3 data points)
- Creates or updates a
ConceptNodewith: best action, confidence (normalized avg outcome), supporting memory count
Concepts serve two purposes:
- Reflection thoughts: The creature can recall "I remember: when I sense heat, moving back works (87% sure)"
- Research output: Concepts are the primary evidence of emergent intelligence — compressed wisdom from raw experience
5.3 Weight Normalization
After every learning update, the weight vector for the current stimulus is normalized:
- Floor at 0.001 (no action is ever impossible)
- Sum all weights
- Divide each by the sum
This ensures weights always form a valid probability distribution.
6. Hardware Probing
The hardware probe (harware_probe.c) reads system information from Linux virtual filesystems:
| Probed Attribute | Source | Creature Interpretation |
|---|---|---|
| CPU cores | sysconf(_SC_NPROCESSORS_ONLN) |
"How many minds do I have?" |
| CPU model | /proc/cpuinfo → model name |
"What kind of brain am I?" |
| CPU frequency | /proc/cpuinfo → cpu MHz |
"How fast do I think?" |
| Cache size | /proc/cpuinfo → cache size |
"How much short-term memory?" |
| Hyperthreading | /proc/cpuinfo → siblings vs cpu cores |
Thread count detection |
| Total RAM | /proc/meminfo → MemTotal |
"How much can I hold?" |
| Available RAM | /proc/meminfo → MemAvailable |
"How full am I?" |
| CPU temperature | /sys/class/thermal/thermal_zone{0,1}/temp or /sys/class/hwmon/hwmon0/temp1_input |
"How warm am I?" |
| System uptime | /proc/uptime |
"How long have I existed?" |
| Load average | /proc/loadavg |
"How hard am I working?" |
Probe Depth (0–5)
Self-knowledge is measured in layers:
- Layer 1: CPU discovered (cores > 0)
- Layer 2: Memory discovered (RAM > 0)
- Layer 3: Temperature sensed (thermal data available)
- Layer 4: System awareness (uptime > 0)
- Layer 5: Full awareness (all four layers succeeded)
Behavior Modifier
The probe returns a float (0.5–2.0) that affects the creature's energy costs:
Temperature >80°C → modifier ×0.5 (thermal throttling)
Temperature >65°C → modifier ×0.8 (warm, cautious)
Temperature <40°C → modifier ×1.1 (cool, push harder)
Cores ≥8 → modifier ×1.3 (parallel power)
Cores ≥4 → modifier ×1.1
RAM usage >90% → modifier ×0.7 (memory pressure)
RAM usage >75% → modifier ×0.9
Applied to energy costs as: delta × (2.0 - modifier). Higher modifier → lower costs.
Probe Triggers
- Initial: Always probed at birth (cycle 0)
- First curiosity: After age 50, if curiosity >0.5 and no stronger stimulus
- Repeat: After cooldown (200 cycles), if curiosity >0.8 and no stronger stimulus
7. Module Loader
The plug-and-play loader (pnp_loader.c) implements runtime capability extension via dlopen/dlsym.
Module Interface Contract
External modules (.so shared libraries) must export:
const char *module_name(void); // Required
const char *module_describe(void); // Optional
int module_init(void); // Optional (return 0 = success)
int module_execute(float *input, float *output, int len); // Required
void module_cleanup(void); // Optional
Registry
typedef struct {
Module modules[16]; // Max 16 modules
int count;
char search_path[512]; // Directory to scan (default: ./modules)
int scan_complete;
} ModuleRegistry;
Lifecycle
pnp_init()— Initialize registry with search pathpnp_scan()— Scan directory for.sofiles (does NOT load them)pnp_load()—dlopena specific module, resolve symbols, callmodule_init()pnp_execute()— Callmodule_execute()with float arrays, track usage statspnp_unload()— Callmodule_cleanup(), thendlclose()pnp_cleanup()— Unload all modules
Current Status
In Phase 1, the module loader is initialized and scans for modules, but no .so modules are shipped. The infrastructure is in place for Phase 2 extensions (e.g., internet fetch, advanced sensors, neural network layers).
8. Build Instructions
Prerequisites
| Dependency | Required For | Version |
|---|---|---|
| GCC | Compilation | Any C11-capable version |
| GNU Make | Build system | Any |
| Linux | /proc, /sys access for hardware probing |
Any modern kernel |
| libm | Math functions (sinf, sqrtf) |
Standard |
| libdl | Dynamic module loading (dlopen) |
Standard |
Build
cd head_2/
make # Produces ./lifeform binary
Compiler flags: -Wall -Wextra -O2 -std=c11 -D_POSIX_C_SOURCE=200809L
Linker flags: -lm -ldl
Run
# Default: 2000 cycles
./run_simulation.sh
# Custom cycles
./run_simulation.sh 5000
# Verbose (log every cycle)
./run_simulation.sh 5000 verbose
# Direct execution with options
./lifeform -c 10000 -v -l logs/experiment.log
Command-Line Options
| Flag | Description | Default |
|---|---|---|
-c <N> |
Number of simulation cycles | 2000 |
-v |
Verbose logging (every cycle) | Off |
-l <path> |
Log file path | logs/simulation.log |
-h |
Help | — |
Output Files
- Console: Periodic status reports (every 100 cycles), final report with concepts and weights
- Log file:
logs/simulation_<timestamp>.log— complete history - Weight matrix: Printed at end — the creature's learned preferences
- Concept list: Printed at end — compressed wisdom
9. Configuration
All configuration is via #define constants in lifeform.c:
| Constant | Value | Description |
|---|---|---|
WORLD_WIDTH |
20 | Grid width |
WORLD_HEIGHT |
20 | Grid height |
SIMULATION_CYCLES |
2000 | Default cycle count |
REPORT_INTERVAL |
100 | Status report frequency |
CONCEPT_INTERVAL |
50 | Concept extraction frequency |
HW_PROBE_INTERVAL |
200 | Hardware probe cooldown |
ENERGY_START |
50.0 | Initial energy |
ENERGY_MAX_START |
100.0 | Initial max energy |
ENERGY_PER_FOOD |
25.0 | Energy from eating |
ENERGY_METABOLISM |
0.3 | Per-cycle breathing cost |
ENERGY_MOVE_COST |
0.5 | Movement energy cost |
ENERGY_PROBE_COST |
1.0 | Investigation energy cost |
Memory system constants in memory.h:
| Constant | Value | Description |
|---|---|---|
MAX_MEMORY_BLOCKS |
4096 | Circular buffer capacity |
MAX_CONCEPT_NODES |
256 | Max concepts |
MAX_THOUGHT_DEPTH |
32 | Thought buffer depth |
MEMORY_HASH_SEED |
0xDEAD | FNV-1a hash seed |
Learning parameters (set in memory_init()):
| Parameter | Initial Value | Decay |
|---|---|---|
| Learning rate | 0.15 | ×0.995 every 100 updates |
| Exploration rate | 0.25 | ×0.99 every 200 updates |
| Decay rate | 0.001 | Fixed |
10. Known Limitations
Architectural
- Single-threaded: The simulation runs sequentially. The creature cannot think and act simultaneously.
- Flat state space: Stimulus types are discrete categories, not continuous. The creature cannot distinguish between "slightly warm" and "very hot" as separate stimuli — only "heat" with varying intensity.
- No spatial memory: The creature has no map. It cannot remember where food was or plan routes.
- No temporal sequences: Learning is per-stimulus, not per-sequence. The creature cannot learn "do A then B then C."
- Opaque struct workarounds:
lifeform.credeclaresHardwareProfileand uses opaque memory forModuleRegistryinstead of proper header separation. This works but is fragile.
Learning
- No negative reward shaping: The creature has no way to learn "the absence of negative is good." It only learns from explicit positive/negative signals.
- Local perception only: The creature sees only its current cell. No adjacent-cell awareness for navigation (except obstacle checking in facing direction).
- Instinct override: The hunger-driven food consumption override partially bypasses the learning system, though it decays with age.
Technical
- Linux-only: Hardware probing reads from
/procand/sys. No macOS, Windows, or bare-metal support in Phase 1. - No state persistence: The creature dies at simulation end. No save/load mechanism.
- Fixed world seed:
srand()uses time, but world generation is deterministic (same layout every run). Only creature behavior varies. - Module loader untested: No
.somodules are provided. The loader has been compiled but not exercised with real modules.
11. Future Work
Phase 2 (Planned)
- Multi-creature simulation: Multiple creatures in the same world — competition for food, communication, predator-prey dynamics
- Bare-metal deployment: Port to run on raw hardware without an OS (the original vision from PLAN.md). Target: Alpine Linux on a dedicated machine with USB-mounted modules.
- Neural expansion: Add a simple neural network layer on top of the weight matrix for pattern recognition in more complex environments
- Internet fetch engine: A loadable module that lets the creature fetch data from the internet and incorporate it into its world model
- Persistent memory: Save/load creature state (weights, concepts, memories) across simulation runs
- Genetic algorithms: Run populations of creatures, breed the fittest, observe evolution across generations
- Richer environments: 3D worlds, more stimulus types, continuous (not discrete) sensation
- Multi-modal sensing: Adjacent cell awareness, direction-sensitive perception, memory-based path planning
- Emotional model expansion: More nuanced emotional states beyond the current four (curiosity, fear, satisfaction, hunger)
"Each part is real. Each test is honest." — amuzetnoM