# Fly Mind

A local language model with a limbic system made from a real insect brain.

The **mushroom body** of the fruit fly, the brain region for learning, memory and
emotional "good/bad" tagging, is simulated from its real wiring diagram (5,191 neurons from the
MaleCNS v1.0 connectome). Its dopamine neurons produce emotions that rise quickly and fade slowly,
its Kenyon cells store memories as sparse activity patterns, and a local LLM (via
[Ollama](https://ollama.com)) acts as its language centre. It starts with no name and no
personality; the goal is emergence - whatever it becomes, it discovers through experience.

Nobody prompts the language model directly: what you type and the images you share are its
*senses*. It feels a gut reaction, its dopamine shifts, memories surface, and then it speaks, thinks
privately, or stays quiet. It forms its own memories, sleeps at night to consolidate them, and may
one day choose a name for itself.

## Download and run (Windows)

1. Install [Ollama](https://ollama.com) and pull the models:
   ```bash
   ollama pull nomic-embed-text   # the brain's "ears" (required)
   ollama pull gemma4:12b         # its voice - or gemma3:4b on smaller GPUs
   ```
2. Download `FlyMind-windows.zip` from the [latest release](../../releases/latest), unzip it
   anywhere, and run `FlyMind.exe`. No Python needed.
3. Pick the language model in the toolbar **before** the first conversation, then say hello.

Everything the companion accumulates is stored in `mind_data/` next to `FlyMind.exe`, so
copying or zipping the folder moves the companion with it. Delete `mind_data/` to start a new life.

Any Ollama chat model works; models that can see images (e.g. `gemma3`, `gemma4`) also get the
vision sense. Larger models give a much fuller voice: `gemma4:12b` runs fully on an 11 GB GPU at
the default 32k context, while `gemma3:4b` tends to answer in short fragments.

## Running from source

```bash
python -m venv .venv
.venv/Scripts/activate          # Windows;  source .venv/bin/activate  on macOS/Linux
pip install -e .
python -m fly_mind
```

Requires Python 3.11+. From source, the companion's data lives in `~/.fly_mind`
(override with the `FLY_MIND_HOME` environment variable).

### Portable build

```bash
pip install pyinstaller
python tools/build.py
```

This creates `dist/FlyMind/`, a self-contained folder (~250 MB) with `FlyMind.exe`. Rebuilding
keeps an existing `dist/FlyMind/mind_data/`. Errors in the packaged app are written to
`mind_data/crash.log`.

## How it works

```
 text / image ──► embedding ──► projection neurons ──► Kenyon cells (sparse code, ~5 %)
                                (686 real PNs)          │      ▲ APL feedback inhibition
                                                        ▼
                         dopamine neurons ──learning──► KC→MBON synapses ──► MBONs (approach / avoid)
                         PAM  = reward                                         │
                         PPL1 = punishment          ◄──── feedback ────────────┘
                         PPL2 = arousal
                               │
                               ▼
                 emotions (fast rise, slow fade) → mood (minutes)
```

* **Simulation**: a firing-rate model of every neuron, wired with real synapse counts, signed
  by neurotransmitter (`fly_mind/brain/biology.py`). One tick = 1 s of brain time (100 × 10 ms steps).
  The tick rate is adjustable in the GUI to suit your hardware.
* **Senses**: any input is embedded (`nomic-embed-text`), the "background smell" of ordinary
  sentences is subtracted, and the result drives the projection neurons. The real PN→KC wiring
  then forms a sparse code, the fly's own similarity hash (Dasgupta et al. 2017), so related
  sensations share Kenyon cells. A quick, model-free appraisal (pleasant/unpleasant,
  calm/intense) drives the reward, punishment and arousal dopamine neurons.
* **Learning**: Kenyon cell activity paired with dopamine weakens KC→MBON synapses in that
  compartment (Hige et al. 2015). Each MBON's approach/avoid role is derived from which dopamine
  cluster innervates it in the connectome (the valence-balance model, Aso et al. 2014).
  Pairing "chocolate" with reward makes "brownies" attractive too.
* **Emotions** (`fly_mind/brain/emotion.py`): phasic dopamine feeds traces that rise in ~1 s and
  fade over ~30 s; mood is a ~5 min trace of valence. Dopamine that rises in reward and
  punishment clusters together counts as salience, not valence. Feelings are read out on a
  valence × arousal circumplex; novelty of the Kenyon-cell pattern drives curiosity.
* **Memory** (`fly_mind/memory/`): significant moments become memories automatically
  (emotional salience from the brain, paced to ~7 a day), written by the language centre with a
  narrative, tags and notes, plus Emotional Resonance measured from the brain and Continuity
  Threads found by similarity. Banks follow a 7:7:7 cascade and live in different Kenyon-cell
  subtypes, as in the fly:

  | Bank | Kenyon cells | Distilled when |
  |---|---|---|
  | Short-term | γ | bedtime (10 PM default), or a nap when 7 accumulate |
  | Long-term | α′β′ | 7 accumulate (≈ weekly "Memory Day") |
  | Deep recall | αβ outer (s/m) | 7 accumulate |
  | Historical | αβ inner (c/p) | 7 accumulate (merged into one) |

  Nothing is deleted: distilled memories are archived and can still surface. Every tick, live
  Kenyon-cell activity is matched against memory codes; matches compete (strength × emotion ×
  mood) for 5 working-memory slots, and a surfaced memory is replayed into the circuit and felt again.
* **Sleep**: DPM neurons switch on and the day's memories replay in the brain view while the
  language centre distills them. A missed bedtime is caught up on the next launch.
* **Language centre** (`fly_mind/mind.py`, `fly_mind/llm/`): no persona or rules - only a short
  factual description of its own mind (`self_knowledge.md` in the data folder, editable).
  Whatever it writes is spoken; `<thought>` is private, `<remember>` keeps a memory, and
  `<name>` records a name if it ever chooses one. It hears its own speech, and thinks on its own
  during quiet periods ("Inner life").

The 7:7:7 memory cascade comes from the author's earlier, hand-run "Companion Project", here
automated and driven by the fly brain.

## Layout

```
fly_mind/
  brain/      connectome loading, biology tables, simulation, emotions, runtime (tick loop)
  memory/     SQLite store (memories, conversation log, self facts) and recall/surfacing
  llm/        Ollama client, appraisal (gut-level valence/arousal), prompts
  mind.py     coordinates senses, brain, memory, language centre and sleep
  gui/        PySide6 desktop app
data/mushroom_body.npz         extracted circuit (1.7 MB)
tools/extract_connectome.py    rebuilds it from a full neuPrint/MaleCNS export
tools/build.py                 portable build (PyInstaller)
```

The data folder holds `mind.sqlite` (memories, conversation, name/birthday), `brain_state.npz`
(learned synapses, feelings, mood), `settings.ini` and `self_knowledge.md`.

## Data credit

The connectome data is from the **FlyEM male CNS connectome (MaleCNS v1.0)**
by HHMI Janelia, the University of Cambridge, the MRC Laboratory of Molecular
Biology and Google Research, licensed under
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
Project page: https://male-cns.janelia.org. `data/mushroom_body.npz` is an extract of that
dataset (mushroom body, APL, DPM and olfactory projection neurons, with soma positions).

Key papers: Aso et al. 2014 (eLife 3:e04577, e04580); Hige et al. 2015 (Neuron 88:985);
Dasgupta, Stevens & Navlakha 2017 (Science 358:793); Li et al. 2020 (eLife 9:e62576).

## License

Code: [MIT](LICENSE). Connectome data: CC BY 4.0 (see above).