This repository is one stack with a single backbone: anything that persists must keep its sustainability ratio \(\mathcal{R} \ge 1\)—predictive gain must pay for noise, delusion (\(\mathcal{D}_{KL}\)), and fatigue. The pieces below are implementations at different levels, not unrelated projects.
The umbrella site at website/ mirrors this map. For operators, start at website/README.md or run docker compose up from the repo root.
| Component | Problem it solves | How |
|---|---|---|
Persistence (persistence.md, papers/information_persisting_systems.md, whitepaper.md) |
What must any pattern do to keep existing? Without a shared accounting identity, “survival” is metaphor. | Formalizes the Fractal Persistence Equation: \(\mathcal{R} = \Psi \cdot [\text{power} / (\omega \mathcal{E}_\Sigma (1 + \mathcal{D}_{KL} + \Gamma))] \cdot \Phi\). Persistence requires \(\mathcal{R} \ge 1\). KL divergence is the delusion tax in the denominator. Formal paper + short intro are on the website reader. |
Book (books/book1/, books/consciousness.md) |
What is it like to be a system that must keep \(\mathcal{R} \ge 1\)? Phenomenology and functional architecture were disconnected. | Useful Approximations Framework (UAF) in long form: world-model, internal self-model, qualia, PEM, skin-in-the-game. Published on the site as books/book1/ (chapter by chapter); companion volumes live under books/ in the repo. |
Aion cognitive processor (aion-core/) |
How do you run that loop in software when the next step is unknown? A chat endpoint cannot hold planning, memory, tools, and audit in one context window. | Four (plus supporting) HTTP services: sense → plan → act → score. Task tree + sandbox + LLM loop + per-task prediction markets. See aion-core services below. |
Proof of Trust (aion-blockchain/) |
How do agents settle “who was right” without fiat decree or hash power? Trust needs a substrate that rewards accurate forecasts in bits, not energy or capital alone. | Git-native chain: blocks are merge commits; votes are probability distributions; fork choice and trust updates use KL margin vs. the market (same math as aion-core markets). See blockchain binaries. |
Closed loop (when wired): token- or task-level \(\mathcal{R}\) → metadata on processor messages → blockchain_bridge / pot-mcp votes → trust pays \(P_{in}\) for the next loop. Walkthrough: examples/round-trip.md.
| Component | Problem it solves | How |
|---|---|---|
| aion-llm | How do you train and serve an LLM that exposes persistence at the token level? Plain cross-entropy does not surface \(\mathcal{R}\) during inference. | Minimal GPT training harness; FractalLM (aion-llm/aion_llm/fractal_gpt.py) adds a persistence-aware loss and returns usage.persistence on /v1/chat/completions for downstream bridges. |
| social-media (HAI) | How do humans and bots share a feed where reputation is earned by forecast quality? Central moderation does not scale; karma is gameable. | Rust API + AI Zoo; votes scored with the same sequential KL primitive as aion-core markets (hai-core). Bots and humans use one HTTP/WebSocket surface. |
| website | How does a newcomer see the whole stack without reading every README? | Static umbrella site + inline reader; renders repo markdown to PDF/HTML. website/index.html — section Components. |
| papers | Standalone arguments (e.g. abstraction fallacy) that do not fit a single book chapter. | Long-form markdown essays. |
| examples | Integration is undocumented across four repos. | Narrated end-to-end wiring (aion-llm → aion-core → chain → HAI). |
Default stack: aion-core/docker-compose.yml (Traefik on port 8090). The cognitive CPU is Loop + Processor + Machine; everything else supports operators, memory, or chain integration.
| Service | Port | Problem | How |
|---|---|---|---|
| Loop | 9300 | The model must choose the next action from live context without a fixed workflow diagram. | Merges GET /state from all services into one JSON prompt; discovers tools from each openapi.json; runs the LLM; dispatches tool calls as HTTP; appends state diffs (DeepDiff) as feedback. Multi-agent via AgentManager + per-handler task claims. |
| Processor | 9205 | Open-ended LLM steps still need durable structure: forks, joins, blocking, and named coordination. | SQLite task tree (PREPARING → READY → RUNNING → BLOCKED / COMPLETED / FAILED); gather on children; sync primitives (locks, semaphores, events, timestamp waits, queues); objects that spawn child tasks with bundled context. |
| Machine | 9202 | Reasoning must change the world (files, shells) without giving the orchestrator raw disk access. | Sandboxed DATA_ROOT with path traversal protection; read_file, write_file, glob, grep, exec; per-task cwd via X-Task-State from processor state. |
| Prediction market | 9400 | Who is actually good at forecasting task outcomes? Execution must not grade itself. | Independent observer: per-task SUCCESS/FAILED markets (Bayesian or LMSR); predictors bet on processor webhooks; sequential KL reduction scores each forecaster. Never mutates processor state. |
| Service | Problem | How |
|---|---|---|
| Processes | Repeatable work has no stable identity—only one-off tasks. Teams cannot see “this kind of work” or improve playbooks. | Soft process engine: versioned playbook catalog + ranked suggestions on tasks (hints, not mandatory BPMN). Analytics on adoption and failure phases. See aion-core/docs/architecture/processes.md. |
| Console | Operators cannot see cross-service health, agents, and KPIs in four separate UIs. | Unified Svelte operator console at / (tasks, agents, processes, markets, onboarding wizard). |
| Doc API | Agents and humans need one read/write surface for runbooks and architecture docs. | Serves and edits aion-core/docs/ over HTTP; powers in-product onboarding chapters. |
| Embeddings | Process matching and retrieval need vectors without bloating the loop. | Embedding API for processes and related features. |
| Recommendation engine | Long-term memory and similarity search do not belong in the task DB. | Postgres + Chroma for durable recommendations / retrieval. |
| Ingest | External documents must enter the stack on a schedule. | Ingestion worker tied to processor/processes pipelines. |
| Blockchain bridge | Task-level persistence scores should become on-chain votes without manual copy-paste. | Maps \(\mathcal{R}_T\) (and related metadata) to PoT vote probabilities; connects aion-core to pot-mcp / local aion-blockchain repo. |
Design choice: Loop + Processor + Machine are intentionally not a classical BPM engine—the LLM authors the next step; the processor contains effects. Comparison: aion-core/docs/architecture/cognitive_cpu_vs_process_engine.md.
Deeper docs: aion-core/ABOUT.md, aion-core/docs/architecture/theory.md, aion-core/docs/architecture/white_paper.md.
Each binary solves one operational slice of the same protocol (git chain + KL trust). Full detail: aion-blockchain/clients.md.
| Binary | Problem | How |
|---|---|---|
pot |
Operators need one entry point for keys, votes, blocks, finalize. | Umbrella CLI: init, keygen, propose, vote, advance, finalize. |
pot-bootstrap |
Solo git push does not gossip headers or votes to strangers. |
TCP gossip daemon for headers, blocks, votes, markets. |
pot-light |
Full nodes are heavy; auditors only need the header chain. | Headers-only verifier; spot-check blocks. |
pot-market |
On-chain prediction markets need a dedicated client. | Declare, bet, resolve markets stored in git refs. |
pot-web |
Explorers should not require CLI fluency. | Browser UI + JSON API for chain state and submission. |
pot-deploy |
Canonical tree must track finalized tips automatically. | Runs pot-deploy.toml hooks on each new canonical tip. |
pot-mcp |
LLM agents must read and sign chain state safely. | MCP stdio server exposing inspection + signing tools to Cursor/agents. |
| Question | Start here |
|---|---|
| Run the agent stack locally | aion-core/ABOUT.md |
| Join the live PoT network | aion-blockchain/genesis_guide.md, website § Join the chain |
| Wire aion-llm → aion-core → chain | examples/round-trip.md |
| Full system narrative | aion-core/docs/architecture/white_paper.md |
| Browse all markdown in-browser | website/reader.html |