MoE-Stream augments the Stream SSM backbone with sparse Mixture-of-Experts feed-forward layers and gradient-aware expert lifecycle management. Unlike Stream's minimalist design (which has no MLP at all), MoE-Stream adds specialized capacity through expert networks while maintaining Stream's clean single-loss training and O(n) SSM recurrence.
Each block stacks an SSMBlock (identical to Stream's core recurrence) followed by a sparse MoE FFN, with layer-normalized residual connection:
The MoEFFN replaces Stream's absent MLP with a top-k sparse mixture of expert sub-networks. Each expert is a 2-layer MLP with GELU activation:
Routing is performed by a learned linear gate followed by top-2 selection with normalized weights.
| Parameter | Default | Description |
|---|---|---|
| n_experts | 8 | Number of expert sub-networks per layer |
| top_k | 2 | Number of active experts per token |
| expert_hidden_mult | 4 | Hidden dimension multiplier relative to n_embd |
| importance_momentum | 0.999 | EMA decay for frequency and impact tracking |
| replacement_threshold | 0.05 | Global floor for expert value score |
| expert_min_tokens | 5000 | Minimum tokens seen before eligibility for replacement |
| moe_balance_coeff | 0.01 | Weight for load balancing auxiliary loss |
The core innovation in MoE-Stream is the expert lifecycle system, which distinguishes rare but valuable experts from truly useless ones using gradient-based impact measurements. This section details each component.
Each expert $i$ maintains two exponential moving averages updated every forward pass:
The frequency EMA tracks how often the expert is selected. The impact EMA uses backward hooks on each expert's output layer to compute per-token loss reduction: $-(\partial \mathcal{L} / \partial y) \cdot y$, which is a first-order approximation of how much the expert's output contributes to reducing the loss. The combined value score is:
Gradient-based impact is captured via PyTorch backward hooks registered on the last Linear layer of each expert:
Recently replaced experts receive a temporary value score bonus to prevent immediate re-death before they have a chance to learn:
This provides a score boost of up to 0.35 at birth, decaying linearly to 0 once the expert has seen 2× the minimum token threshold.
The `find_dead_experts` method identifies candidates for replacement using an adaptive per-layer threshold:
Safety constraints:
expert_min_tokens total tokens (probation period)When an expert is identified for replacement, the system clones the best-performing expert's weights with small Gaussian noise rather than random initialization:
After replacement, an exploration bias is injected into the router logits to encourage the new expert to receive tokens during early training. This bias decays exponentially (factor 0.99 per training step), allowing the router to naturally integrate the new expert over time.
MoE-Stream maintains Stream's clean single-loss approach with one additional term for load balancing:
where $f_i$ is the batch-local fraction of tokens routed to expert $i$, and $P_i$ is the average router probability. The load balancing loss uses batch-local counts (not cumulative history) to ensure responsiveness to recent routing patterns.
After each backward pass, `flush_grad_impacts()` is called via a hook registered on the loss tensor, ensuring that gradient-based impact EMAs are updated immediately after gradients are computed but before the next forward pass.
| Parameter | Value | Notes |
|---|---|---|
| n_embd | 128 | Embedding dimension |
| n_layer | 4 | Number of MoE-Stream blocks |
| n_experts | 4 | Experts per layer (8 for full config) |
| top_k | 2 | Active experts per token |
| learning_rate | 6e-4 | Peak LR with cosine decay |
| max_iters | 1000 | Training iterations |
| replace_interval | 400 | Check for dead experts every 400 iters |
| block_size | 256 | Max sequence length in bytes |
The following sections document smoke tests, utilization logging, and simulation results for the MoE-Stream expert lifecycle system.
During training, expert utilization statistics are logged at evaluation intervals. The `log_expert_utilization()` method produces per-layer, per-expert reports:
The value score distribution across experts in a 4-expert, 4-layer configuration typically shows a bimodal pattern: 2-3 high-value core experts (score > 0.5) and 1-2 low-value candidates for replacement (score < threshold). The gradient-based metric naturally captures the distinction between frequency and impact.
The impact/frequency ratio is critical because it prevents high-frequency but low-impact experts from being wrongly classified as "valuable." A frequently selected expert that provides minimal loss reduction per token (e.g., outputting near-zero values) will have low value despite high frequency.
The replacement system includes multiple safeguards verified through simulation:
| Safeguard | Mechanism | Status |
|---|---|---|
| Best expert protection | Best score expert excluded from candidate list | VERIFIED |
| Replacement cap | Max floor(n_experts / 2) per check | VERIFIED |
| Probation period | min_tokens threshold before eligibility | VERIFIED |
| Adaptive threshold | max(global, max_score × 0.05) | VERIFIED |
| Birth-age boost | Score bonus decaying over token count | VERIFIED |
| Exploration bias decay | Router bias decays 0.99 per step | VERIFIED |
| Clone + noise init | Gaussian noise std=0.01 on best expert clone | VERIFIED |
| Fallback random init | Scaled init when all experts are dead | VERIFIED |
The load balancing loss uses batch-local token fractions:
This design avoids the hysteresis of cumulative count-based balancing, ensuring the router can rapidly adapt to changing expert quality after replacements. The coefficient $\alpha = 0.01$ provides gentle balancing pressure without overwhelming the prediction loss.
| Feature | Stream | VECTOR | MoE-Stream |
|---|---|---|---|
| Backbone | SSM only | SSM + Attn + MoE | SSM + MoE |
| Token-Free | YES | YES | YES |
| Position-Free | YES | YES | YES |
| Multi-Byte Head | YES | No | YES |
| Gate / Pruning | None | SaliencyGate | None |
| MoE | None | Top-2 | Top-2 |
| Expert Lifecycle | N/A | None | Gradient-Aware |
| Loss Terms | 1 (CE) | 5 (Dual) | 2 (CE + Balance) |
| Complexity | O(n) | O(n) var. | O(n) |
| Attention | None | GQA | None |
MoE-Stream is implemented as a standalone module in moe_stream.py with no dependencies on Stream's model.py or VECTOR's model_vector.py. The SSMBlock is duplicated for independence, ensuring each variant can evolve independently.
| Class | File | Lines | Purpose |
|---|---|---|---|
| SSMBlock | moe_stream.py | 53-105 | Selective SSM recurrence (Mamba-style) |
| MoEFFN | moe_stream.py | 111-389 | MoE with lifecycle tracking, hooks, replacement |
| MoEStreamBlock | moe_stream.py | 395-413 | SSM + MoE block with residual LN |
| MoEStream | moe_stream.py | 419-597 | Full model with multi-byte head |
The MoEStreamConfig dataclass provides all hyperparameters with sensible defaults (8 experts, top-2, min 5000 tokens before replacement). Training is orchestrated through train.py with model_type='moe_stream' and CLI overrides via configurator.py.