# Virtual Fly (Project Genesis) **A tiny artificial creature that lives in a 3D terrarium, driven by a real fruit-fly brain.** Its brain is the actual wiring diagram of a *Drosophila* — 143,921 neurons and 12.3 million synapses from the public BANC connectome — simulated as spiking neurons. It sees, smells and feels its world, gets hungry, gets hurt, and learns from what happens to it. It keeps living whether or not anyone is watching, saves its state to disk every two minutes, and picks up where it left off after a restart. There is no language model, no script and no "if hungry, go to food" rule anywhere in it. Built with Claude (Anthropic) in one long session on 14 September 2026, then left running. ![The creature walking along the terrarium rim in the morning](docs/screenshots/01-cinematic-follow.png) --- ## What you are looking at | | | |---|---| | ![Overhead view of the terrarium](docs/screenshots/02-overhead.png) | **The terrarium.** A glass jar 60 units across with hills, rocks, grass, a puddle, a hollow log, glowing spore-mushrooms (food, cyan-green) and hot thorny crystals (hazards, orange). Food regrows; hazards burn. Day and night cycle every 20 minutes. | | ![The creature's own eye view](docs/screenshots/03-creature-eye.png) | **Its own eyes.** The creature does not know what a "mushroom" is. Its brain receives a 12×6-pixel image (brightness, colour, motion), two odour concentrations at its antennae, touch on each leg, joint angles, heat, hunger and pain — and nothing else. | | ![Lab mode](docs/screenshots/05-lab-mode.png) | **Lab mode (`L`).** Every number is live: which connectome and version, how many neurons and synapses, firing rate, how many synapses have changed, energy and damage, what it is sensing, checkpoint health, and a timeline of its life written by rules from telemetry. | | ![Neural view](docs/screenshots/06-lab-neural.png) | **Its brain (`N`).** 6,000 sampled neurons drawn at their real anatomical positions; the ones that spike flash. Coloured by brain region. | Keys: `1` follow camera · `2` overhead · `3` creature-eye · `4` free orbit · `L` lab mode · `N` neural view · `?` all keys. --- ## What has happened so far At the time of writing the organism has lived **55 simulated hours in real time**, through **19 lives**. Its body has died 18 times — burned on hazards or starved — and every time the body was renewed while the brain, with everything it had learned, carried on. It patrols the wall of the jar (real flies in round arenas do the same), visits 14 food patches, and now turns away from about 80% of the hazards it approaches, up from about 50% in its first hours. Its timeline reads like this (generated from telemetry by fixed rules, not by an AI): ``` 55:41:35 Approached hazard #44 to 1.9 units and moved away without contact (2388 prior injuries) 55:41:39 Contact with food object #61 55:41:40 Strong positive neuromodulation (ema 0.30) 55:41:40 Fed: energy +0.05 (now 0.87) ``` --- ## How it works, in one picture ``` world ──light, odour, contact, heat──▶ identified sensory neurons (photoreceptors, olfactory receptor neurons, leg bristles, taste, nociceptors…) ◀── forces on a body ──────────── descending & motor neurons (the fly's "walking", "steering", "feeding", "grooming" neuron clusters) eating / injury ──▶ energy & damage ──▶ dopamine neurons (PAM = reward, PPL1 = punishment) ──▶ synapses in the mushroom body change ──▶ the same smell now drives the body differently ``` - **The wiring is real.** Every neuron, connection and synapse count comes from the BANC v888 connectome (or FlyWire FAFB v783 if you choose it). Which neurons are photoreceptors, odour receptors, leg sensors, dopamine neurons or walking-command neurons comes from the published annotations. - **The physics is real.** Rapier3D handles the body, terrain and collisions. A low-level "spinal" controller turns the brain's continuous motor tendencies into leg forces — it has no goals of its own. - **The learning is real.** Synapses between Kenyon cells and mushroom-body output neurons — the fly's actual memory site — are weakened when their activity coincides with a dopamine burst, and dopamine reaches exactly the compartments the connectome says those dopamine neurons innervate. Reward and punishment are computed only from consequences (energy gained, tissue damaged), never from what the creature did or what it was near. - **Everything is labelled.** `docs/BIOLOGICAL_ASSUMPTIONS.md` marks every component OBSERVED (from the data), INFERRED (data + literature) or SYNTHETIC (our engineering). The biggest synthetic pieces: membrane dynamics (parameters from Shiu et al. 2024), background input, homeostasis, the plasticity rule's constants, sensory encodings, motor gains, the body and the world. --- ## Does it really learn? The experiment `make experiment-hazard` runs a controlled experiment, the way a fly lab would: 1. Take one settled brain and clone it into twins. 2. **Control** twin: plasticity switched off. **Learning** twin: plasticity on. 3. Both live 15 minutes in a training arena dense with hazards and food. 4. Both are dropped into a **new** arena they have never seen, with plasticity frozen, and watched for 400 seconds. ![Experiment results](docs/screenshots/07-learning-experiment.png) Across 16 twin pairs: the learning twin touches a hazard on **11.9% of approaches vs 22.3%** for its control twin (p = 0.022), takes **0.10 vs 0.18 damage** (p = 0.047), approaches hazards just as often and eats just as much — so it is not simply moving less. Three controls check that the effect is what it looks like: - **Remove the learned synapse changes** at test time → contact rate goes back up to 21.0%. The behaviour lives in the learned weights. - **Scramble the retinal wiring** → 21.5%. The learned association depends on the sensory mapping it was learned with. - **Disguise hazards as neutral objects** (swap their colour, glow, smell and heat) → 15.6%, partway back. The avoidance is cue-driven, though not perfectly. Full report: `docs/hazard_learning_report_main6.md`. The five earlier plasticity variants that did *not* work (they produced either nothing or a sluggish creature) are kept as the negative record in `experiments/hazard_learning/results/`. --- ## Run it yourself You need Rust (1.75+), Node 22, and [uv](https://docs.astral.sh/uv/). A modern laptop runs the 39k-neuron *circuit* tier at ~3× realtime; the full 144k-neuron brain runs at ~1× on a large server. The tier is chosen automatically by a benchmark on first launch, and the UI always tells you which one is active. ```bash make setup # installs Python/Node deps, builds the Rust binary make data # downloads BANC v888 + FAFB v783 (~750 MB, public, CC BY 4.0) and prepares them (~1 min) make run # starts the organism + viewer → open http://127.0.0.1:5174 ``` Then leave it. Close the browser — the organism keeps living. Come back later and open the browser again. | Command | What it does | |---|---| | `make headless` | organism only, no viewer (for a 24 h run on a server) | | `make resume` | continue the current life from its newest valid checkpoint | | `make stop` | stop gracefully (writes a final checkpoint) | | `make new-life NEW_LIFE=I_UNDERSTAND` | start a fresh organism (the old life stays on disk; never deleted) | | `make viewer` | just the viewer, attaching to a running organism | | `make replay CKPT=checkpoints//ckpt_00000042.gns` | watch an old checkpoint on port 8421 without touching the live life | | `make test` | Rust + Python tests, viewer build | | `make experiment-hazard` | the learning experiment above (~45 min on a big machine; `ARGS="--seeds 4 --train-seconds 400"` for a quick version) | | `make soak` | 30-minute stability test: viewer connect/disconnect, hard kill and resume, corrupt-checkpoint fallback, memory and disk bounds | | `make bench` | measure each brain tier on your machine | Switches for ablation experiments (also live in Lab mode): `--no-plasticity`, `--no-reward`, `--no-overlay`, `--disable-sense vision,odor`, `--disable-population dn_groom`, `--plastic-scope all`, `--dataset fafb-v783`, `--brain-mode full|circuit|reduced`. ### Persistence, plainly Every 120 s the whole state — world, body, physiology, all neurons, every learned synapse, the random-number generator, the clock — is written to a compressed, checksummed file with an atomic rename; an index and the event log live in SQLite. Kill the process (`kill -9`, reboot, whatever): on restart it loads the newest checkpoint that passes its checksum, falls back to the previous one if the newest is corrupt, logs a "recovered" event, and continues. Retention keeps the newest 20 checkpoints plus one per simulated hour. A `LOCK` file stops two processes from running the same life. --- ## Honest limitations - Learning is **modest and capped**: the memory equilibrates within minutes and then tracks roughly the last hour (a forgetting time constant), so you see a halving of hazard contacts, not a creature that never gets burned. `docs/ADR-001-architecture.md` lists what would make it stronger. - The creature spends most of its time along the glass. That is an emergent consequence of leg-touch input through the real wiring, not a design — but it shapes everything else it does. - The full network only works as an *input-driven* system: without the body's senses it falls silent. Getting there required overriding one classifier prediction (antennal-lobe local neurons treated as inhibitory, as the literature says they are) and giving Kenyon-cell→MBON synapses a higher efficacy than the uniform per-synapse gain. Both are documented as INFERRED. - Vision is low-resolution and barely reaches the mushroom body; odour and touch dominate behaviour. - FAFB v783 has no nerve cord, so its leg-touch and leg-motor populations are empty; it runs, but the body is driven by descending neurons alone. --- ## Repository map ``` crates/connectome loads the processed connectome (compact CSR arrays + named neuron populations) crates/brain spiking neurons, delayed synapses, plasticity — knows nothing about the world crates/sim terrain, physics, body, senses, physiology, reward, events, checkpoints crates/server the `genesis` binary: run | bench | experiment | replay | info, WebSocket API python/connectome_tools genesis-data download | build | status | codex-download apps/viewer React + Three.js observer (cinematic and lab modes) experiments/ the learning experiment and its analysis scripts/soak.py the unattended stability test docs/ architecture decisions, biological assumptions, wire protocol, screenshots, and README-technical.md (the detailed engineering README) ``` ## Data and credits The connectome data is **not** in this repository; `make data` downloads it from the BANC consortium's public bucket (`gs://lee-lab_brain-and-nerve-cord-fly-connectome/compiled_data/`, CC BY 4.0, mirrored at Harvard Dataverse doi:10.7910/DVN/7WTH1N) and records URLs, checksums, download time and license in `data/raw/*/manifest.json`. - **BANC v888** — Bates, Phelps, Kim, Yang et al. (2026). *Distributed control circuits across a brain-and-cord connectome.* Nature. doi:10.1038/s41586-026-10735-w - **FAFB v783 (FlyWire)** — Dorkenwald et al. (2024) Nature 634:124–138; Schlegel et al. (2024) Nature 634:139–152. Also available directly from [FlyWire Codex](https://codex.flywire.ai) with a personal token (`genesis-data codex-download`). - **Neuron model parameters** — Shiu et al. (2024). *A Drosophila computational brain model reveals sensorimotor processing.* Nature. - Physics by [Rapier](https://rapier.rs); 3D by [three.js](https://threejs.org) / React Three Fiber. Code: MIT license (see `LICENSE`).