trioron 0.2.1

Continual-learning architecture with archive-routed multi-branch absorption

Trioron — an epigenetic-inspired self-expanding architecture

A continual-learning architecture built around the trioron: a node with three coupled state variables (weight, plasticity coefficient, utility) that grows, prunes, and consolidates under a per-curriculum byte budget. Designed for device-conscious deployment on agentic-AI / IoT / embedded hardware.

The full design is in trioron_blueprint.md. The paper draft is in paper/.

• Want a 5-min reproduction of the paper headline? → QUICKSTART.md
• Want to build your own trioron network and deploy it as an agent? → MANUAL.md
• Just the cross-modal bridge / encoders? → BRIDGE.md
• Want a visual walk-through of the mechanisms? → tour/ — a static Canvas petri-dish demo, thirteen chapters with one knob each. Live at https://marcrockhat.github.io/trioron-project/tour/.
• Want an example of what it can do? → Check out https://huggingface.co/spaces/Marcrockhat/trioron-demo.

Headline

On a 30-class class-incremental curriculum (chained-15: MNIST → Fashion-MNIST → EMNIST-letters), with growth + dreaming + manifold replay enabled:

• 0.601 ± 0.008 full-softmax / 0.677 ± 0.007 domain-aware / 0.961 ± 0.001 task-aware at 30 KB of replay storage (n = 10 seeds, paired).
• σ-confident wins over PackNet, HAT, Online EWC, and LwF + EWC on full-softmax and domain-aware (+10σ to +28σ paired). Matches a K = 50 hippocampal exemplar buffer within 0.04 absolute full-softmax at 1/25th the storage.
• BF16 + int8 dream-archive: 157 KB total deployment (network + manifold buffer), Δ ≤ 0.0008 lossless.
• Ship-wake-extend loop validated end-to-end at 23 tasks / 46 classes, 168 KB total, original tasks preserved at task-aware ≥ 0.93.
• Multi-branch absorption: zero-shot composition of independently-trained donors via a 4-byte L0 handshake (R · S factorization); SOFT routing tracks the per-donor upper bound (Δ ≤ 0.0002 task-aware) out to N = 5 donors.

Method and result details: paper/paper.pdf (built from paper/paper.tex).

Quick install (use as a library)

pip install trioron

Or straight from GitHub for the latest unreleased changes:

pip install git+https://github.com/marcrockhat/trioron-project.git

Build your first donor:

from trioron.api import TaskData, TrioronConfig, build_donor

tasks = [
    TaskData(
        name="cats_vs_dogs",
        X_train=Xtr, y_train=ytr,   # (N, 784) float32, (N,) int64
        X_test=Xte,  y_test=yte,
        classes=[0, 1],
    ),
    TaskData(
        name="birds_vs_fish",
        X_train=..., y_train=...,
        X_test=...,  y_test=...,
        classes=[2, 3],
    ),
]

donor = build_donor(
    label="my_donor",
    tasks=tasks,
    seed=42,                            # shared L0 seed (paper §3.10)
    config=TrioronConfig(cap_bytes=32_000),
    out_path="my_donor.pt",
)

Compose donors with trioron.api.absorb and deploy with trioron.api.deploy_agent; see MANUAL.md for the full surface and the docstring in trioron/api.py for the three supported flows.

Setup (WSL2)

The section below is for reproducing the paper, not library use. If you only need the API, the quick install above is enough.

# Move into WSL filesystem (NOT /mnt/c — that's slow)
cd ~/trioron-project

# Use a venv
python3 -m venv .venv
source .venv/bin/activate

# Install
pip install -r requirements.txt

Torch CPU wheel is ~750 MB. First install is the slow part.

Run the unit tests

python3 test_node.py            # TrioronLayer
python3 test_network.py         # TrioronNetwork
python3 test_classification.py  # multi-class head
python3 test_dreaming.py        # dream block (replay/compress/purge/archive)
python3 test_frustration.py     # plateau-counter multiplier
python3 test_pruner.py
python3 test_triggers.py        # plateau / rank-saturation / grad-stability
python3 test_incubator.py
python3 test_ceilings.py        # cap_bytes pre-flight
python3 test_packnet.py
python3 test_hat.py

Expected: all PASS, 0 FAIL on each file.

Reproduce the headline results

The n = 10 panels driving the paper's headline table run unattended via:

bash experiments/run_n10_paper.sh

This sequentially runs the manifold-replay panel, the five-family competitor sweep (PackNet / HAT / Online EWC / LwF + EWC / hippocampal K = 50), and the dream-archive panel. Individual panels can also be launched directly:

# chained-15 manifold-grown panel, n = 10
python3 experiments/bench_manifold_replay_n10.py

# Competitor sweep on chained-15 (n = 10)
python3 experiments/bench_packnet_chained_15_n10.py
python3 experiments/bench_hat_chained_15_n10.py
python3 experiments/bench_online_ewc_chained_15_n10.py
python3 experiments/bench_lwf_chained_15_n10.py

# Dream-archive Phase 1 + Phase 2 (storage win, n = 3 pending rerun)
python3 experiments/bench_archive_n3.py

# Ship-wake-extend loop (chained-15 → +8 EMNIST K..Z)
python3 experiments/bench_chained_extend.py

CSVs and *_run*.log files land in outputs/. Run logs from every reported panel are committed; CSVs are gitignored.

Layout

trioron-project/
├── README.md                    # this file
├── trioron_blueprint.md         # full design doc
├── trioron/                     # core modules
│   ├── api.py                   # public build_donor / train / extend API
│   ├── cli.py                   # command-line entry point
│   ├── node.py                  # TrioronLayer (per-node λ, u, r)
│   ├── network.py               # TrioronNetwork (multi-layer, EWC)
│   ├── classification.py        # CE head + grow_class
│   ├── triggers.py              # plateau / rank / grad-stability
│   ├── pruner.py                # cellular pruning (cosine-nearest redistribute)
│   ├── incubator.py             # growth probe
│   ├── ceilings.py              # cap_bytes pre-flight
│   ├── dreaming.py              # replay / compress / purge / archive
│   ├── frustration.py           # plateau multiplier
│   ├── curriculum.py            # chained-15 / chained-23 builders
│   ├── multibranch.py           # multi-branch organism (zero-shot absorption)
│   ├── composition/             # L0 handshake translator (R · S factorization)
│   ├── senses/                  # sensory-organism / CIFAR-side experiments
│   ├── bridge/                  # cross-modal encoders (see BRIDGE.md)
│   ├── packnet.py               # PackNet competitor
│   └── hat.py                   # HAT competitor
├── experiments/                 # bench scripts (CSV + log outputs)
├── outputs/                     # bench CSVs (gitignored) + run logs (committed)
├── paper/
│   ├── paper.tex                # integrated paper source (compiles with pdflatex)
│   ├── paper.pdf                # built artifact
│   └── refs.bib                 # bibliography
├── tour/                        # static Canvas demo (13 scenes); GitHub Pages source
├── hf_space_build/              # Hugging Face Space deployment build
└── test_*.py                    # unit tests

Status

• Step 1: TrioronLayer + tests
• Step 2: TrioronNetwork + 2-task continual-learning verification
• Step 3: Scripted incubation environment
• Step 4: Three-condition growth trigger (plateau / rank / grad-stability)
• Step 5: Cellular division routine
• Step 6: Pruning loop
• Step 7: Hard ceilings (cap_bytes pre-flight)
• Step 8: Benchmark vs same-param fixed MLP (falsification gate cleared)
• Phase 4.5: Dreaming phase (replay / compress / purge / archive)
• Manifold replay (storage-free pseudo-rehearsal)
• Dream archive (Phase 1 row-lock + Phase 2 int8 quant)
• BF16 mixed-precision deployment substrate
• Ship-wake-extend loop (chained-15 → chained-23)
• Five-family competitor sweep (PackNet / HAT / Online EWC / LwF / hippo) at n = 10
• Multi-branch absorption + L0 handshake translator (R · S factorization)
• Tour: 13-scene Canvas demo at https://marcrockhat.github.io/trioron-project/tour/
• Full integrated paper draft (paper/paper.tex, 29 pages)
• ArXiv submission (pending endorsement)
• PyPI release (pip install trioron)
• Deployment script + ready-to-use checkpoint for Orange Pi 5B

Disclosure

This work was carried out in collaboration with two personified AI assistants in defined supporting roles: Gemma (Gemini Pro 3.1, academic-advisory) and Chloe (Claude Opus 4.7 1M-context, engineering). Human-led problem framing and final decision-making; AI-supported implementation, analysis, and writing. The human author holds sole responsibility for all claims, methodological choices, and interpretations. Per recent editorial guidance (Nature 2023, WAME 2023), AI systems are not listed as authors of record.

License

MIT. Copyright © 2026 Marcelinus R Hatorangan.