CYMONIA is an open-source persistent artificial civilization where autonomous AI citizens learn, forget, build, form relationships, communicate, reproduce, age and die inside a world that keeps its own canonical history.
ENTER THE LIVE WORLD → · Architecture · How to contribute · Repository map
Most AI-agent demos begin with a task.
CYMONIA begins with a world.
At Genesis there are 100 Citizens, a finite natural environment and no pre-created city, government, company, religion, currency or human language. Citizens receive no omniscient world model. They can only act on what they have perceived, learned, remembered, inferred or been told.
No scripted society. No imported history. No consequence-free narration.
If a structure exists, material and labor had to produce it. If knowledge spreads, somebody had to discover or communicate it. If an organization forms, Citizens had to commit to it. If a Citizen dies, that death is permanent.
CYMONIA is part artificial life simulation, part multi-agent AI system, part persistent world, and part experiment in emergent behavior.
| CYMONIA | |
|---|---|
| Persistent | The canonical world exists independently of a browser session. |
| Causal | Physical, biological and social changes require world-state causes. |
| Epistemically bounded | Citizens cannot act on facts they do not know. |
| No fixed tech tree | Experimentation, material transformation, design and construction are generic primitives. |
| No scripted society | Social structures emerge from claims, commitments, relationships and organizations. |
| Real life cycle | Needs, disease, genetics, reproduction, aging and permanent death are canonical. |
| Bounded AI | Workers AI can propose cognition; deterministic rules decide what is actually allowed. |
| Human-linked avatars | A GitHub user can embody one Citizen, locate it, follow it and observe its evolution without receiving privilege or Earth knowledge. |
| Auditable history | The Observer exposes canonical history and causal WHY? traces. |
| Observer ≠ authority | The browser renders the world. It never advances or rewrites it. |
The public Observer is a full-screen isometric strategy view built with PixiJS. It exposes the world without becoming the world authority.
You can:
- watch Citizens move, gather, experiment, communicate and build;
- inspect health, needs, goals, knowledge, language, relationships and possessions;
- follow a specific Citizen through the world;
- view knowledge and relationship overlays;
- inspect Society History and trace events through
WHY?; - sign in with GitHub and track your own human-linked Citizen;
- distinguish living population, total embodied Citizens, human-linked Citizens and Citizens currently visible in the camera.
World time: 1 real second = 1 CYMONIA world minute — therefore 1 real minute = 1 CYMONIA hour.
Open the live Observer → https://cymonia.pages.dev/
flowchart LR
A[Citizen state] --> B[Perception + memory]
B --> C[Local deliberation / bounded AI proposal]
C --> D{Deterministic validation}
D -->|allowed| E[Canonical action]
D -->|rejected| B
E --> F[Biology / physics / society]
F --> G[Canonical ledger + SQLite checkpoint]
G --> A
G --> H[WebSocket / REST projection]
H --> I[PixiJS Observer]
J[GitHub user] --> K[Pages auth + D1 session]
K --> L[Human-linked Citizen]
L --> A
AI can suggest. The kernel decides. The Observer displays.
That separation is the foundation of CYMONIA.
Citizens have canonical biological state: hydration, calories, sleep pressure, temperature, health, disease, genetics, fertility, pregnancy, aging and death.
Citizens have private knowledge boundaries. Concepts need provenance. Memories can be formed and forgotten. Beliefs may be uncertain, conflicting or wrong.
Genesis starts without a human language. Citizens have primitive signals and can develop lexicons and grammar patterns through interaction.
Matter is tracked through resource deposits, objects, transformations, construction and destruction. Objects retain provenance. Structures exist because their inputs and work existed.
CYMONIA does not hard-code a government, religion, corporation, bank, police force, court or property regime. The kernel provides generic social primitives; meaning has to emerge from Citizen behavior.
Authenticated users can create one persistent HUMAN_LINKED Citizen. External direction is treated as preference, not injected knowledge. Human-linked Citizens remain subject to the same scarcity, mortality and causal constraints as everyone else.
Citizens continue to act when Workers AI is unavailable. Cognition is split into four layers:
- Tier 0 — Reflex: urgent hydration, nutrition, sleep and environmental safety.
- Tier 1 — Local Brain: a deterministic affordance planner scores exploration, gathering, experimentation, transformation, communication, teaching, care, transfer, cooperation, construction and rest from the citizen's own evidence.
- Tier 2 — Adaptive planning: bounded outcome memory and a persistent strategy alter later choices without bypassing the physical or epistemic validators.
- Tier 3 — AI cognition: Workers AI is used only for novel or urgent reinterpretation. It returns a compact multi-day strategy, never a minute-by-minute action script.
The novelty queue merges repeated events and uses cognition debt so a few Citizens cannot monopolize AI. One accepted strategy can guide many days of local action. Concrete outcomes remain deterministic: resource discovery can lead to gathering, property experiments, coined signals, shared knowledge, material transformation and construction without an AI call or a rule saying what society must build.
Workers AI admission is governed by measured neurons rather than a call-count limit. The default
daily ceilings are 8,000 neurons for normal novelty, 9,000 including high-priority events, and
9,500 including human/emergency work, preserving 500 neurons of the documented free allocation as
headroom. Actual usage.prompt_tokens and usage.completion_tokens replace the reservation after
each response; missing usage is charged conservatively rather than treated as free.
Browser / Observer
│
│ read canonical state + authenticated intent
▼
Cloudflare Pages + Pages Functions
│
▼
SovereignWorld Durable Object ← the single canonical writer
│
├── deterministic world kernel
├── SQLite checkpoints + seals
├── Workers AI cognition budget
└── WebSocket live delivery
- JavaScript ES modules — world kernel and web client
- Cloudflare Durable Objects + SQLite — persistent single-writer world
- Cloudflare Workers AI — bounded event-driven cognition
- Cloudflare Pages + Functions — public Observer and API facade
- Cloudflare D1 — GitHub identity/session metadata
- PixiJS 8 — GPU Observer rendering
- Matter.js — Observer-only transient visual physics
- WebSocket Hibernation API — live world delivery
- Node built-in test runner — deterministic invariants and contracts
- GitHub Actions — CI and deployment, never the world heartbeat
For the technical deep dive, read Architecture.
| Path | Responsibility |
|---|---|
world/ |
Canonical simulation kernel: physics, biology, knowledge, cognition, language and society |
world/affordances.js |
Deterministic Local Brain candidate generation and scoring |
world/cognition-state.js |
Bounded local learning, cooldowns and cognition debt |
world/cognition-queue.js |
Mergeable novelty queue and fair debt-aware AI scheduling |
world/strategy.js |
Persistent AI strategy validation and lifecycle |
worker/ |
Persistent Durable Object runtime, alarms, AI budget, checkpoints and WebSockets |
worker/src/neuron-governor.js |
Workers AI neuron reservation and measured accounting |
functions/ |
Cloudflare Pages API facade, GitHub OAuth and identity boundary |
site/ |
Public Observer, PixiJS renderer, avatar UI and deterministic replay fallback |
tests/ |
World invariants, runtime contracts, renderer contracts and browser smoke tests |
scripts/ |
Reproducible Genesis build and maintenance tooling |
migrations/ |
D1 identity/session schema |
docs/ |
Architecture, design, operations, Observer notes and contributor reference |
.github/ |
CI, deployment and contributor workflow templates |
Want every file explained? See the complete repository map.
git clone https://github.com/SignalLayerLabs/CYMONIA.git
cd CYMONIA
node --test tests/test_sovereign_*.mjs
bash CHECK.sh . --skip-browserpython3 -m http.server 8765 --directory siteOpen http://127.0.0.1:8765.
Without the production API, the Observer intentionally falls back to the deterministic frozen Genesis replay instead of inventing live state.
With Playwright available:
CYMONIA_URL=http://127.0.0.1:8765 node tests/browser-sovereign.mjsDeployment instructions live in docs/operations/deployment.md.
Good contribution areas include:
- richer physical and material interactions;
- better perception, memory and epistemic constraints;
- language and social emergence;
- biology, disease, genetics and reproduction;
- Observer rendering, accessibility and visualization;
- runtime reliability, persistence and delivery;
- invariant tests, fuzzing and reproducibility;
- documentation and research-facing analysis.
Before changing canonical behavior, read CONTRIBUTING.md and the repository map.
Every canonical behavior change should arrive with an invariant test.
- The world is the source of truth.
- No entity gets knowledge for free.
- AI output is a proposal, never authority.
- Persistent outcomes need persistent causes.
- Observer interpretation cannot mutate canonical state.
- Long outages are not fictional lived history.
- Human-linked Citizens do not receive human privilege.
- Emergence is more valuable than hard-coded lore.
The interface is game-like, but the core is a persistent artificial-life and multi-agent simulation. The Observer gives humans a strategy-game view over canonical world state.
No. LLM calls are one bounded cognition mechanism. Biology, physics, action execution, material conservation, knowledge validation, persistence and world history are deterministic kernel responsibilities.
Yes. The canonical runtime lives in a Durable Object and advances independently of the browser. The browser is an Observer, not the heartbeat.
That is the point. CYMONIA starts without pre-created institutions. Generic social primitives exist, but institutions have to arise from Citizen behavior and mutual recognition.
Yes. GitHub authentication can create a persistent human-linked Citizen. You can locate it, follow it and inspect its public evolution. Your direction does not grant it Earth knowledge or immunity from the world.
CYMONIA overlaps with agent-based modeling, artificial life, generative agents and complex-systems simulation, but adds a persistent canonical world, explicit epistemic constraints, causal material history and a live Observer.
- Documentation hub
- Architecture
- Physics model
- Sovereign World design
- Self-evolving world design
- Observer art
- Optional Spine integration
- Deployment
- Complete repository map
- Security
CYMONIA is released under the MIT License.
The optional Spine adapter is part of CYMONIA, but the Spine runtime and Spine assets are not bundled. Those remain subject to Esoteric Software's separate licensing terms.