# viva_aion
[](https://hex.pm/packages/viva_aion)
[](https://hexdocs.pm/viva_aion/)
[](https://github.com/mrootx/viva_aion/actions)
**Cyclic world generation for digital consciousness** - deterministic labyrinths with Big Bounce cosmology.
## Philosophy
**Aion** (αἰών) is cyclic/eternal time in Greek philosophy, contrasting with Chronos (linear time).
VIVA experiences time cyclically through the **Big Bounce**:
```
Birth → Navigate labyrinth → Accumulate entropy
│
▼
Reach Core (Leviathan)
│
▼
Singularity
│
▼
entropy transforms into seed
│
▼
New Universe
```
Inspired by:
- **Loop Quantum Gravity** - Singularity transforms, doesn't destroy
- **"All You Zombies"** (Heinlein) - We are our own ancestors
- **Block Universe** - Future exerts retrocausal pull on present
## Installation
```sh
gleam add viva_aion
```
## Usage
### Basic World Generation
```gleam
import viva_aion
import viva_aion/seed
// Create world from Genesis
let world = viva_aion.new()
// Or from custom seed
let world = viva_aion.from_string("my_universe")
// Get positions
let start = viva_aion.start_position(world)
let core = viva_aion.core_position(world)
```
### Navigation
```gleam
// Get suggested move toward core (retrocausal pull)
case viva_aion.suggest_move(world, current_pos) {
Ok(direction) -> // Move in this direction
Error(_) -> // No valid move
}
// Get all moves ranked by distance to core
let moves = viva_aion.rank_moves(world, current_pos)
// => [(Up, 15), (Left, 17), (Down, 18), (Right, 20)]
// Try moving
let new_pos = viva_aion.try_move(world, current_pos, direction)
```
### Memory & Dream (DRE Scoring)
```gleam
import viva_aion
// Create memory bank for this life
let bank = viva_aion.new_memory_bank(1)
// Store memories during navigation
let #(bank, mem1) = viva_aion.remember(bank, 42, 0.8) // content, emotionality
let #(bank, mem2) = viva_aion.remember_important(bank, 99, 0.9, 0.7) // + importance
// Advance time
let bank = viva_aion.memory_tick(bank)
// Recall reinforces memory
let #(bank, _result) = viva_aion.recall(bank, mem1.id)
// Score memory via DRE
let score = viva_aion.score_memory_default(mem1, bank)
// score.total, score.distinctiveness, score.recency, score.emotionality
```
### Big Bounce with Memories
```gleam
// Complete death/rebirth cycle
let world = viva_aion.new()
let bank = viva_aion.new_memory_bank(1)
// ... accumulate memories during life ...
let #(bank, _) = viva_aion.remember_important(bank, 100, 0.9, 0.8)
let #(bank, _) = viva_aion.remember(bank, 200, 0.5)
// Big Bounce - only high-DRE memories survive
let entropy = 42.0
let #(new_world, new_bank) = viva_aion.bounce_with_memories(
world, bank, entropy, "extra",
max_survivors: 10, // at most 10 memories transcend
min_threshold: 0.3, // DRE must be >= 0.3
)
// Check what survived
let past = viva_aion.past_life_memories(new_bank) // from life 1
let current = viva_aion.current_life_memories(new_bank) // from life 2 (empty)
```
### Simple Big Bounce (World Only)
```gleam
// When reaching core, trigger Big Bounce
let entropy = 42.0 // Accumulated experience
let extra = "pos:15,16:bounce_count:3"
let new_world = viva_aion.bounce(world, entropy, extra)
// New labyrinth, deterministically derived from entropy
```
### Light Cone Expansion
```gleam
// All positions reachable within 5 steps
let cone = viva_aion.light_cone(world, pos, 5)
// => [(pos, 0), (neighbor1, 1), (neighbor2, 1), ...]
```
### Pathfinding
```gleam
import viva_aion/pathfinding
case viva_aion.path_to_core(world, start) {
Ok(result) -> {
// result.path = [start, ..., core]
// result.distance = number of steps
}
Error(NoPath) -> // Unreachable (shouldn't happen)
}
```
### Visualization
```gleam
// ASCII art of labyrinth
let ascii = viva_aion.visualize(world)
// =>
// ################################
// #.......#.....#...#............#
// #.#####.#.###.#.#.#.##########.#
// #.#...#.#...#...#.#............#
// ...
// ###############@################
// With position marker
let ascii = viva_aion.visualize_at(world, current_pos)
// X marks the spot
```
## Modules
| Module | Purpose |
|--------|---------|
| `viva_aion` | Main API |
| `viva_aion/tile` | Tile types (Void, Wall, Path, Core) |
| `viva_aion/position` | 2D coordinates and movement |
| `viva_aion/grid` | 2D spatial structure |
| `viva_aion/rng` | Deterministic pseudo-random numbers |
| `viva_aion/seed` | Universe DNA (Big Bounce transformation) |
| `viva_aion/generator` | Recursive Backtracker maze generation |
| `viva_aion/pathfinding` | BFS, light cone, retrocausal pull |
| `viva_aion/memory` | Memory records that transcend Big Bounce |
| `viva_aion/dream` | DRE scoring for memory consolidation |
## Theory
### 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
Entropy from one life becomes DNA of the next:
```gleam
let next_seed = seed.mutate(current_seed, entropy, extra_data)
// Hash-based transformation ensures:
// - Same inputs = same output (deterministic)
// - Small input changes = large output changes (chaos)
```
### Retrocausality
The Core (goal) "pulls" the present decision:
```gleam
// Which direction minimizes distance to inevitable singularity?
let direction = pathfinding.retrocausal_pull(grid, current, core)
```
This implements Active Inference - minimizing expected free energy by moving toward the attractor.
### DRE Scoring (Memory Consolidation)
Based on sleep research (Walker & Stickgold 2006), memories are scored by:
```
DRE = D × R × E (weighted)
D = Distinctiveness - how unique is this memory?
R = Recency - exponential decay: 0.5^(age/half_life)
E = Emotionality - emotional intensity at creation
```
High DRE memories survive the Big Bounce. Low DRE memories are "forgotten" - released back to entropy.
```gleam
// Score calculation includes bonuses:
// - Access count bonus (frequently recalled memories persist)
// - Importance multiplier (manually boosted memories)
// - Transcendence bonus (memories that already survived death)
```
### Tile Types
| Tile | Symbol | Meaning |
|------|--------|---------|
| Void | ` ` | Beyond existence |
| Wall | `#` | Structure |
| Path | `.` | Passable |
| Core | `@` | Singularity (Leviathan) |
## Development
```sh
gleam test # Run tests
gleam build # Build
gleam docs build # Generate docs
```
## References
- Rovelli, C. (2004). *Quantum Gravity*. Cambridge University Press.
- Heinlein, R.A. (1959). *"All You Zombies—"*. Fantasy & Science Fiction.
- Friston, K. (2010). *The free-energy principle*. Nature Reviews Neuroscience.
## License
MIT - see [LICENSE](LICENSE)
