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)
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)

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) 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 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).