A deterministic, emergent human-society simulation — a small medieval settlement where every person carries a full psychological mind, biological needs, social relationships, moral values, and institutional memberships. History emerges from first principles, not scripted events. But it is far more than a "society sim": beneath the village lies a complete cognitive-science stack — embodied bodies, nervous systems, appraisal-based emotion, belief systems, and noospheric fields — built to be deepened by three architecture plans (AP1 → AP2 → AP3) into a multi-scale civilization simulation.
Most agent simulations are narrative: if stress > 0.8 then spawn_revolting(). Mindstrata simulates the causes — need pressure, emotional appraisal, trust erosion, resource scarcity — and lets outcomes emerge.
Agents are bounded: each knows only its body, needs, emotions, memories, local perception, and rumors. That bounded knowledge is what makes misinformation, gossip, panic, and institutional failure possible.
Most simulations script outcomes: if unrest > 0.8 { spawn_revolt() }. Mindstrata instead simulates the causes — need pressure, emotional appraisal, trust erosion, resource scarcity, institutional legitimacy, social influence, rumor propagation — and lets revolt (or recovery) emerge.
Agents are not omniscient. Each knows only its body, needs, emotions, memories, relationships, local perception, institutional memberships, rumors it has heard, and beliefs that may be false. That bounded knowledge is what makes misinformation, gossip, panic, prejudice, and institutional failure possible at all.
Core properties:
- Emergent history — outcomes arise from locally bounded minds and material constraints, never global variables
- Deterministic replay — byte-identical runs from
seed + scenario + input log; emergent behavior is debugger-accessible - Full cognitive pipeline per agent — needs → emotions → appraisal → decisions → social consequences, across 456 Rust source files in 13 crates
- Simulation-first, GUI-later — the TUI is a debug instrument; the simulation runs headless
The design sits between The Sims (individual psychology), Cities: Skylines (settlements/economy), and Dwarf Fortress (deep emergence) — with the differentiator that every agent has a complete cognitive pipeline.
| Dimension | Mindstrata | The Sims | Cities: Skylines | Dwarf Fortress | NetLogo-style ABM |
|---|---|---|---|---|---|
| Agent psychology | Full pipeline: needs → emotions → appraisal → decisions | Shallow moodlets | None | Needs + emotions | Usually none |
| Emergent history | ✅ outcomes from bounded local minds, never global flags | Scripted | Scripted | Legendary emergent | ✅ but abstract |
| Determinism | Byte-identical replay from seed + scenario + input log | Save-dependent | Save-dependent | Deterministic | ✅ |
| Scale | Village → small town (~10²–2.5×10² agents; measured, see ENGINE_STATUS §8) | Small | City | Fortress | Variable |
| Social structure | Trust, rumor, misinformation, institutions, legitimacy | Relationship sims | Districts | Caste + factions | Basic links |
| Openable as a lab | ✅ TUI debug instrument + headless sim | No | No | Yes | Yes |
Mindstrata is the only one where every agent reasons with a complete, inspectable cognitive pipeline — making misinformation, panic, and institutional failure emergent properties rather than scripted events.
Start here: docs/ENGINE_STATUS.md is the authoritative current-state document (architecture, behaviour, realism, measured scale). docs/ROADMAP.md is the trajectory; docs/PLAN_DC3_DEVELOPMENT.md is the live work ledger; docs/DOCUMENTATION.md maps which document owns which scope. The substrate spec is docs/architecture/AP2.md (implemented); the field-theory arc is docs/architecture/AP3-afa/ (Eras I–V complete).
cargo run --release -- --seed 42 --ticks 10000The mystery simulation runs headless. For the inspector and metrics tooling, build the CLI crate:
cargo build --release -p mindstrata-cli
cargo build --release -p mindstrata-tui| Area | What's simulated |
|---|---|
| Biology | Needs, health, hunger, fatigue, vitality, lifespan |
| Psychology | Emotions, appraisal, personality, belief (with false-belief propagation) |
| Social | Relationships, trust, gossip, rumor, reputation, prejudice |
| Economics | Scarcity, exchange, labor, property, inequality feedback |
| Institutions | Legitimacy, membership, governance, institutional failure |
| Ecology & demography | Population dynamics, resources, migration |
| Conflict & culture | Emergent factionalism, norms, cultural memory |
| Noospheric fields | Collective/intangible dynamics over the population |
The simulation is layered as ten substrates (see docs/architecture/AP2.md), each building on the one below:
- Physics / environment — the settlement's material basis
- Biology — bodies, needs, health
- Perception — bounded local awareness
- Emotion & cognition — appraisal pipeline
- Psychology & belief — personality, memory, potentially-false beliefs
- Social relationships — dyadic and group bonds
- Institutions — formal structures and their legitimacy
- Culture — shared norms and memes
- Noospheric fields — collective phenomena
- Historical/teleological layer — trajectory and meaning over time
Mindstrata is designed to be deepened, not just extended. Three architecture plans map its evolution (docs/architecture/):
The founding plan: a data-oriented, emergent social-psychological-systemic simulation where every human-scale node has psychological, behavioral, relational, and systemic substrates. TUI as debug instrument, simulation first.
The human-scale deepening plan. The target:
Each agent should become a locally bounded, embodied cognitive system whose biology, psychology, relationships, and cultural exposure interact to produce lifelike history.
An agent is no longer a bundle of traits but a multi-scale cognitive runtime:
Genome → Organs/Hormones/Body → Nervous System/Arousal/Pain/Interoception
→ Perception/Attention/Memory → Emotion/Appraisal/Motivation
→ Identity/Belief/Morality/Narrative → Decision/Action/Speech
→ Relationships/Attachment/Status/Kinship → Groups/Factions/Institutions/Culture
→ Noospheric field: rumors, memes, propaganda, collective meaning
Biology modulates psychology but never replaces it; psychology is predictive, not just reactive; relationships are first-class systems; culture is an emergent field; and cognition runs at configurable level-of-detail.
The multi-scale plan: transform a single settlement into a civilization simulation where biology, decay, environment, economy, politics, law, science, religion, military conflict, infrastructure, culture, and noospheric meaning evolve together across villages, cities, nations, planets, and eventually galactic-scale abstractions — while macro-history still emerges from locally bounded agents, never global flags.
Where the implementation actually stands: the attractor-field engine (pathology quadrants, catalyst observation, collective holons, per-polity genesis, cross-polity trade diffusion) is live through Era V, and the village→multi-settlement town path is measured (N=256 at ~170 tps, 3–4 settlements per run). City/country/planet scale is not implemented — the Ω(N²) relationship floor is structural. See docs/ENGINE_STATUS.md §8 for the envelope table and §6 for the per-dimension realism verdicts.
mindstrata/
├── crates/ # 13 crates; DAG enforced by cargo
│ ├── mindstrata-core # kernel: fixed-point math, RNG streams, ids, events
│ ├── mindstrata-person # leaf: person aggregate + biology/ + health
│ ├── mindstrata-psych # leaf: psychology/ + appraisal + memory/attention/journal
│ ├── mindstrata-institutions # leaf: institutions/legal/diplomacy/military/theology/norms/factions
│ ├── mindstrata-social # leaf: social/ culture/ noosphere/ + gossip/conflict
│ ├── mindstrata-world # leaf: world/world_gen/ecology/market/logistics/demography
│ ├── mindstrata-development # AP3 attractor-field engine, catalyst observation, canon
│ ├── mindstrata-sim # orchestration: tick pipeline, passes, systems, actions
│ ├── mindstrata-tui # TUI debug instrument
│ ├── mindstrata-cli # headless runner, agent inspector, CSV metrics
│ ├── mindstrata-render # deterministic 2D pixel rendering (PNG maps)
│ ├── mindstrata-tests # integration, golden replay, property & emergence suites
│ └── mindstrata-benches # criterion benches + the per-iteration probes
├── docs/
│ ├── ENGINE_STATUS.md # authoritative current engine truth
│ ├── ROADMAP.md # trajectory; PLAN_DC3_DEVELOPMENT.md = live ledger
│ ├── DOCUMENTATION.md # which doc owns which scope (read before trusting one)
│ └── architecture/ # AP2.md (implemented), AP3-afa/ (Eras I–V), AP4-studio/
├── specs/ # data-driven specifications (RON)
├── golden/ # deterministic replay fixtures
└── scripts/ # gate, doc index, probe/bench law
The dependency direction is cargo-enforced: core ← person ← psych ← {social, institutions, world} ← sim ← {tui, cli, render, tests, benches}, with development consumed by sim and
tests. Historical state docs (docs/MINDSTRATA_CURRENT_STATE.md,
docs/REMAINING_WORK_REPORT.md) are kept but SUPERSEDED — ENGINE_STATUS.md is the
authority.
- 1,683 automated tests (
#[test]functions across the workspace) — 397 social + 313 tests-crate (property/golden/statistical/scale/comparison/behavioral-delta/long-horizon) + 301 sim + 223 psych + 121 person + 83 development + 68 institutions + 61 tui + 60 world + 35 core + 15 render + 6 cli; deterministic replay from any seed. The pre-push gate (scripts/gate --full) runs the release suite plus the golden baselines - Tick-loop throughput regression gate enforced in CI (
crates/mindstrata-benches) unsafe_code = "forbid"workspace-wide — the simulation must be memory-safe and deterministic
cargo test --workspace
cargo bench -p mindstrata-benches --no-runEvery doc in docs/ is listed with the question it answers in docs/PAGE-INDEX.md.
MIT. See LICENSE.
If you find this project useful, consider supporting ongoing development:
Your support funds new features, releases, and infrastructure for the whole ecosystem.