Neuro-Symbolic Vision + RAM Reinforcement Learning Agent
Autonomous completion of Pokémon Yellow using long-term memory (LSTM) and direct memory access.

• Project Overview
• Key Features
• Technology Stack
• Installation & Setup
• Usage
• Monitoring & Metrics
• Agent Architecture
• Project Structure
• Credits
• Disclaimer

IndigoRL is an autonomous Artificial Intelligence agent designed to complete Pokémon Yellow using Deep Reinforcement Learning.

Unlike generic agents that randomly press buttons, IndigoRL implements a Neuro-Symbolic Architecture combining:

• 🖼️ Computer Vision: CNN processing over resized game frames.
• 🧠 Symbolic State: Direct RAM memory inspection (event flags, battle state, map data).
• 🔁 Long-Term Memory: Recurrent Neural Networks (LSTM via Recurrent PPO).

This allows the agent to reason about story progression, battles, and exploration in an extremely sparse, long-horizon RPG environment.

• Uses RecurrentPPO (PPO + LSTM).
• Enables maze navigation, backtracking, and objective persistence.
• Solves the "memoryless" limitation of standard RL agents.

• Story Progress
  • Reads event flags directly from game RAM.
  • Rewards badges, key items, and narrative milestones.
• Battle Awareness
  • Reads enemy HP, player HP, and battle states.
  • Learns combat strategies instead of brute-force button mashing.
• Exploration
  • Rewards discovering new Map IDs.
  • Penalizes stagnation and looping behavior.

• State Loading
  • Skips Oak’s intro using a clean save-state.
  • ~20% reduction in compute per episode.
• Headless Training
  • SDL disabled during training for maximum FPS.
• Parallel Training
  • Supports multiple emulator instances.

• Python 3.10+ (Conda recommended)
• Pokémon Yellow ROM (.gb) — legally owned

git clone https://github.com/OutFerz/indigoRL.git
cd indigoRL
conda create -n indigoRL python=3.10
conda activate indigoRL
pip install -r requirements.txt

Place your ROM at:

roms/PokemonYellow.gb

python record_state.py

Play the intro manually and close the window once you gain control of the player.

python train_lstm.py

Models and logs are saved to:

experiments/poke_lstm_v1/

python play.py

• Real-time 60 FPS playback
• Neural network input overlay
• Live RAM debugging info

Monitor training in real time using TensorBoard:

tensorboard --logdir experiments/poke_lstm_v1/logs

Open your browser at:

http://localhost:6006

Policy: Multi-Input Recurrent Policy

• Visual Encoder (CNN)
  • Grayscale, downsampled game frames
• Symbolic Encoder (MLP)
  • RAM vector:
    • X, Y, Map ID
    • Player HP, Enemy HP
    • Party Levels
    • In-Battle Flag
• Memory Core
  • LSTM (256 units)
• Action Head
  • Discrete GameBoy button actions

indigoRL/
├── assets/                 # README images
├── experiments/            # Models and logs
├── roms/                   # Game ROMs
├── src/
│   └── environment/
│       └── pokemon_env.py  # Gym environment & RAM reader
├── states/                 # Save states
├── train_lstm.py           # Training entry point
├── play.py                 # Visualization script
├── record_state.py         # Save-state utility
└── requirements.txt

• PyBoy Emulator
• Stable-Baselines3 Contrib
• pret/pokeyellow disassembly project

This project is for research and educational purposes only.
You must legally own a physical or digital copy of Pokémon Yellow to use the ROM.
The authors do not encourage or support piracy.