# Genesis Context Tier Architecture
## Visual Breakdown: Hot/Warm/Cold Memory

```
┌─────────────────────────────────────────────────────────────────┐
│                      GENESIS CONTEXT TIERS                      │
│                   "Human Memory-Inspired AI"                    │
└─────────────────────────────────────────────────────────────────┘

╔══════════════════════════════════════════════════════════════════╗
║  HOT TIER: Always Loaded (Target: <1K tokens)                   ║
║  "Working Memory" — Immediate context for every session          ║
╚══════════════════════════════════════════════════════════════════╝

┌──────────────────────────────────────────────────────────────────┐
│ CLAUDE.md (300 tokens)                                           │
├──────────────────────────────────────────────────────────────────┤
│ • Prime Directives (3 lines)                                     │
│   1. MEMORY — Persistent, contextual, cross-session              │
│   2. EVOLUTION — Recursive self-improvement                      │
│   3. REVENUE — Generate value, ship products                     │
│                                                                  │
│ • Command Centre Doctrine (5 lines)                             │
│   - This terminal = orchestration (Kinan + Claude)               │
│   - ALL execution delegated to background agents                 │
│   - Dispatch via Task tool (run_in_background=true)              │
│                                                                  │
│ • Critical Warnings (2 lines)                                    │
│   - AIVA server 152.53.201.152 UNTOUCHABLE                       │
│   - C: drive forbidden, all work on E:\genesis-system            │
│                                                                  │
│ • Key Commands (4 lines)                                         │
│   /hyperstack, /context, supermemory search                      │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│ MEMORY.md (400 tokens)                                           │
├──────────────────────────────────────────────────────────────────┤
│ • Current Date: 2026-02-15                                       │
│ • Active Mission: AIVA Queen Ascension (Phase 3/4)               │
│ • Critical Infrastructure:                                       │
│   - AIVA: Mac Mini M4 @ 192.168.1.57 (ssh: aiva-mini)            │
│   - Elestio: 152.53.201.152 (UNTOUCHABLE)                        │
│   - Working Dir: /mnt/e/genesis-system                           │
│ • Memory Systems:                                                │
│   - Supermemory: ./mcp-servers/supermemory/                      │
│   - FalkorDB: localhost:6379                                     │
│   - Elestio Core: PostgreSQL/Qdrant/Redis                        │
│ • Quick Status (10 lines max):                                   │
│   - Last completed: [brief]                                      │
│   - Next: [brief]                                                │
│   - Pointer: supermemory search "war-room-2026-02-15"            │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│ .claude/rules/always-loaded/ (300 tokens total)                  │
├──────────────────────────────────────────────────────────────────┤
│ • 00-prime-directives.md (100 tokens)                            │
│ • 01-execution-mandate.md (100 tokens)                           │
│ • 02-infrastructure.md (100 tokens)                              │
└──────────────────────────────────────────────────────────────────┘

Total Hot Tier: ~1,000 tokens (5x reduction from current 10.6K)


╔══════════════════════════════════════════════════════════════════╗
║  WARM TIER: Conditionally Loaded (0-2K tokens based on context) ║
║  "Short-Term Memory" — Relevant recent knowledge                 ║
╚══════════════════════════════════════════════════════════════════╝

┌──────────────────────────────────────────────────────────────────┐
│ .claude/rules/conditional/testing.md (~500 tokens)               │
├──────────────────────────────────────────────────────────────────┤
│ paths:                                                           │
│   - "**/*.test.ts"                                               │
│   - "**/*.spec.py"                                               │
│   - "**/tests/**"                                                │
│                                                                  │
│ Content:                                                         │
│ • Black box testing protocol                                     │
│ • White box testing protocol                                     │
│ • 100% verification requirement                                  │
│ • Story completion gate                                          │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│ .claude/rules/conditional/research-first.md (~400 tokens)        │
├──────────────────────────────────────────────────────────────────┤
│ paths:                                                           │
│   - "TRADIES/**"                                                 │
│   - "RECEPTIONISTAI/**"                                          │
│   - "AGILEADAPT/**"                                              │
│                                                                  │
│ Content:                                                         │
│ • Read before build mandate                                      │
│ • Data fabrication forbidden                                     │
│ • Research-led decision making                                   │
│ • Key research locations table                                   │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│ .claude/rules/conditional/native-first.md (~300 tokens)          │
├──────────────────────────────────────────────────────────────────┤
│ paths:                                                           │
│   - "integrations/**"                                            │
│   - "workflows/**"                                               │
│   - "n8n/**"                                                     │
│                                                                  │
│ Content:                                                         │
│ • Decision hierarchy (native → template → library → custom)      │
│ • No quick fixes mandate                                         │
│ • Simplicity principle                                           │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│ .claude/rules/conditional/aiva-protection.md (~200 tokens)       │
├──────────────────────────────────────────────────────────────────┤
│ paths:                                                           │
│   - "scripts/**"                                                 │
│   - "deploy/**"                                                  │
│   - "**/ssh*"                                                    │
│                                                                  │
│ Content:                                                         │
│ • NO SSH to 152.53.201.152                                       │
│ • NO modifications to AIVA's server                              │
│ • NO pulling/deleting Ollama models                              │
│ • Violation = immediate termination                              │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│ .claude/rules/conditional/prd-structure.md (~300 tokens)         │
├──────────────────────────────────────────────────────────────────┤
│ paths:                                                           │
│   - "plans/**/*.md"                                              │
│   - "docs/**/*PRD*.md"                                           │
│                                                                  │
│ Content:                                                         │
│ • PRD template structure                                         │
│ • Atomic story requirements                                      │
│ • Verification checklist                                         │
└──────────────────────────────────────────────────────────────────┘

Example Token Load:
  Working on TRADIES/strategy.md:
    Hot: 1,000 + Warm: 400 (research-first) = 1,400 tokens

  Working on core/tests/test_executor.py:
    Hot: 1,000 + Warm: 500 (testing) = 1,500 tokens

  Working on integrations/n8n/workflow.json:
    Hot: 1,000 + Warm: 300 (native-first) = 1,300 tokens

  Working on CLAUDE.md (no special paths):
    Hot: 1,000 + Warm: 0 = 1,000 tokens


╔══════════════════════════════════════════════════════════════════╗
║  COLD TIER: On-Demand Only (0 tokens at boot)                   ║
║  "Long-Term Memory" — Historical context retrieved as needed     ║
╚══════════════════════════════════════════════════════════════════╝

┌──────────────────────────────────────────────────────────────────┐
│ Supermemory MCP (mcp-servers/supermemory/)                       │
├──────────────────────────────────────────────────────────────────┤
│ • War room status: supermemory search "war-room-2026-02-15"      │
│ • Completed sessions: supermemory search "session-archive"       │
│ • Architecture patterns: supermemory search "patterns"           │
│ • Infrastructure details: supermemory search "infrastructure"    │
│ • Key insights: supermemory search "learnings"                   │
│                                                                  │
│ Load time: ~500ms per query                                      │
│ Token cost: 0 at boot, ~300-500 per retrieval                    │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│ docs/ Folder (reference on-demand)                               │
├──────────────────────────────────────────────────────────────────┤
│ • @docs/ALPHA_EVOLVE.md — Full protocol details                  │
│ • @docs/HYPERSTACK_CAPABILITIES.md — Complete feature list       │
│ • @docs/EVOLUTION_PROTOCOL.md — Recursive improvement process    │
│ • @docs/PATTERNS.md — Architecture patterns catalog              │
│ • @docs/RULES_ARCHIVE.md — Historical rule versions              │
│                                                                  │
│ Load time: Instant (local file)                                  │
│ Token cost: 0 at boot, variable per file                         │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│ .claude/agents/manifest.json (loaded on team creation)           │
├──────────────────────────────────────────────────────────────────┤
│ • 8 agent definitions                                            │
│ • Thread type mappings                                           │
│ • When-to-use guide                                              │
│                                                                  │
│ Load trigger: TeamCreate skill invoked                           │
│ Token cost: 0 at boot, ~500 when team created                    │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│ .claude/skills/registry.json (lazy-loaded via ToolSearch)        │
├──────────────────────────────────────────────────────────────────┤
│ • 64 skill definitions                                           │
│ • Loaded only when skill invoked or searched                     │
│                                                                  │
│ Load trigger: ToolSearch or skill execution                      │
│ Token cost: 0 at boot, ~200-400 per skill                        │
└──────────────────────────────────────────────────────────────────┘


╔══════════════════════════════════════════════════════════════════╗
║  PROMPT CACHING (API ONLY)                                       ║
║  "Cache Frequently Accessed Hot Tier Content"                    ║
╚══════════════════════════════════════════════════════════════════╝

Cache Breakpoint Strategy:

┌──────────────────────────────────────────────────────────────────┐
│ System Prompt Structure:                                         │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│ ┌────────────────────────────────────┐                          │
│ │ Prime Directives (200 tokens)      │ [CACHE BREAKPOINT 1]     │
│ └────────────────────────────────────┘                          │
│   ↓ Cached: 90% cost reduction on subsequent calls              │
│                                                                  │
│ ┌────────────────────────────────────┐                          │
│ │ Command Centre (150 tokens)        │ [CACHE BREAKPOINT 2]     │
│ └────────────────────────────────────┘                          │
│   ↓ Cached: 90% cost reduction                                  │
│                                                                  │
│ ┌────────────────────────────────────┐                          │
│ │ Infrastructure (250 tokens)        │ [CACHE BREAKPOINT 3]     │
│ └────────────────────────────────────┘                          │
│   ↓ Cached: 90% cost reduction                                  │
│                                                                  │
│ ┌────────────────────────────────────┐                          │
│ │ Current Mission (400 tokens)       │ [NO CACHE — changes]     │
│ └────────────────────────────────────┘                          │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

First Call Economics:
  Total tokens: 1,000
  Cache write cost: 750 tokens (600 cached) × 1.25 + 400 uncached
                  = 750 + 400 = 1,150 token cost (+15%)

Subsequent Calls (within 5 min TTL):
  Total tokens: 1,000
  Cache read cost: 600 × 0.10 + 400 = 60 + 400 = 460 token cost (-54%)

Session Economics (10 calls):
  Without caching: 10 × 1,000 = 10,000 token cost
  With caching: 1,150 + (9 × 460) = 1,150 + 4,140 = 5,290 token cost
  Savings: 47% (and responses 2-10x faster)


╔══════════════════════════════════════════════════════════════════╗
║  COMPARISON: BEFORE vs AFTER                                     ║
╚══════════════════════════════════════════════════════════════════╝

BEFORE (Current Genesis):
┌──────────────────────────────────────────────────────────────────┐
│ Boot Cost: 10,562 tokens                                         │
├──────────────────────────────────────────────────────────────────┤
│ CLAUDE.md                      1,557 tokens (14.7%)              │
│ MEMORY.md                      2,011 tokens (19.0%)              │
│ GLOBAL_GENESIS_RULES.md        2,494 tokens (23.6%)              │
│ Skill Registry                 4,000 tokens (37.9%)              │
│ Agent Manifest                   500 tokens (4.7%)               │
├──────────────────────────────────────────────────────────────────┤
│ 3-agent team overhead: 31,800 tokens                             │
│ 7-agent swarm overhead: 74,300 tokens                            │
└──────────────────────────────────────────────────────────────────┘

AFTER (Tiered Architecture):
┌──────────────────────────────────────────────────────────────────┐
│ Boot Cost: ~1,000 tokens                                         │
├──────────────────────────────────────────────────────────────────┤
│ Hot Tier (always)              1,000 tokens (100%)               │
│ Warm Tier (conditional)        0-500 tokens (loaded as needed)   │
│ Cold Tier (on-demand)            0 tokens (MCP/docs)             │
├──────────────────────────────────────────────────────────────────┤
│ 3-agent team overhead: 3,000-4,500 tokens (90% reduction)        │
│ 7-agent swarm overhead: 7,000-10,500 tokens (90% reduction)      │
└──────────────────────────────────────────────────────────────────┘

AFTER + CACHING (API):
┌──────────────────────────────────────────────────────────────────┐
│ Effective Cost: ~100-200 tokens (for repeat sessions)            │
├──────────────────────────────────────────────────────────────────┤
│ First call:   1,000 tokens → 1,150 cost (+15% write premium)     │
│ Next 9 calls: 1,000 tokens → 460 cost each (-54% each)           │
│ Total session (10 calls): 5,290 tokens vs 10,000 (47% savings)   │
├──────────────────────────────────────────────────────────────────┤
│ Plus: 2-10x faster response times for cached content             │
└──────────────────────────────────────────────────────────────────┘


╔══════════════════════════════════════════════════════════════════╗
║  DECISION TREE: Which Tier for What Content?                     ║
╚══════════════════════════════════════════════════════════════════╝

┌─────────────────────────────────────────┐
│ Is this content needed EVERY session?   │
└─────────────────┬───────────────────────┘
                  │
        ┌─────────┴─────────┐
        │                   │
       YES                 NO
        │                   │
        ▼                   ▼
  ┌───────────┐      ┌─────────────────────────┐
  │ HOT TIER  │      │ Is it needed frequently │
  │ (inline)  │      │ for specific contexts?  │
  └───────────┘      └──────────┬──────────────┘
                                │
                      ┌─────────┴─────────┐
                      │                   │
                     YES                 NO
                      │                   │
                      ▼                   ▼
               ┌────────────┐      ┌───────────┐
               │ WARM TIER  │      │ COLD TIER │
               │(conditional│      │ (MCP/docs)│
               │   rules)   │      └───────────┘
               └────────────┘

Examples:
  "Prime Directives" → HOT (needed every session)
  "Testing Protocol" → WARM (only when working on tests)
  "Completed Session 4 Details" → COLD (query when needed)


╔══════════════════════════════════════════════════════════════════╗
║  IMPLEMENTATION TIMELINE                                         ║
╚══════════════════════════════════════════════════════════════════╝

Week 1: Compress (30% reduction)
  ├─ Day 1-2: Compress CLAUDE.md, MEMORY.md
  └─ Day 3: Move verbose content to docs/

Week 2: Conditional Rules (50% reduction)
  ├─ Day 4-5: Create .claude/rules/conditional/
  ├─ Day 6: Add YAML frontmatter with paths
  └─ Day 7: Test path matching

Week 3: MCP Integration (70% reduction)
  ├─ Day 8-9: Archive to Supermemory
  ├─ Day 10: Update MEMORY.md to pointers
  └─ Day 11: Test retrieval latency

Week 4: Full Tiered (90% reduction)
  ├─ Day 12-13: Micro CLAUDE.md + MEMORY.md
  ├─ Day 14: Externalize manifests/registries
  └─ Day 15: Validation + documentation

Ongoing: Monitor & Iterate
  └─ Track token usage, cache hits, adjust tiers


╔══════════════════════════════════════════════════════════════════╗
║  SUCCESS METRICS                                                 ║
╚══════════════════════════════════════════════════════════════════╝

Target Metrics (Week 4):
  ✓ Boot cost: 10,562 → 1,100 tokens (90% reduction)
  ✓ 7-agent swarm: 74,300 → 7,700 overhead (90% reduction)
  ✓ Cache hit rate: 80%+ (API usage)
  ✓ MCP retrieval: <500ms average
  ✓ Conditional rules: 95%+ accuracy (load when expected)
  ✓ Zero regressions: All existing tasks still work

Quality Metrics:
  ✓ Agent success rate: Unchanged or improved
  ✓ Context errors: Zero increase
  ✓ Compaction quality: Same or better
  ✓ Developer experience: Faster, cleaner sessions


══════════════════════════════════════════════════════════════════

This tiered architecture enables Genesis to scale from 7 agents to
1000 agents without context becoming the bottleneck.

"The depth of optimization determines the height of scale."

══════════════════════════════════════════════════════════════════
