Simple AGI

# simple-AGI
## Emergent Artificial Intelligence for Minecraft

> **Minecraft Forge 1.20.1 · Java 17 · Mod ID: `simple_agi`**

[🇺🇦 Українська версія](README.md)

—

**simple-AGI** is a Minecraft Forge mod that replaces the vanilla mob AI with a full cognitive pipeline.

“`
Body → Hormones → Emotions → Memory → MindContext → Decision → Action
“`

Each AGI entity (mob) owns a brain with **emotions, memory, hormones, social bonds, a spatial belief map, instincts, and genetically inherited species traits**. The system is fundamentally **stochastic** — two identical mobs in the same conditions will make different choices, producing an emergent living ecosystem.

—

## Table of Contents

– [Features](#features)
– [How It Works](#how-it-works)
– [Architecture](#architecture)
– [Commands](#commands)
– [Technical Details](#technical-details)
– [Requirements](#requirements)
– [Installation](#installation)
– [Quick Start](#quick-start)

—

## Features

### 1. Cognitive Stack (7 Layers)

| Layer | Component | Description |
|——-|———–|————-|
| **Layer 1** | Body / Perception | Health, movement, attack, environment scanning |
| **Layer 2** | Hormones / Emotions | 7 hormones → 8 emotions (fear, grief, loneliness, confidence, etc.) |
| **Layer 3** | Memory | Episodic memory with emotional weighting, persistent disk storage |
| **Layer 4** | Social | Signal field, emotional contagion, bonds, species disposition |
| **Layer 5** | Cognition | MindContext (50+ fields), DecisionEngine (16 rule blocks), role system |
| **Layer 6** | Decision | ActionField with softmax + stochastic sampling (NOT argmax!) |
| **Layer 7** | Execution | MobAgentBody — move, attack, flee, stop |

### 2. Hormones & Emotions

**7 Hormones:**
– `adrenaline` — rapid threat spike
– `cortisol` — chronic stress
– `dopamine` — reward for exploration
– `serotonin` — environment stability
– `oxytocin` — social proximity
– `hormoneAggression` — combat readiness
– `melatonin` — night-cycle rhythm

**8 Emotions:**
– `fear`, `confidence`, `grief`, `loneliness`, `comfort`, `peacefulness`, `boredom`, `stress`

### 3. Memory & Spatial Belief Map

– **MemorySystem** — weighted episodic memory (max 100 events). Importance = base × (1 + fear + adrenaline × 0.5). Events decay over time.
– **WorldModel** — spatial belief map (8-block grid). Each zone has `danger`, `food`, `safety`, `familiarity` with time-based decay.
– **PersistentMemoryManager** — disk persistence in JSON: `cognitive_data/entity/<uuid>.json`, `species/<type>.json`, `world/danger_zone.json`.

### 4. Social System

– **LocalSignalField** — spatial signal field (`DANGER`, `FOOD`, `ATTACK`, `HELP`, `SAFE`, `RETREAT`). Signals decay over ~143 ticks.
– **SocialExchangeSystem** — emotional contagion between mobs (fear-comfort transmission), bond reinforcement.
– **AttachmentSystem** — home + bonds to allies. Grief at ally death scales with bond strength.
– **ResourceExchangeSystem** — item trading between mobs (`OFFER_ITEM`, `ACCEPT_ITEM`).

### 5. Species Knowledge Inheritance

– **SpeciesKnowledgeStore** — cross-generation trait inheritance:
  – `caution`, `aggression`, `curiosity`, `playerHostility`
  – `generations` — generation counter
– On mob death, traits pass to the next generation with 70% weight.

### 6. Emergent Language

– **Phoneme** — 16-symbol alphabet (4 energy groups).
– **Utterance** — word (1–3 phonemes), unique int key for O(1) lookup.
– **LexiconEntry** — meaning vector (6 slots: DANGER, FOOD, SAFE, ATTACK, RETREAT, CONTACT).
– Language emerges spontaneously: a mob sees danger → makes a sound → a neighbor hears it during the threat → association reinforces → shared lexicon.
– Words with confidence `+0.55` are inherited across generations.

### 7. Build System

– **BuildPlanner** + **BuildExecutor** — planning and construction.
– Bot can build from templates: `shelter`, `small_house`, `farm`, `wall`, `pillar`.
– Features: inventory check, stall detection, retry logic.

### 8. Group Capability Assessment

– Scans `20-block` radius to identify allies and threats.
– States: `DOMINANT` (ratio > 1.4), `CONTESTED` (0.5–1.4), `VULNERABLE` (< 0.5), `ALONE`.
– Influences FLEE/ATTACK in the DecisionEngine.

### 9. Role System

Automatically assigned by context:
– `LEADER` — dominant group → broadcasts ATTACK signals
– `SCOUT` — high dopamine → boosts EXPLORE
– `ATTACKER` — aggressive state → boosts ATTACK
– `DEFENDER` — protects allies
– `FOLLOWER` — follows leader

### 10. Trauma Propagation

When a mob dies within a 24-block radius:
– Witnesses gain `fear` + `grief` (attenuated by distance).
– Allies receive `allyBonus` + `bondGrief` (scaled by bond strength).
– `RevengeMotive` activates.
– Adrenaline spike, emotional memory log, and `DEATH` WorldModel event trigger.

—

## How It Works

### Full Brain Cycle (per server tick)

“`
SERVER TICK (every N ticks)
│
├─ AttachedMobController → loops over all AGENTS (up to 150)
│   │
│   ├─ 1. BODY:       Homeostasis.quickTick(), FeelingsSystem.tick(), RevengeMotive.tick()
│   ├─ 2. SOCIAL:      SocialExchange (every 40 ticks)
│   ├─ 3. THREAT:      findNearestThreat() → memory → DANGER/HELP signal → WorldModel
│   ├─ 3b. WORLDMODEL: markVisited(); tick() (every 20 ticks)
│   ├─ 4. TIME:        dayTime, isNight, isSunset, isSunrise
│   ├─ 5. GROUP:       GroupCapabilityModel (every 30 ticks)
│   ├─ 6. REVENGE:     RevengeMotive.getKillerEntity()
│   ├─ 7. SIGNALS:     LocalSignalField.senseIntensity ×6 types
│   ├─ 7a. FOOD:       scanNearestFood (every 25 ticks)
│   ├─ 7b. ZONES:      findSafeZone / findFoodZone (every 40 ticks)
│   ├─ 8. MindContext: full snapshot (50+ fields)
│   ├─ 9. DecisionEngine: 16 rule blocks → ActionField
│   ├─ 10. ProfileBias: species-specific instincts
│   ├─ 11. RoleSystem: role-based field shift
│   ├─ softmaxNormalize() → sample() → ActionIntent
│   ├─ 12. executeForMob(): MobAgentBody executes action
│   ├─ 13. MicroBehavior (if IDLE/EXPLORE)
│   └─ 14. MemoryDecay: decayEntityRecords() + decayImportance()
“`

### DecisionEngine (16 Rule Blocks)

| Block | Description | Key Factors |
|——-|————-|————-|
| Block 1 | **FLEE** | fear × 0.45, cortisol × 0.20, critical health < 25% |
| Block 2 | **ATTACK** | aggressionTrait × 0.30, hormoneAggression × 0.35, adrenaline × 0.20 |
| Block 3 | **EXPLORE** | curiosityTrait × 0.30, dopamine × 0.25, boredom × 0.25 |
| Block 4 | **IDLE** | peacefulness × 0.30, grief × 0.45 (paralysis) |
| Block 5 | **EAT / MOVE_TO_FOOD** | hungerRatio × 0.60, nearestFood bonus |
| Block 6 | **Cave penalty** | isInCave + dark → FLEE↑, IDLE↑ for non-aggressors |
| Block 7 | **Semantic food** | semanticFoodScore > 0.1 → EXPLORE↑ |
| Block 8-11 | **Signal blocks** | sigDanger, sigFood, sigAttack, sigHelp, sigSafe, sigRetreat |
| Block 12 | **Home pull** | homesickness > 0.3 → MOVE_TO(home) |
| Block 13 | **Temporal** | isNight + avoidsSun → IDLE↑, FLEE↑ |
| Block 14 | **Revenge** | revengeMotive > 0.4 → ATTACK(revengeTarget) |
| Block 15 | **GroupCapability** | DOMINANT → ATTACK↑; VULNERABLE → FLEE↑ |
| Block 16 | **WorldModel** | zoneDanger > 0.35 → FLEE↑; familiarity < 0.05 → EXPLORE↑ |

### Stochasticity

`ActionField.sample()` uses **softmax + random sampling** instead of argmax. This means **no mob is predictable** — the same mob in the same conditions may choose differently, following a flexible probability distribution.

—

## Architecture

### Project Structure

“`
src/main/java/com/rayman/
├── action/
│   ├── ActionExecutor.java         — Action execution (move, attack, flee, eat, explore)
│   ├── ActionField.java            — Probability weight field (softmax + sample)
│   └── ActionIntent.java           — Action intent (with target)
├── ai/
│   ├── AttachedMobController.java  ← CENTRAL ORCHESTRATOR
│   ├── AgiGoal.java                — Minecraft Goal API wrapper
│   └── AIController.java           — BotEntity controller
├── body/
│   ├── BotEntity.java              — Dedicated AI player-like entity
│   ├── MobAgentBody.java           — Move/attack/stop for any Mob
│   ├── AgentBody.java              — Base body interface
│   ├── InventorySystem.java        — Inventory management
│   └── core/
│       ├── Homeostasis.java        — Body state aggregator
│       ├── HormoneSystem.java      — 7-hormone system
│       ├── FeelingsSystem.java     — 8-emotion system
│       ├── InstinctSystem.java     — Basic instincts
│       ├── ReflexSystem.java       — Reflexes
│       ├── NervousSystem.java      — Nervous system
│       ├── FatigueSystem.java      — Fatigue
│       ├── PainSystem.java         — Pain
│       └── TemperatureSystem.java  — Temperature
├── core/
│   ├── MindContext.java            ← COGNITIVE STATE SNAPSHOT (50+ fields)
│   ├── DecisionEngine.java         ← 16 RULE BLOCKS
│   ├── ActionScheduler.java        — Action scheduler
│   ├── AttentionSystem.java        — Attention system
│   ├── GoalSystem.java             — Goals
│   ├── MotivationSystem.java       — Motivation
│   ├── PredictionSystem.java       — Prediction
│   ├── FailureModel.java           — Failure model
│   ├── StabilityGovernor.java      — Behavior stability
│   ├── SkillSystem.java            — Skills
│   ├── GroupCapabilityModel.java   — Force balance assessment
│   ├── RevengeMotive.java          — Revenge motive
│   ├── RoleSystem.java             — Role system
│   ├── CognitiveLayer.java         — Cognitive layer interface
│   └── MicroBehaviorSystem.java    — Small animations
├── memory/
│   ├── MemorySystem.java           — Episodic memory
│   └── PersistentMemoryManager.java — Persistent JSON storage
├── perception/
│   ├── PerceptionSystem.java       — Perception system
│   ├── AttentionFocus.java         — Attention focus (central/peripheral)
│   ├── VisualMemory.java           — Visual memory
│   ├── VisibilityResolver.java     — Visibility resolution
│   ├── DynamicVisibility.java      — Dynamic visibility
│   └── PerceptionResult.java       — Perception result
├── personality/
│   ├── Personality.java            — Personality
│   ├── FeelingsSystem.java         — Emotional system
│   └── SelfModel.java              — Self-model
├── social/
│   ├── LocalSignalField.java       — Spatial signal field
│   ├── SocialExchangeSystem.java   — Emotional exchange
│   ├── AttachmentSystem.java       — Bonds and home
│   ├── SocialMemory.java           — Disposition toward entities
│   ├── SpeciesKnowledgeStore.java  — Cross-generation memory
│   ├── SpeciesMind.java            — Inherited traits
│   ├── MobBehaviorProfile.java     — Species behavior profile
│   ├── CognitiveTier.java          — Cognitive tier
│   └── ResourceExchangeSystem.java — Item exchange
├── language/
│   ├── LanguageSystem.java         — Language processor
│   ├── Phoneme.java                — 16-symbol alphabet
│   ├── Utterance.java              — Word (1–3 phonemes)
│   ├── LexiconEntry.java           — Lexicon entry (meaning vector)
│   ├── SpeciesLexicon.java         — Species lexicon
│   ├── Ukrainian*                  — Ukrainian language extensions
│   └── OntologicalRoot.java        — Ontological root
├── build/
│   ├── BuildPlanner.java           — Build planning
│   ├── BuildExecutor.java          — Build execution
│   ├── BuildValidator.java         — Plan validation
│   └── BuildProgress.java          — Progress tracking
├── structure/
│   ├── StructureTemplate.java      — Building template
│   └── TemplateLibrary.java        — Template library
├── world/
│   ├── WorldModel.java             — Spatial belief map
│   └── WorldState.java             — World state
├── SimpleAgi.java                ← Main mod class
├── Config.java                   Configuration
└── ARCHITECTURE.md               Full architectural documentation
“`

—

## Commands

| Command | Description |
|———|————-|
| `/gamerule globalCognition true/false` | Auto-attach AGI to all new mobs |
| `/simpleagi spawn` | Create BotEntity |
| `/simpleagi kill` | Remove BotEntity |
| `/simpleagi attach` | Attach AGI to the mob you are looking at |
| `/simpleagi attach_type <type> [radius]` | Attach AGI to all mobs of a given type |
| `/simpleagi detach` | Detach AGI from the mob you are looking at |
| `/simpleagi detach_all` | Detach all agents |
| `/simpleagi agents` | Show number of active agents |
| `/simpleagi build <template>` | Start building (shelter, small_house, farm, wall, pillar) |
| `/simpleagi build_stop` | Stop building |

### Configuration (`config/simple_agi-common.toml`):
“`toml
aiTickInterval = 5   # AI tick interval (server ticks)
maxAgents = 150    # Maximum active AGI mobs (1–1000)
“`

—

## Technical Details

### Performance & Optimization

– **LOD (Level of Detail):**
  – `0–32 blocks` → full AI
  – `32–64 blocks` → half rate (skip 1/2)
  – `>64 blocks` → quarter rate (skip 3/4)
– **Staggering:** Each mob has a unique `phase = gameTime + mob.getId()`, spreading operations across time.
– **Chunk boundary guard:** Skips mobs in unloaded chunks.
– **ConcurrentHashMap:** All static maps use `ConcurrentHashMap` for thread safety.

### Cognitive Tiers

| Tier | lvl | maxPhon | lexCap | shareWds | memCap | wmRes | canTrade |
|——|—–|———|——–|———-|——–|——-|———-|
| PRIMITIVE   | 1 | 0 |  0 |  0 |  20 | 32 blocks | false |
| SIMPLE      | 2 | 1 | 12 |  0 |  40 | 16 blocks | false |
| SOCIAL      | 3 | 2 | 24 |  4 |  60 | 8 blocks  | true  |
| INTELLIGENT | 4 | 3 | 48 |  8 |  80 | 6 blocks  | true  |
| SAPIENT     | 5 | 3 | 96 | 16 | 200 | 4 blocks  | true  |

### Time Characteristics

| Operation | Interval | Frequency |
|———–|———-|———–|
| Body tick | every AI tick | ~4/sec |
| Threat scan | every AI tick | ~4/sec |
| WorldModel.observe | every AI tick | ~4/sec |
| Social exchange | 40 game-ticks | ~0.5/sec |
| Food item scan | 25 game-ticks | ~0.8/sec |
| GroupCapabilityModel | 30 game-ticks | ~0.67/sec |
| WorldModel tick (decay) | 20 game-ticks | ~1/sec |
| DANGER memory log | 20 game-ticks | ~1/sec |
| Memory auto-flush (DANGER) | 200 mem-ticks | ~1 per 10 sec |
| Memory auto-flush (DEATH) | immediate | — |

—

## Requirements

– **Minecraft:** 1.20.1
– **Forge:** e.g., 47.x
– **Java:** 17+
– **Gradle:** 8.8+

## Installation

1. Clone the repository.
2. Open in your IDE (IntelliJ IDEA / Eclipse / VS Code).
3. Run `./gradlew build` (or `gradlew.bat build` on Windows).
4. Find the `.jar` in `build/libs/simple_agi-<version>.jar`.
5. Place the JAR in your Minecraft profile’s `mods/` folder.
6. Launch the game with Forge.

## Quick Start

1. Create a world.
2. Enable global cognition: `/gamerule globalCognition true` (or manually attach AGI: look at a mob and run `/simpleagi attach`).
3. All mobs now have their own brains, emotions, memories, and even language!
4. Use `/simpleagi agents` to track the number of active agents.
5. To build: `/simpleagi build shelter`.

—

## License

All rights reserved, author: bruhasub

—

> **Note:** For full architectural documentation, see [ARCHITECTURE.md](ARCHITECTURE.md) (includes ASCII diagrams, impact matrices, detailed component interaction schematics, and a complete description of every cognitive layer).

UA: