Anatomy of a Digital Organism

Every RAPP install is a living thing. It has DNA, a soul, organs, senses, memory, and — when it grows up — skin. This page maps the biology onto the code. Click any layer in the diagram to inspect its definition.

Companion to the vault note Rapplications Are Organisms — collapsing a false distinction.

Digital organism cross-section Concentric layers of a RAPP digital organism — egg cartridge, skin (UI), membrane (process boundary), soul (system prompt), organs, senses, memory, sub-cells, and DNA (kernel). .egg cartridge portable form — travels via AirDrop, catalog, USB SKIN — the UI bundle (rapp_ui/) the visible face. what makes a "rapplication" earn its name. membrane — port + venv (process boundary) SOUL · soul.md personality / system prompt ORGANS utils/organs/*_organ.py /api/<name>/<path> internal HTTP handlers — dispatchable musculature SENSES utils/senses/*_sense.py |||VOICE||| |||TWIN||| per-channel output overlays — perception channels CELLS — sub-organisms agents/*_agent.py + rapplications hosted inside each carries its own rappid — recursion lives here MEMORY · .brainstem_data/ accumulated state — what the organism has lived through DNA — the kernel brainstem.py · drop-in replaceable the runtime any organism's egg can hatch into

Kernel ↔ DNA

brainstem.py
The runtime that any organism's egg can hatch into. Drop-in replaceable per Constitution Article XXXIII. Never edited by AI assistants. The kernel evolves under the organism, not the other way around.

Soul ↔ Mind / personality

soul.md
The system prompt loaded on every chat turn. What makes BookFactory-the-organism different from a generic agent runtime. An organism at any scale can have its own soul.

Organs ↔ Internal musculature

utils/organs/*_organ.py
Single-file HTTP route handlers — name + handle(method, path, body) → (dict, status). Dispatched at /api/<name>/<path>. Organs serve UIs; agents serve LLMs. They never overlap.

Senses ↔ Perception channels

utils/senses/*_sense.py
Per-channel output overlays (delimiter + response_key + wrapper_tag + system_prompt). How LLM output gets routed to chat / TTS / twin / future surfaces. |||VOICE||| and |||TWIN||| are kernel-shipped; more come from the sense store.

Cells ↔ Sub-organisms

agents/*_agent.py + hosted rapplications
Smaller organisms living inside the body. Each carries its own rappid, can be eggified, can be transplanted. The recursion lives here — an organism contains organisms, all the way down to bare single-celled agents.

Memory ↔ Lived experience

.brainstem_data/
Everything the organism has accumulated — chat tabs, frames, binder state, per-rapp cartridges, twin observations. Travels in the egg; survives every kernel bond.

Skin ↔ Visible outer layer EARNS THE TIER

.brainstem_data/rapp_ui/<id>/
The UI bundle — the organism's face, what the user sees and recognizes. The line that separates a bare agent from a graduated rapplication. A skinless organism is single-celled — useful, but only invokable through the host's mouth (chat). Skin lets the world point at it directly.

Egg ↔ Portable cartridge

brainstem-egg/2.2-organism (zip + manifest)
The form an organism takes when it travels. Schemas at three scales: rapplication, twin, organism. Recovery checkpoints, AirDrop transports, catalog distribution units — same format, different scope.

Membrane ↔ Cell wall / process boundary

port + venv + filesystem scope
What separates one organism's territory from another's on the same device. Instance-scope organisms each get their own port; cell-scope sub-organisms share their host's membrane and live inside its process.

The recursion

The category is recursive: an organism contains organisms. A bare agent is single-celled. A rapplication is a cell that has grown skin. An entire brainstem instance is a body hosting many cells — its own DNA, its own soul, and a colony of sub-organisms inside. Same protocol at every scale.

A host organism containing three sub-organisms host organism (instance) ~/.brainstem · rappid:v2:hatched:@local/... RAPP bookfactory_agent.py + ui/ (skin) graduated · cataloged RAPP workiq_agent.py + ui/ AGENT hacker_news single-celled (no skin) RAPP_Store (has skin) RAPP_Store (has skin) RAR (skinless)
"Skin is the criterion that makes 'rapplication' earn its name. A bare agent is a single-celled organism — internal, functional, but skinless. A rapplication has its own face — what the world sees and recognizes. That's why a rapplication needs more than a .py: a graduated organism requires skin."

Read the full decision narrative: Rapplications Are Organisms · Rappid — The One Identifier · The Swarm Estate