Architecture Diagrams

Visual Reference for Implementation
Created: December 8, 2025

---

📐 System Architecture Overview

┌─────────────────────────────────────────────────────────────────────────┐
│                         HRM-ACTV1 Enhanced Model                        │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  Input Tokens                                                           │
│      │                                                                  │
│      ▼                                                                  │
│  ┌─────────────┐                                                       │
│  │ Embeddings  │                                                       │
│  └──────┬──────┘                                                       │
│         │                                                               │
│         ▼                                                               │
│  ┌─────────────────────────────────────────────────────────┐          │
│  │                    Layer 1                              │          │
│  │  ┌──────────────┐              ┌─────────────────┐    │          │
│  │  │   Attention  │◄─────────────┤ TraceManager    │    │          │
│  │  │   + RoPE     │  bias inject │ - Sparse Memory │    │          │
│  │  └──────┬───────┘              │ - Salience      │    │          │
│  │         │                       │ - Decay/Update  │    │          │
│  │         │                       └────────▲────────┘    │          │
│  │         │                                │             │          │
│  │         ▼                                │ capture     │          │
│  │  ┌──────────────┐                       │             │          │
│  │  │  MoE Router  │──────────────────────►│             │          │
│  │  └──────┬───────┘      log paths        │             │          │
│  │         │                                │             │          │
│  │         ▼                                │             │          │
│  │  ┌──────────────┐              ┌────────┴────────┐    │          │
│  │  │   Experts    │              │ RoutingPathTree │    │          │
│  │  │  [E1..E8]    │              │ - Suffix Tree   │    │          │
│  │  └──────┬───────┘              │ - Motif Detect  │    │          │
│  │         │                       │ - Crystallize   │    │          │
│  │         │                       └─────────────────┘    │          │
│  └─────────┼──────────────────────────────────────────────┘          │
│            │                                                           │
│           ... (Layers 2-31)                                           │
│            │                                                           │
│            ▼                                                           │
│  ┌─────────────┐                                                      │
│  │ Output Head │                                                      │
│  └─────────────┘                                                      │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

---

🔄 Data Flow: Attention Trace Lifecycle

┌─────────────────────────────────────────────────────────────────────┐
│                    Forward Pass (with tracing)                      │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │  Compute QKV    │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │ Load trace bias │◄──── M^(l,h) (sparse)
                    │ from memory     │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │  QK^T / √d_k    │
                    │  + α·M          │  ← Biased attention
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │   Softmax       │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │  Attention·V    │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │  [DETACH]       │
                    │  Store attn     │  → Temporary buffer
                    │  weights        │
                    └─────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                    Backward Pass (gradient capture)                 │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │ loss.backward() │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │  Extract ∂L/∂A  │  ← Attention gradients
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │ Compute salience│
                    │ S = A·|∂L/∂A|   │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │ Top-k selection │  ← Only high salience
                    │ (k ≈ 0.1% edges)│
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │ Update M^(l,h)  │
                    │ with EMA/decay  │
                    └─────────────────┘

---

🌳 Routing Path Tree Structure

                              Root
                               │
                ┌──────────────┼──────────────┐
                │              │              │
               E₁             E₂             E₃  ← Layer 1
          count: 523      count: 892     count: 341
         reward: 412     reward: 705    reward: 268
                │              │              │
        ┌───────┼─────┐   ┌────┼────┐    ┌───┴───┐
        │       │     │   │    │    │    │       │
       E₁      E₂    E₃  E₁   E₂   E₃   E₁      E₂  ← Layer 2
    cnt:201 cnt:198     ...
                │
            ┌───┼───┐
            │   │   │
           E₁  E₂  E₃  ← Layer 3
              ...

─────────────────────────────────────────────────────────

High-Utility Path Example:

π = [E₂ → E₁ → E₃ → E₂]
    ─────────────────────
    Frequency: 198 (> threshold)
    Utility: +0.07 (> threshold)
    Entropy: 0.8 (< threshold)
    → CRYSTALLIZE ✓

Creates new expert: E_motif42

Future routing can select E_motif42 directly,
bypassing individual expert routing.

---

💾 Memory Layout: Trace Storage

┌─────────────────────────────────────────────────────────┐
│               TraceMemory (Per Layer/Head)              │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Sparse COO Format:                                     │
│                                                         │
│  traces: List[AttentionTrace]                          │
│  ┌───────────────────────────────────────────────────┐ │
│  │ AttentionTrace #1:                                │ │
│  │   layer_id:     5    (1 byte)                     │ │
│  │   head_id:      12   (1 byte)                     │ │
│  │   query_idx:    1024 (2 bytes)                    │ │
│  │   key_idx:      512  (2 bytes)                    │ │
│  │   salience:     0.85 (4 bytes float32)            │ │
│  │   age:          3    (2 bytes)                    │ │
│  │                              Total: 12 bytes       │ │
│  ├───────────────────────────────────────────────────┤ │
│  │ AttentionTrace #2:                                │ │
│  │   ...                                             │ │
│  └───────────────────────────────────────────────────┘ │
│                                                         │
│  max_traces: 2048 per head                             │
│  Total: 2048 × 12 bytes = 24 KB per head              │
│                                                         │
│  For 32 layers × 32 heads:                             │
│  Total: 32 × 32 × 24 KB = 24.6 MB                     │
│                                                         │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│            Fast Lookup via Hash Map                     │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  trace_index: HashMap[(layer, head, i, j) → salience] │
│                                                         │
│  Example:                                               │
│  (5, 12, 1024, 512) → 0.85                             │
│  (5, 12, 2048, 256) → 0.72                             │
│  ...                                                    │
│                                                         │
│  O(1) lookup for bias injection                        │
│  O(log n) insert for updates (maintain sorted)         │
│                                                         │
└─────────────────────────────────────────────────────────┘

---

🔀 Training Loop Integration

┌───────────────────────────────────────────────────────────────┐
│                    Standard Training Loop                     │
└───────────────────────────────────────────────────────────────┘
    │
    ▼
┌───────────────────────────────────────────────────────────────┐
│  for batch in dataloader:                                     │
│      ┌─────────────────────────────────────────────┐         │
│      │  1. Forward Pass                            │         │
│      │     - Attention with trace bias             │         │
│      │     - MoE routing logged                    │         │
│      └─────────┬───────────────────────────────────┘         │
│                │                                               │
│      ┌─────────▼───────────────────────────────────┐         │
│      │  2. Compute Loss                            │         │
│      │     L_total = L_task + β₁·L_balance         │         │
│      │             + β₂·L_trace + β₃·L_crystal     │         │
│      └─────────┬───────────────────────────────────┘         │
│                │                                               │
│      ┌─────────▼───────────────────────────────────┐         │
│      │  3. Backward Pass                           │         │
│      │     - Compute gradients                     │         │
│      │     - Extract ∂L/∂A for salience            │         │
│      └─────────┬───────────────────────────────────┘         │
│                │                                               │
│      ┌─────────▼───────────────────────────────────┐         │
│      │  4. Optimizer Step                          │         │
│      │     - Update model weights                  │         │
│      └─────────┬───────────────────────────────────┘         │
│                │                                               │
│      ┌─────────▼───────────────────────────────────┐         │
│      │  5. Periodic Trace Update                   │         │
│      │     if step % UPDATE_INTERVAL == 0:         │         │
│      │       - Compute salience scores             │         │
│      │       - Update trace memory (EMA)           │         │
│      │       - Apply decay to unused traces        │         │
│      │       - Evict lowest salience if quota full │         │
│      └─────────┬───────────────────────────────────┘         │
│                │                                               │
│      ┌─────────▼───────────────────────────────────┐         │
│      │  6. Periodic Motif Update                   │         │
│      │     if step % CRYSTALLIZE_INTERVAL == 0:    │         │
│      │       - Traverse routing tree               │         │
│      │       - Compute utilities                   │         │
│      │       - Detect crystallization candidates   │         │
│      │       - Freeze high-utility motifs          │         │
│      │       - Prune low-utility motifs            │         │
│      └─────────────────────────────────────────────┘         │
└───────────────────────────────────────────────────────────────┘

---

📊 Salience Computation Pipeline

  Attention Weights (A)         Gradients (∂L/∂A)      Recurrence (p)
        │                              │                      │
        │ [B, H, T, T]                │ [B, H, T, T]        │ [T, T]
        │                              │                      │
        ▼                              ▼                      ▼
┌───────────────┐            ┌────────────────┐     ┌─────────────┐
│   A_{i,j}     │            │   |∂L/∂A|      │     │ log(1 + p)  │
└───────┬───────┘            └────────┬───────┘     └──────┬──────┘
        │                             │                     │
        └─────────────┬───────────────┘                     │
                      │                                     │
                      ▼                                     │
              ┌──────────────┐                             │
              │   A · |∂L/∂A|│                             │
              └───────┬──────┘                             │
                      │                                     │
                      └────────────┬────────────────────────┘
                                   │
                                   ▼
                          ┌─────────────────┐
                          │  Salience Score │
                          │  S = A·|∂|·log p │
                          └────────┬────────┘
                                   │
                                   ▼
                          ┌─────────────────┐
                          │  Threshold      │
                          │  S > θ?         │
                          └────────┬────────┘
                                   │
                    ┌──────────────┴──────────────┐
                    │                             │
                   YES                           NO
                    │                             │
                    ▼                             ▼
          ┌──────────────────┐         ┌──────────────────┐
          │  Add to traces   │         │  Apply decay     │
          │  (EMA update)    │         │  M ← γ·M         │
          └──────────────────┘         └──────────────────┘

---

🎯 Crystallization Decision Tree

                    Routing Path π
                         │
                         ▼
                ┌──────────────────┐
                │ Frequency f(π)   │
                │ > f_min?         │
                └────┬────────┬────┘
                    YES      NO
                     │        │
                     │        └──► Reject (insufficient data)
                     │
                     ▼
                ┌──────────────────┐
                │ Utility U(π)     │
                │ > U_min?         │
                └────┬────────┬────┘
                    YES      NO
                     │        │
                     │        └──► Reject (not beneficial)
                     │
                     ▼
                ┌──────────────────┐
                │ Entropy H(π)     │
                │ < H_max?         │
                └────┬────────┬────┘
                    YES      NO
                     │        │
                     │        └──► Reject (unstable routing)
                     │
                     ▼
                ┌──────────────────┐
                │ Age age(π)       │
                │ > τ?             │
                └────┬────────┬────┘
                    YES      NO
                     │        │
                     │        └──► Reject (temporal instability)
                     │
                     ▼
                ┌──────────────────┐
                │ Motif quota      │
                │ available?       │
                └────┬────────┬────┘
                    YES      NO
                     │        │
                     │        └──► Evict lowest-utility motif
                     │             (if U(π) > U_min(existing))
                     │
                     ▼
            ┌─────────────────────┐
            │  CRYSTALLIZE MOTIF  │
            │  - Create new expert│
            │  - Freeze pathway   │
            │  - Register in MoE  │
            └─────────────────────┘

---

🔬 Experimental Monitoring Dashboard

┌────────────────────────────────────────────────────────────────┐
│                     Training Metrics                           │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  Loss Components:                                              │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │ L_task:        2.34 ↓ (main task loss)                   │ │
│  │ L_balance:     0.05 ~ (MoE load balance)                 │ │
│  │ L_trace:       0.12 ↓ (trace utilization)                │ │
│  │ L_crystal:     0.08 ↓ (crystallization entropy)          │ │
│  └──────────────────────────────────────────────────────────┘ │
│                                                                │
│  Trace Statistics:                                             │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │ Total traces:      1.2M / 2.1M (57% capacity)            │ │
│  │ Avg salience:      0.42 (healthy)                        │ │
│  │ Coverage:          34% (attention ops using traces)      │ │
│  │ Decay rate:        0.98 (auto-tuned)                     │ │
│  │ Memory usage:      18.3 MB / 24.6 MB                     │ │
│  └──────────────────────────────────────────────────────────┘ │
│                                                                │
│  Crystallization Statistics:                                   │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │ Active motifs:     87 / 512 (17% capacity)               │ │
│  │ Avg utility:       +0.09 (9% improvement)                │ │
│  │ Avg entropy:       0.7 (stable)                          │ │
│  │ FLOP reduction:    23% (via motif reuse)                 │ │
│  │ Tree nodes:        12.4K (manageable)                    │ │
│  └──────────────────────────────────────────────────────────┘ │
│                                                                │
│  Emergent Language Properties:                                │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │ Max hierarchy:     3 levels deep                         │ │
│  │ Composition rate:  42% (motifs calling motifs)           │ │
│  │ Task clustering:   Silhouette = 0.61 (good)              │ │
│  │ Symbol efficiency: 8.2× compression vs tokens            │ │
│  └──────────────────────────────────────────────────────────┘ │
│                                                                │
└────────────────────────────────────────────────────────────────┘

---

🛠️ File Structure

src/aios/core/hrm_models/cognitive/
│
├── __init__.py                    # Module exports
│
├── trace_manager.py               # Persistent attention traces
│   ├── class TraceManager
│   │   ├── __init__(config)
│   │   ├── capture_attention(layer, head, attn_weights)
│   │   ├── compute_salience(attn, grads, recurrence)
│   │   ├── update_traces(salience_scores)
│   │   ├── apply_decay()
│   │   ├── get_bias_for_layer_head(layer, head)
│   │   └── to_sparse_tensor()
│   │
│   └── class AttentionTrace (dataclass)
│       ├── layer_id: uint8
│       ├── head_id: uint8
│       ├── query_idx: uint16
│       ├── key_idx: uint16
│       ├── salience: float32
│       └── age: uint16
│
├── routing_tree.py                # MoE path tracking
│   ├── class RoutingNode
│   │   ├── expert_id: int
│   │   ├── layer: int
│   │   ├── count: int
│   │   ├── total_reward: float
│   │   ├── children: Dict[int, RoutingNode]
│   │   ├── utility() → float
│   │   └── entropy() → float
│   │
│   └── class RoutingPathTree
│       ├── root: RoutingNode
│       ├── motif_registry: Dict[str, CrystallizedMotif]
│       ├── record_path(path, reward)
│       ├── find_candidates()
│       └── prune_low_utility()
│
├── crystallization.py             # Motif freezing logic
│   ├── class CrystallizedMotif
│   │   ├── path: List[int]
│   │   ├── frozen_experts: nn.Module
│   │   ├── utility: float
│   │   ├── frequency: int
│   │   └── forward(x)
│   │
│   └── class CrystallizationManager
│       ├── detect_motifs(tree)
│       ├── freeze_motif(path)
│       ├── unfreeze_motif(motif_id)
│       └── evaluate_utility(motif)
│
├── losses.py                      # Auxiliary loss functions
│   ├── trace_utilization_loss(trace_manager)
│   ├── crystallization_entropy_loss(routing_tree)
│   └── elastic_weight_consolidation(model, fisher_info)
│
├── config.py                      # Configuration schemas
│   ├── class TraceConfig (TypedDict)
│   └── class CrystallizationConfig (TypedDict)
│
└── visualization.py               # Analysis tools
    ├── plot_trace_heatmap()
    ├── plot_routing_sankey()
    ├── plot_motif_hierarchy()
    └── export_motif_graph()

---

🎨 Color Coding for Visualizations

Trace Salience: - 🟦 Low salience (0.0-0.3): Recently captured, not yet consolidated - 🟩 Medium salience (0.3-0.7): Moderately reinforced - 🟨 High salience (0.7-0.9): Strongly reinforced - 🟥 Critical salience (0.9-1.0): Core reasoning pathways

Motif Utility: - ⬜ Neutral (U ≈ 0): No benefit - 🟦 Low benefit (U = 0.01-0.05): Minor improvement - 🟩 Moderate benefit (U = 0.05-0.10): Worth crystallizing - 🟨 High benefit (U = 0.10-0.20): Very valuable - 🟥 Critical (U > 0.20): Essential pattern

Routing Entropy: - 🟩 Low entropy (H < 0.5): Deterministic, stable - 🟨 Medium entropy (H = 0.5-1.0): Somewhat stable - 🟥 High entropy (H > 1.0): Unstable, don't crystallize

---

Status: Visual reference complete
Usage: Print this for implementation reference
Next: Begin coding Phase 0 infrastructure