# 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

1. [Architecture Overview](#1-architecture-overview)
2. [File Interconnections](#2-file-interconnections)
3. [Data Structures](#3-data-structures)
4. [The Sense-Think-Act-Remember-Grow Loop](#4-the-sense-think-act-remember-grow-loop)
5. [Learning System](#5-learning-system)
6. [Hardware Probing](#6-hardware-probing)
7. [Module Loader](#7-module-loader)
8. [Build Instructions](#8-build-instructions)
9. [Configuration](#9-configuration)
10. [Known Limitations](#10-known-limitations)
11. [Future Work](#11-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

```c
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

```c
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)

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

```c
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)

```c
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)

```c
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:

1. **Temperature extremes** — Heat (>65°C) or cold (<25°C)
2. **Food** — Amplified by hunger (`0.5 + 0.5 × hunger`)
3. **Obstacle** — When facing a wall/obstacle (intensity 0.7)
4. **Danger/Pain** — Probabilistic based on danger level
5. **Light/Dark** — Only registered when nothing else is dominant (intensity <0.3)
6. **Internal curiosity** — When curiosity >0.7 and nothing else pressing
7. **Hardware curiosity** — Triggered when not yet probed and curiosity >0.5, or after cooldown with curiosity >0.8
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:

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

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:
1. **Multiplicative punishment** (instead of additive): negative outcomes multiply the weight by `(1 - lr)`, creating exponential decay
2. **Cross-action influence**: outcomes affect alternative actions too (positive suppresses alternatives; negative boosts them)
3. **FATAL outcome hardcoding**: near-death experiences specifically boost retreat and turning actions regardless of the stimulus, creating an innate survival instinct
4. **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:

1. Scans the 500 most recent memory blocks
2. For each stimulus type, tallies action counts and cumulative outcome scores
3. Finds the action with the highest average outcome (requires ≥3 data points)
4. Creates or updates a `ConceptNode` with: 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:
1. Floor at 0.001 (no action is ever impossible)
2. Sum all weights
3. 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:

```c
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

```c
typedef struct {
    Module  modules[16];        // Max 16 modules
    int     count;
    char    search_path[512];   // Directory to scan (default: ./modules)
    int     scan_complete;
} ModuleRegistry;
```

### Lifecycle

1. **`pnp_init()`** — Initialize registry with search path
2. **`pnp_scan()`** — Scan directory for `.so` files (does NOT load them)
3. **`pnp_load()`** — `dlopen` a specific module, resolve symbols, call `module_init()`
4. **`pnp_execute()`** — Call `module_execute()` with float arrays, track usage stats
5. **`pnp_unload()`** — Call `module_cleanup()`, then `dlclose()`
6. **`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

```bash
cd head_2/
make            # Produces ./lifeform binary
```

Compiler flags: `-Wall -Wextra -O2 -std=c11 -D_POSIX_C_SOURCE=200809L`
Linker flags: `-lm -ldl`

### Run

```bash
# 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.c` redeclares `HardwareProfile` and uses opaque memory for `ModuleRegistry` instead 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 `/proc` and `/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 `.so` modules 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