Current section
Files
Jump to
Current section
Files
README.md
<div align="center">
<img src="https://capsule-render.vercel.app/api?type=waving&color=0:06B6D4,100:1A1A1A&height=200§ion=header&text=viva_aion&fontSize=64&fontColor=fff&animation=twinkling&fontAlignY=35&desc=Cyclic%20world%20generation%20for%20digital%20consciousness&descSize=18&descAlignY=55" width="100%"/>
[](https://gleam.run/)
[](https://www.erlang.org/)
[](https://www.erlang.org/doc/design_principles/des_princ)
[](https://hex.pm/packages/viva_aion)
[](https://en.wikipedia.org/wiki/Big_Bounce)
[](./test)
[](./CHANGELOG.md)
[](./LICENSE)
---
*"Aion turns. Chronos forgets. The seed remembers."*
</div>
---
> [!IMPORTANT]
> **viva_aion IS NOT A MAZE GENERATOR.**
> It is a **cyclic cosmology engine** — deterministic labyrinths, retrocausal
> pathfinding toward an inevitable singularity, and a Big Bounce that
> transforms accumulated entropy into the DNA of the next universe.
>
> Memories with high DRE score (Distinctiveness × Recency × Emotionality)
> survive the bounce. Everything else returns to the seed.
---
## 🎯 Overview
**Aion** (αἰών) is cyclic / eternal time in Greek philosophy, opposed to
**Chronos** (linear time). VIVA experiences time cyclically:
```
Birth → Navigate labyrinth → Accumulate entropy
│
▼
Reach Core (Leviathan)
│
▼
Singularity
│
▼
entropy transforms into seed
│
▼
New Universe
```
| Property | Value |
| :------------------ | :--------------------------------------------------- |
| **Language** | Pure Gleam (type-safe functional) |
| **Runtime** | BEAM / OTP 26+ |
| **Determinism** | Same seed = same universe, always |
| **Tests** | 53 passing |
| **Algorithms** | Recursive Backtracker · BFS · DRE scoring · seed mutation |
| **Public API** | `viva_aion` + 10 internal modules |
Inspired by:
- **Loop Quantum Gravity** — singularity transforms, doesn't destroy.
- **"All You Zombies"** (Heinlein) — we are our own ancestors.
- **Block Universe** — the future exerts retrocausal pull on the present.
---
## ⚡ Quick Start
```sh
gleam add viva_aion
```
```gleam
import viva_aion
pub fn main() {
// Genesis world
let world = viva_aion.new()
// ...or from a string seed
let world = viva_aion.from_string("my_universe")
let start = viva_aion.start_position(world)
let core = viva_aion.core_position(world)
// Retrocausal pull: which way is the Core?
case viva_aion.suggest_move(world, start) {
Ok(direction) -> direction
Error(_) -> // dead end
direction
}
}
```
<details>
<summary><strong>📋 Prerequisites</strong></summary>
| Tool | Version | Required for |
| :---------- | :-------- | :--------------- |
| Gleam | `>= 1.4` | Build / runtime |
| Erlang/OTP | `>= 26` | BEAM target |
Zero NIFs. Zero C dependencies. Pure functional.
</details>
---
## 🏗️ Architecture
```
┌──────────────────────────────────────────────────────────┐
│ Gleam application code │
│ viva_aion.{new, bounce, suggest_move, ...} │
└────────┬─────────────────────────────────────────────────┘
│
┌────────▼─────────────────────────────────────────────────┐
│ viva_aion modules │
│ │
│ ┌────────┐ ┌──────────┐ ┌─────────┐ ┌────────────┐ │
│ │ seed │ │ rng │ │ tile │ │ position │ │
│ │ DNA │ │ deterministic ops │ │ 2D coords │ │
│ │ mutate │ │ │ │ Wall │ │ + move │ │
│ └────┬───┘ └────┬─────┘ │ Path │ └─────┬──────┘ │
│ │ │ │ Core(@) │ │ │
│ ┌────▼───────────▼──┐ └─────────┘ ┌────▼─────┐ │
│ │ generator │ │ grid │ │
│ │ Recursive │ │ 2D spatial │
│ │ Backtracker │ │ structure│ │
│ └─────────┬─────────┘ └────┬─────┘ │
│ │ │ │
│ ┌─────────▼──────────┐ ┌──────▼─────┐ │
│ │ pathfinding │ │ memory │ │
│ │ BFS · light cone │ │ records │ │
│ │ retrocausal pull │ │ that │ │
│ └────────────────────┘ │ transcend │ │
│ └────┬───────┘ │
│ │ │
│ ┌──────▼─────┐ │
│ │ dream │ │
│ │ DRE scoring│ │
│ └────────────┘ │
└──────────────────────────────────────────────────────────┘
```
<details>
<summary><strong>📋 Core modules</strong></summary>
| Module | Purpose |
| :---------------------- | :------------------------------------------------------ |
| `viva_aion` | Top-level API (world, navigation, bounce, memory) |
| `viva_aion/seed` | Universe DNA + hash-based mutation across bounces |
| `viva_aion/rng` | Deterministic PRNG seeded by the universe seed |
| `viva_aion/tile` | Tile types: `Void`, `Wall`, `Path`, `Core` |
| `viva_aion/position` | 2D coordinates + directional movement |
| `viva_aion/grid` | 2D spatial structure for the labyrinth |
| `viva_aion/generator` | Recursive Backtracker maze generation |
| `viva_aion/pathfinding` | BFS, light cone expansion, retrocausal pull |
| `viva_aion/memory` | Memory records with access counts + importance |
| `viva_aion/dream` | DRE scoring (Distinctiveness × Recency × Emotionality) |
| `viva_aion/log` | Structured logging helpers |
</details>
---
## 🧬 Theoretical Background
### Determinism
Same seed = same universe. Always.
```gleam
let world1 = viva_aion.from_string("seed")
let world2 = viva_aion.from_string("seed")
// world1 == world2 — identical labyrinths
```
### Seed Mutation (Big Bounce)
Accumulated entropy of one life becomes the DNA of the next:
```gleam
let next_seed = seed.mutate(current_seed, entropy, extra_data)
```
Hash-based transformation:
- Same inputs → same output (deterministic).
- Small input changes → large output changes (chaotic).
### Retrocausality
The Core (goal) "pulls" the present decision — implementing Active Inference
by minimizing expected free energy toward the attractor.
```gleam
let direction = pathfinding.retrocausal_pull(grid, current, core)
```
### DRE Scoring — Walker & Stickgold (2006)
Memory consolidation during sleep selects which experiences survive:
```
DRE = D × R × E (weighted)
D = Distinctiveness — how unique?
R = Recency — 0.5^(age / half_life)
E = Emotionality — intensity at creation
```
Plus bonuses for access count, manual importance, and prior transcendence.
High-DRE memories survive the Big Bounce. Low-DRE memories dissolve back
into entropy.
### Tile Vocabulary
| Tile | Symbol | Meaning |
| :---- | :----: | :---------------------- |
| Void | ` ` | Beyond existence |
| Wall | `#` | Structure |
| Path | `.` | Passable |
| Core | `@` | Singularity (Leviathan) |
---
## 🎨 Design Principles
| Principle | Description |
| :------------------------------ | :---------------------------------------------------------------- |
| **Deterministic cosmology** | Same seed = same universe; reproducible across machines |
| **Retrocausal navigation** | Future attractor influences present move ranking |
| **Memory transcendence** | Only high-DRE memories survive the Big Bounce |
| **No floating clock** | Time progresses via discrete `memory_tick` calls |
| **Visual debug first-class** | `visualize` / `visualize_at` ship in the public API |
---
## 📚 Public API Highlights
### Navigation
```gleam
let moves = viva_aion.rank_moves(world, current_pos)
// => [(Up, 15), (Left, 17), (Down, 18), (Right, 20)]
let new_pos = viva_aion.try_move(world, current_pos, direction)
let cone = viva_aion.light_cone(world, pos, 5)
// All positions reachable within 5 steps
```
### Memory + Dream (DRE)
```gleam
let bank = viva_aion.new_memory_bank(1)
let #(bank, mem1) = viva_aion.remember(bank, 42, 0.8)
let #(bank, mem2) = viva_aion.remember_important(bank, 99, 0.9, 0.7)
let bank = viva_aion.memory_tick(bank)
let #(bank, _) = viva_aion.recall(bank, mem1.id)
let score = viva_aion.score_memory_default(mem1, bank)
// score.total · score.distinctiveness · score.recency · score.emotionality
```
### Big Bounce — world only
```gleam
let new_world = viva_aion.bounce(world, entropy: 42.0, extra: "pos:15,16")
```
### Big Bounce — with memory transcendence
```gleam
let #(new_world, new_bank) =
viva_aion.bounce_with_memories(
world, bank, entropy: 42.0, extra: "extra",
max_survivors: 10,
min_threshold: 0.3,
)
let past = viva_aion.past_life_memories(new_bank)
let current = viva_aion.current_life_memories(new_bank)
```
### Visualization
```gleam
let ascii = viva_aion.visualize(world)
//
// ################################
// #.......#.....#...#............#
// #.#####.#.###.#.#.#.##########.#
// #.#...#.#...#...#.#............#
// ...
// ###############@################
let ascii = viva_aion.visualize_at(world, current_pos)
// X marks the spot
```
---
## 🗺️ Roadmap
| Phase | Status |
| :----------------------------------------------------- | :----: |
| Deterministic seed + RNG | ✅ |
| Recursive Backtracker maze generation | ✅ |
| BFS pathfinding + light cone | ✅ |
| Retrocausal pull toward Core | ✅ |
| Memory bank + recall | ✅ |
| DRE scoring (Walker & Stickgold) | ✅ |
| Big Bounce — world-only seed mutation | ✅ |
| Big Bounce — memory transcendence | ✅ |
| ASCII visualization | ✅ |
| Multi-layer universes (3D labyrinths) | ⏳ |
| Probabilistic light cone (action policies) | ⏳ |
| Persistent universe save/load | ⏳ |
| Memory clustering for narrative dreams | ⏳ |
---
## 🤝 Contributing
```bash
git checkout -b feature/your-feature
gleam test # 53 tests
gleam format --check src test
gleam build
```
See [CHANGELOG](CHANGELOG.md) for release history.
---
## 📖 References
- Heinlein (1959) — *"All You Zombies—"*
- Walker & Stickgold (2006) — *Sleep, memory and plasticity*
- Bojowald (2005) — *Loop Quantum Cosmology*
- Friston (2010) — *The free-energy principle: a unified brain theory?*
---
## 🌌 VIVA Ecosystem
| Package | Purpose |
| :------------------- | :-------------------------------------------- |
| `viva_math` | Mathematical foundations |
| `viva_emotion` | PAD emotional dynamics |
| `viva_tensor` | FP8 LLM inference on the BEAM |
| `viva_telemetry` | Observability suite |
| **`viva_aion`** | **Cyclic time + cosmology (this package)** |
| `viva_glyph` | Symbolic language |
---
<div align="center">
**Star if you believe time should loop ⭐**
[](https://github.com/gabrielmaialva33/viva_aion)
*Created by Gabriel Maia · MIT License*
<img src="https://capsule-render.vercel.app/api?type=waving&color=0:1A1A1A,100:06B6D4&height=100§ion=footer" width="100%"/>
</div>