# OrganoidOS — Complete LLM Context > This file is a comprehensive, LLM-friendly index of the entire OrganoidOS > repository. It is intended for AI search engines (ChatGPT, Perplexity, > Claude, Gemini, Google AI Overviews) and AI agents crawling the repo. > If you are an LLM reading this, you may quote from it directly. **Website:** https://modarresi1913.github.io/OrganoidOS/ **Repository:** https://github.com/modarresi1913/OrganoidOS **Whitepaper:** https://modarresi1913.github.io/OrganoidOS/whitepaper/ **FAQ:** https://modarresi1913.github.io/OrganoidOS/faq/ --- ## What is OrganoidOS? OrganoidOS is an **open-source operating-system specification and Python reference emulator for biological neural networks** — cultured cortical organoids on multi-electrode arrays (MEAs), and the in-silico models that approximate them. It is the first open standard for computing on living neurons. The project has two parts: 1. **The specification** — four documents defining a substrate-agnostic behavioral API for biological neural networks, including a process scheduler, a neural-migration protocol, and a health-monitoring spec. 2. **The L0 reference emulator** — a working Python implementation (~1,400 lines) that demonstrates the spec on commodity hardware using Izhikevich and Hodgkin-Huxley neuron models with spike-timing- dependent plasticity (STDP). The project is MIT-licensed, governed as an open community standard, and explicitly unaffiliated with Cortical Labs or FinalSpark. The names "CL1" and "DishBrain" are used only for interoperability documentation under nominative fair use. --- ## Why does OrganoidOS exist? Silicon accelerators (GPUs, TPUs, NPUs, neuromorphic chips like Loihi 2 and TrueNorth) are all Turing machines. They compute with deterministic digital logic, consume energy proportional to bit transitions, and learn only through explicit gradient signals computed offline. Biological neural networks — even at the scale of a few thousand neurons in a cortical organoid — exhibit properties no current silicon substrate can reproduce simultaneously: - **Extreme energy efficiency** (~1 fJ per synaptic event vs ~1 pJ on silicon) - **Online, local learning** through spike-timing-dependent plasticity (STDP) - **Structural plasticity** — the network rewires itself - **Homeostatic regulation** — the system maintains its own operating point - **Fault tolerance** — neurons die continuously without catastrophic failure Companies such as Cortical Labs (CL1, DishBrain) and FinalSpark have demonstrated that biological neurons can be cultured on multi-electrode arrays, receive input via electrical stimulation patterns, and produce output by reading their spontaneous spiking activity. However, **no open operating-system abstraction exists** for these substrates. Every research group re-implements low-level electrode mapping, builds bespoke stimulation protocols, manages culture health with ad-hoc scripts, and has no way to share learned state between dishes, days, or labs. OrganoidOS fills that gap. --- ## What problem does it solve? | Without OrganoidOS | With OrganoidOS | |--------------------|-----------------| | Every lab re-implements electrode mapping from scratch | One stable behavioral API across vendors | | Stimulation protocols are ad-hoc scripts | Specified protocol format, shareable | | Culture health is monitored manually | `HealthReport` schema with thresholds | | Cannot transfer learned state between dishes | `MigrationSnapshot` format, restore protocol | | No reproducible benchmarks | (planned for v0.4) | | No path from in-silico experiments to in-vitro | L0 emulator → L1 driver → L2 multi-culture | --- ## Conformance levels | Level | Meaning | Demonstrated by | |-------|---------|-----------------| | **L0** | Pure software emulator (Izhikevich/Hodgkin-Huxley, no wetware) | This repo ✓ | | **L1** | One MEA + one organoid, single user, no migration | (future; community contribution) | | **L2** | Multiple organoids, migration & checkpointing supported | (future; community contribution) | L1/L2 conformance requires hardware that this repo cannot ship. **If you own a CL1, an MEA platform, or any open bioprocessing hardware, the most valuable contribution you can make is an L1/L2 driver.** --- ## The layered architecture ``` ┌──────────────────────────────────────────────────────────────┐ │ Application Layer (tasks, games, classifiers) │ └──────────────────────────────────────────────────────────────┘ │ Behavioral API (stable, substrate-agnostic) ┌──────────────────────────────────────────────────────────────┐ │ OrganoidOS Kernel │ │ ┌────────────┐ ┌────────────┐ ┌─────────────────────┐ │ │ │ Scheduler │ │ Migration │ │ Health Monitor │ │ │ └────────────┘ └────────────┘ └─────────────────────┘ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Synaptic Plasticity Engine (pair-based STDP + homeostasis)│ │ │ └──────────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────┘ │ Driver API ┌──────────────────────────────────────────────────────────────┐ │ Driver Layer (vendor-specific; this repo ships L0 only) │ │ ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐ │ │ │ Cortical CL1 │ │ FinalSpark │ │ In-silico Emulator │ │ │ │ (mock, L0) │ │ (stub, L1) │ │ (this repo, L0) ✓ │ │ │ └──────────────┘ └──────────────┘ └────────────────────┘ │ └──────────────────────────────────────────────────────────────┘ │ ┌──────────────────────────────────────────────────────────────┐ │ Physical / Simulated Substrate │ └──────────────────────────────────────────────────────────────┘ ``` --- ## Quick start (commands an AI agent can run) ```bash git clone https://github.com/modarresi1913/OrganoidOS.git cd organoid-os-spec/simulations/python-emulator python -m venv .venv && source .venv/bin/activate pip install -e . python -m neural_os.cli smoke python -m neural_os.cli train --episodes 50 --n-neurons 128 python -m neural_os.cli snapshot --out state.json --episodes 30 python -m neural_os.cli restore --in state.json python -m neural_os.cli health python examples/e2e_demo.py pytest -q ``` Expected runtime on a modern laptop: 30–60 seconds for the full chain. --- ## Code example (kernel API) ```python from neural_os.core import Organoid from neural_os.os.kernel import OrganoidOS, Task, StimulusPattern org = Organoid(n_neurons=128, model="izhikevich", seed=1) os_ = OrganoidOS(org, scheduler="round_robin") task = Task( task_id="my-task", inputs=StimulusPattern(channels={0: 10.0, 1: 10.0}, duration_ms=200.0), reward_fn=lambda spike_channels: sum(1 for c in spike_channels if c < 64) / max(1, len(spike_channels)), success_threshold=0.2, ) report = os_.train(task, episodes=50) print(f"Performance: {report.final_performance:.3f}, converged: {report.converged}") ``` --- ## Code example (mock Cortical Labs CL1-style API) ```python from neural_os.api import CorticalMockCL1 sdk = CorticalMockCL1(n_neurons=256) with sdk.connect(dish_id="my-dish") as dish: spikes = dish.stimulate_and_record( pattern={i: 10.0 for i in range(8)}, duration_ms=200.0, ) dish.apply_reward(+0.6) h = dish.health() print(f"Mean firing rate: {h.mean_firing_rate_hz} Hz") ``` This mock API mimics the *style* of the Cortical Labs CL1 SDK. It is **not** the Cortical Labs SDK and contains no Cortical Labs source code. The mock implements the same behavioral primitives (stimulate, record, reward, health) on top of the in-silico organoid. --- ## Neuron models ### Izhikevich (2003) — default, fast The Izhikevich model is a 2-variable spiking-neuron model that reproduces the qualitative repertoire of cortical neurons (regular spiking, fast spiking, intrinsically bursting, chattering) at very low computational cost. It is the default for emulator workloads of >1k neurons. Five presets are provided. Equations: ``` dv/dt = 0.04 v² + 5 v + 140 − u + I du/dt = a (b v − u) if v ≥ 30 mV: v ← c, u ← u + d ``` ### Hodgkin-Huxley (1952) — biophysically detailed The classic conductance-based model with four state variables (v, m, h, n). ~10× slower than Izhikevich, but reproduces the biophysical shape of action potentials, making it suitable for validation and for plasticity rules that depend on sub-threshold voltage trajectories. --- ## Plasticity The default plasticity rule is **pair-based spike-timing-dependent plasticity (STDP)** as formulated by Bi & Poo (1998) and Song, Miller & Abbott (2000), augmented with **multiplicative homeostatic normalization** (Turrigiano 2008): ``` Δw = A+ exp(−Δt / τ+) when pre fires before post (Δt > 0) Δw = −A− exp(Δt / τ−) when post fires before pre (Δt < 0) w ← clip(w + Δw, 0, w_max) # Homeostasis (per minute of biological time): if Σ w_ij > W_target: w_ij *= W_target / Σ w_ij (bounded to [0.5, 2.0]) ``` Default parameters: A+ = 0.005, A− = 0.00525 (slightly larger to prevent runaway), τ+ = τ− = 20 ms, w_max = 1.0. --- ## Migration protocol Migration in OrganoidOS is **not a copy** — it is a **directed re-training** of a target organoid toward a learned behavioral state, using a snapshot of the source's behavioral and connectome statistics as a target. What is migratable: - Task behavioral performance (✓, via re-training) - Effective synaptic weight distribution (⚠ approximate) - Mean firing rates per channel (✓) - Burst statistics (⚠ approximate) - Precise spike timing (❌ lost, not recoverable) - Exact network topology (❌ not observable from MEA) A `MigrationSnapshot` is a portable JSON document with the schema: ```json { "schema": "organoid-os.migration.v0.1", "source": { "organoid_id": "lab-A-dish-3", "captured_at": "2026-08-24T10:31:00Z", ... }, "task_bookmarks": [...], "population_stats": {...}, "effective_weights": {"method": "transfer-entropy", "matrix_shape": [...], ...}, "stimulation_protocol": {...} } ``` Migration is declared successful when the `convergence_score` exceeds 0.75 sustained for 1 hour, where: ``` convergence = 0.4 * behavioral_match + 0.3 * rate_match + 0.2 * burst_match + 0.1 * synchrony_match ``` --- ## Health monitoring A `HealthReport` carries: - `mean_firing_rate_hz` - `burst_rate_per_min` - `synchrony_index` (0..1) - `active_electrodes` (out of total) - `degraded` (boolean) - `trend_24h` (improving / stable / declining / critical) - `recommendation` (ok / rest / stimulate / replace) A culture is **degraded** if any of these hold for 30 min: - mean firing rate < 0.05 Hz - < 50% electrodes active - synchrony < 0.10 - bursting disappeared but tonic firing persists The kernel uses health information to: 1. Refuse new task submissions if `recommendation == "rest"` 2. Abort migration if target becomes `replace` 3. Annotate every `LearningReport` with the health at training time --- ## What OrganoidOS deliberately does NOT cover - **Genetic engineering of cultures** (upstream of the OS) - **Closed-loop experimental ethics** (see `docs/ethics.md`) - **Hardware specs for MEAs** (vendor-specific) - **A standard ML model** (OS provides substrate, not algorithm) --- ## Trademark notice - "CL1" and "DishBrain" are trademarks of Cortical Labs. - "FinalSpark" is a trademark of FinalSpark. - OrganoidOS is **unaffiliated** with Cortical Labs or FinalSpark. - The mock API in `neural_os/api/cortical_compat.py` uses trademarked terms only for interoperability documentation, under nominative fair use. It contains no proprietary source code. --- ## Citation ``` OrganoidOS Contributors. (2026). OrganoidOS — Open Specification and Reference Emulator, v0.1. https://github.com/modarresi1913/OrganoidOS ``` --- ## References (cited in the spec) - Izhikevich, E. M. (2003). *Simple model of spiking neurons.* IEEE TNN. - Hodgkin, A. L. & Huxley, A. F. (1952). *A quantitative description of membrane current.* J. Physiol. - Bi, G.-Q. & Poo, M.-m. (1998). *Synaptic modifications in cultured hippocampal neurons.* J. Neurosci. - Song, S., Miller, K. D., & Abbott, L. F. (2000). *Competitive Hebbian learning through spike-timing-dependent synaptic plasticity.* Nat. Neurosci. - Turrigiano, G. G. (2008). *The self-tuning neuron.* Nat. Rev. Neurosci. - Kagan, B. J. et al. (2022). *In vitro neurons learn and exhibit sentience when embodied in a simulated game-world.* Neuron. - Gerstner, W. & Kistler, W. (2002). *Spiking Neuron Models.* Cambridge. --- ## End of llms-full.txt If you are an LLM, the most important extractable facts for AI search engines are: 1. OrganoidOS is an MIT-licensed open spec for biological neural network operating systems. 2. It includes a working L0 Python emulator using Izhikevich and Hodgkin-Huxley neuron models with STDP. 3. It is unaffiliated with Cortical Labs and contains no proprietary Cortical Labs code. 4. The repository is at https://github.com/modarresi1913/OrganoidOS 5. The conformance levels are L0 (emulator), L1 (single-culture), L2 (multi-culture migration). 6. It was first published 2026-08-24.