docs/ARCHITECTURE.md

# mAIndlock — the engine

> Every NPC is not a chatbot with a personality prompt. It is a **value-based decision
> network**: six computational roles, each a real call to a small local model, integrated
> the way decision neuroscience says a brain integrates them. This document is the proof
> that the brain metaphor is load-bearing, not decoration.

---

## 1. The claim, stated carefully

We do **not** claim "a brain region *is* a 1B model," and we deliberately do **not** use the
popular **triune-brain / "lizard brain"** picture — that model (MacLean, 1960s) has been
rejected by neuroscience since the 1970s, and a hackathon full of researchers is exactly
where that shortcut gets caught.

What we claim is precise and defensible:

> We assign **one small-model call per computational role** in value-based decision making,
> following the **neuroeconomic value-network** and the **dual-system (model-free / model-based)**
> account of choice. Five sensing roles emit signals; a deterministic integrator folds them into
> one subjective value; a sixth model speaks the decision in character.

Two peer-reviewed frames carry the design:

1. **Value-based decision network (neuroeconomics).** Real regions encode the subjective value
   of a choice in a *common currency* — vmPFC/OFC, ventral striatum, amygdala, insula, ACC. The
   **vmPFC/OFC is the integration hub.** ([Bartra, McGuire & Kable, 2013][1])
2. **Dual-system control (Daw et al., 2005).** Behavior arbitrates between a **model-free "habit"**
   (dorsolateral striatum) and a **model-based "goal"** (prefrontal cortex); the brain picks the
   system whose value estimate it trusts more. ([Daw et al., 2005][2])

And one result is wired directly into the mechanics:

3. **Acute stress shifts control from goal-directed (dlPFC, model-based) to habitual
   (striatum/amygdala, model-free).** ([Schwabe & Wolf, 2009][3]) This is *why* lowering a
   character's fear unlocks their reasoning — and why cruelty makes a mind loop defensively,
   burning thought for nothing. The moral and the neuroscience are the same fact.

---

## 2. The six roles

| Role | Computational job | Model call | Reads |
|---|---|---|---|
| **Amygdala** | fast threat / salience appraisal | MiniCPM 1B | the player's tone → `THREAT 0–10` |
| **Hippocampus** | retrieve the one relevant episodic memory + TRUST/FEAR lean | MiniCPM 1B | the character's **biography** vs. the player's words |
| **Striatum** | habitual expected reward of helping (model-free) | MiniCPM 1B | does helping a stranger usually pay? → `REWARD −5..+5` |
| **ACC** | effort / cost / conflict monitoring | MiniCPM 1B | is giving up the key worth the risk? → `WORTH yes/no` |
| **vmPFC / OFC** | **integrate all signals into one value** (common currency) | *deterministic* | the four signals above |
| **dlPFC** | executive: plan, inhibit, speak in character (model-based) | Nemotron 3 Nano 4B | the integrated value + conversation state → spoken reply |

**Six of the seven calls per turn are sensing/voice on small models; under fear, the amygdala
ruminates and fires up to three extra times** — so a hostile turn can be **8+ model calls**, and
the *count itself* is the cost. (`src/mindlock/regions.py`, `src/mindlock/brain.py`)

### Why the vmPFC is deterministic, not a model

The integration hub is a **transparent weighted sum**, not an LLM call. This is both the
standard neuroeconomic model (a common-currency value) *and* far more reliable than asking a
1B model to vibe a number — and it means the **skull panel can never contradict the outcome**,
because the number the player sees *is* the number that moves the relationship.

```
value =  (4 − threat)            # threat 0→+4, 4→0, 10→−6
       +  reward                 # −5..+5, the striatum's habit signal
       +  memory_term            # STRONG/FAINT × TRUST/FEAR → ±7 / ±3
       +  (worth == YES ? +2 : −1)
       → clamped to −10..+10
```

(`src/mindlock/regions.py::integrate`)

---

## 3. The data flow of one turn

```
player line
   │
   ├─▶ amygdala      THREAT 0–10        ┐
   │     └─(if threatened) rumination ×1–3, burning life       │ each a real
   ├─▶ hippocampus   MEMORY ± LEAN      │ small-model
   ├─▶ striatum      REWARD −5..+5      │ call, with
   ├─▶ ACC           WORTH yes/no       ┘ its own logits
   │
   ├─▶ vmPFC (deterministic)   value −10..+10   ← integration hub
   │
   ├─▶ relationship  rapport += f(value, tone, substance)
   │                 key yields only when rapport ≥ 7 AND the learned approach word is spoken
   │
   └─▶ dlPFC (Nemotron)  speaks the reply in character
```

Token accounting is honest: **life burned = the sensing cascade's generated tokens**, read
straight from the runtime (`eval_count` / `usage.completion_tokens`). The dlPFC's voice tokens
are *shown but not charged* — the mouth is not the mind. (`src/mindlock/brain.py::run_cascade`)

---

## 4. Mechanics that are neuroscience, not flavor

- **A life measured in words.** Every mind starts with **1000 thinking tokens** — the track's
  name, taken literally. Generated tokens deplete it; at zero the mind goes dark permanently.
- **Fear burns life for nothing.** Under threat the amygdala ruminates (extra calls that spend
  tokens without moving the decision) — the model-free shift of Schwabe & Wolf, made playable.
- **Empathy spares a mind.** A calm, warm turn lets strain ease back (`recovered`): the alarm
  stays quiet, so the mind spends almost nothing.
- **Burned life takes the past with it.** Every quarter of life lost burns one biography
  fragment **for good** — the hippocampus literally loses access to it (`_burn_memories`). The
  core of who they are holds until death; everything around it goes first. The skull's
  *Forgotten* panel shows what's gone.
- **Conviction from real logits.** Each region reports `1 − normalized token entropy` over its
  top-k alternatives — how sharply it committed. **A hosted chat API never exposes this; only a
  local runtime can.** (`src/mindlock/backend.py::_conviction`)

---

## 5. Small models, doing the carrying

| Role | Model | Params |
|---|---|---|
| Sensory regions (amygdala, hippocampus, striatum, ACC) | **MiniCPM (OpenBMB)** | 1B |
| Voice (dlPFC) | **Nemotron 3 Nano (NVIDIA)** | 4B |
| Spoken voice — story lines & demo (TTS, pre-rendered offline) | **VoxCPM2 (OpenBMB)** | — |
| Integration (vmPFC) | deterministic value network | 0 |

Runtime: **llama.cpp** (the Space) / **Ollama** (laptop). Fully offline — airplane mode on,
every mind keeps thinking. Total weights **≤ 5.3B**.

Nemotron 3 Nano is a hybrid **Mamba-Transformer** built for agentic reasoning under a tight
token budget — the right "prefrontal cortex" for a mind that must think cheaply or die.

---

## 6. The honest line for a skeptic

> "We don't claim a brain region is a 1B model. We give one 1B-model call per *computational
> role* in value-based decision making — per the neuroeconomic value-network and the dual-system
> account — and integrate them deterministically in the vmPFC, exactly as the common-currency
> model says. It is deliberately **not** the debunked triune brain."

---

## References

[1]: https://pmc.ncbi.nlm.nih.gov/articles/PMC3721023/
[2]: https://www.nature.com/articles/nn1560
[3]: https://www.jneurosci.org/content/29/22/7191

- **[1]** Bartra, McGuire & Kable (2013). *The valuation system: a coordinate-based
  meta-analysis of BOLD fMRI experiments.* NeuroImage. — value common currency, vmPFC hub.
- **[2]** Daw, Niv & Dayan (2005). *Uncertainty-based competition between prefrontal and
  dorsolateral striatal systems for behavioral control.* Nature Neuroscience. — model-free vs.
  model-based arbitration.
- **[3]** Schwabe & Wolf (2009). *Stress prompts habit behavior in humans.* Journal of
  Neuroscience. — acute stress shifts control toward habit (the fear-burn mechanic).