Architecture

Architecture

GenOS is a local-first Rust workspace surrounded by a CLI, an MCP adapter, schemas, examples, benchmarks, and a browser-based Studio. The architecture separates stable domain data from mutable execution and keeps interfaces above the runtime rather than embedding provider-specific behavior in the core.

Layered system

┌──────────────────────────────────────────────────────────────┐
│ Interfaces: CLI · MCP/JSON-RPC · HTTP/API · GenOS Studio    │
├──────────────────────────────────────────────────────────────┤
│ Orchestration: experiments · evaluation · branch evolution  │
├──────────────────────────────────────────────────────────────┤
│ Runtime: capsules · fork · run · diff · merge · replay       │
├──────────────────────────────────────────────────────────────┤
│ Domain: genomes · state · beliefs · events · lineage · goals │
├──────────────────────────────────────────────────────────────┤
│ Substrates: CAS/event stores · directory/Git worlds · models │
└──────────────────────────────────────────────────────────────┘

Crate map

Crate	Responsibility
genos-core	Canonical domain types, genomes, state, snapshots, beliefs, events, goals, lineage, and invariants
genos-store	Local snapshot, capsule, artifact, event, and content-addressable storage
genos-world	World providers, directory containment, snapshots, diffs, and Git-worktree-oriented isolation
genos-runtime	Capsule lifecycle, bounded execution, branch orchestration, checkpointing, replay, and promotion
genos-protocol	Versioned protocol envelopes, schemas, tool catalogue, MCP and JSON-RPC transport contracts
genos-model	Provider-neutral model abstraction and local/provider adapters
genos-eval	Outcomes, traits, Pareto selection, causal experiments, MCTS and evaluation primitives
genos-synaptic	Associative memory, STDP, consolidation, and experience synthesis research
genos-api	API-facing application surface
genos-cli	User-facing command hierarchy across agents, snapshots, worlds, development, experiments, and resilience

The repository also contains specialized experimental crates and engines. Their presence should not be read as a stable public API.

Data model and dependency direction

The core domain types are designed to remain independent of a particular model provider or UI:

Studio / CLI / MCP
        │
        ▼
runtime operations ────── evaluation policies
        │                         │
        └──────────┬──────────────┘
                   ▼
          canonical domain records
                   │
          ┌────────┼─────────┐
          ▼        ▼         ▼
        stores   worlds    model adapters

This makes it possible to test snapshot, fork, diff, replay, and selection mechanics without a live LLM call.

The state transition machine

The core lifecycle can be viewed as transitions between immutable snapshots and active capsules:

                    restore
snapshot Sk ─────────────────────> active capsule Ck
    ▲                                    │
    │                                    ├─ run → events + state/world change
    │                                    ├─ fork → child capsules
    │                                    ├─ mutate → child genome
    │                                    └─ checkpoint
    │                                           │
    └──────────────── snapshot / merge ─────────┘

Every operation should either preserve the old immutable record or create a new descendant. In-place history rewriting would break replay and lineage.

Storage

The local storage layer uses append-only journals and content-addressed objects for supported records and artifacts. This design provides:

• integrity digests for immutable objects;
• deduplication of identical content;
• parent links for lineage;
• replayable event sequences;
• explicit legacy/new-format compatibility where migrations exist.

The current baseline is local. Production-grade shared PostgreSQL, distributed CAS, high availability, and remote transaction coordination are roadmap concerns.

World providers

World providers abstract where branch actions occur. The important contract includes:

• a branch-specific world identity and root;
• safe resolution of relative paths;
• snapshot and restore behavior;
• world diffs;
• cleanup and lifecycle handling;
• no accidental sibling write sharing within the implemented boundary.

Directory isolation is useful for controlled local tasks. It is not equivalent to a microVM, container security profile, network namespace, or kernel-enforced sandbox.

Protocol and interface boundary

The v1alpha1 protocol normalizes operation names, inputs, structured output, failures, taint, and transport framing. The initial MCP implementation supports STDIO and stateless HTTP. Authentication and sessionful remote deployment remain missing work.

Studio architecture

GenOS Studio combines a React/TypeScript frontend with an Express/SQLite backend. It exposes agents, workspaces, experiments, lineage, evaluation, tools, telemetry, and safe-debugging evidence. The backend can use its local runtime adapter or a configured external adapter.

Source of truth

Architecture documents contain both current implementation and target design. Consult the repository's ADR implementation status and proof status before treating a diagram as an available guarantee.