title: L0: Genesis System Overview

key_content: Full system at a glance. Locked decisions: Widget pricing $497/$997/$1,497 AUD/mo, primary brain Gemini 2.5 Flash via OpenRouter, voice Telnyx NaturalHD Eucalyptus, demo=trial (30s scrape), deep reasoning DeepSeek-R1 (NOT Opus), memory PostgreSQL+Qdrant+Redis on Elestio (NO SQLite), C: drive FORBIDDEN, AIVA UNTOUCHABLE, RLM = Recursive Language Models, agent floor 200 minimum, outreach FROZEN. Components: Command Centre (Claude Opus 4.6), Execution Layer (GEL + RateMax), Agent Fleet (Gemini/Kimi/MiniMax/DeepSeek/Jules), MCP Ecosystem (13 servers), Memory Stack (6 tiers), Products (Widget/Tradie/Sunaiva), n8n (13/20 workflows), AIVA (Mac Mini M4 UNTOUCHABLE).

decisions: DeepSeek-R1 for reasoning NOT Opus (27x cost difference)

decisions: AIVA untouchable: NO SSH to 152.53.201.152

status: AUTHORITATIVE — Updated 2026-02-24


title: L1: Command Centre — Governance and Orchestration

key_content: Brain of Genesis. Claude Opus 4.6 = Orchestrator ONLY — zero grunt work. Decompose → Delegate → Verify → Synthesize. Constitution GENESIS_CONSTITUTION.md v1.0.0 = supreme law, no agent may override. GLOBAL_GENESIS_RULES.md 16 rules v2.2.0. Governance hierarchy: Kinan → Constitution → Global Rules → Claude CC. Escalation to Kinan ONLY for: capital approval, physical 2FA, strategic divergence, identity verification, launch go/no-go. Autonomous: browser automation (Playwright MCP), API calls (13 MCP servers), code execution (Jules + Gemini swarm), research + build (parallel always), platform config (GHL/Stripe/Telnyx/DNS). Operational protocols: Browser-First, Native-First, Research-First, Build-On-Request, Proactivity, Capability-First, Check-Existing-First, No Free Gemini.

decisions: Claude Opus = orchestrator only — never does grunt work

decisions: Kinan is LAST RESORT (capital, 2FA, go/no-go)

decisions: All heavy execution delegated to Gemini swarm / Jules Pro


title: L2: Execution Layer and Model Routing

key_content: Critical rule: NEVER use Opus for tasks DeepSeek-R1 can handle (27x cost difference). Model cost hierarchy: Gemini 2.5 Flash $0.15/MTok (bulk/scraping/browser), DeepSeek-R1 Distill $0.12 (fast reasoning), DeepSeek-R1 671B $0.55 (strategy/architecture), MiniMax M2.5 Free/NIM (content/marketing), Kimi K2.5 $1.07 (agentic/multi-step), Claude Haiku $1.00 (simple transforms), Claude Sonnet $9.00 (coordination), Claude Opus 4.6 $15.00 (strategy ONLY). Execution modes: RWL_SWARM (parallel, 200 agents), RWL_SEQUENTIAL, HYBRID (Gemini+Claude), ALPHA_EVOLVE (self-improvement), AGENT_TEAM (Opus 4.6 experimental). Router logic: Code/Tests/PRs→Jules, Bulk/Scraping→Gemini Flash, Volume/Content→MiniMax, Agentic→Kimi, Strategy→DeepSeek-R1, Orchestration→Opus (last resort), Simple→Haiku.

decisions: Gemini 2.5 Flash is primary execution engine

decisions: DeepSeek-R1 replaces Opus for all reasoning tasks

decisions: Jules Pro for code tasks (100 tasks/day, 15 concurrent)

decisions: RateMaximizer: 90-95% capacity target always


title: L3: Agent Hierarchy — 7 Tiers + 6 Hive Teams

key_content: 200-agent floor LOCKED MANDATE. Alpha Fleet: 100 × MiniMax M2.5 (OpenRouter). Bravo Fleet: 100 × Kimi K2.5 (OpenRouter). Auto-respawn: n8n every 15 min. 7 tiers: T1=Claude Opus 4.6 (Command Centre, Kinan-facing, strategic, delegation only, 200K context, 128K output), T2=Jules Pro (100 tasks/day, 15 concurrent, GitHub-native), T3=Claude Opus/Sonnet sub-agents (complex reasoning, engineering), T4=Claude Sonnet sub-agents (coordination, synthesis), T5=Kimi K2.5 + MiniMax M2.5 + Gemini Flash (volume execution), T6=Gemini CLI+Ultra (multimodal, 1000 images/day, 5 videos/day), T7=Claude Haiku (simple transforms). 6 Hive Teams: FORGE (code/arch/testing, Jules), SURFACE (UI/marketing/products, Gemini CLI), BACKBONE (infra/DevOps, Sonnet), LEGION (high-volume swarm, Kimi+MiniMax), SCOUT (research/exploration, specialised), SENTINEL (monitoring/validation, hooks).

decisions: Agent tracking via hive/agents_active.json

decisions: RAM-aware scaling: max 8 concurrent, stop at 85% RAM


title: L4: Memory Architecture — 6-Tier Stack

key_content: Critical rule: NO SQLite — PostgreSQL ONLY. 4 Elestio services: PostgreSQL (postgresql-genesis-u50607.vm.elestio.app:25432), Qdrant (qdrant-b3knu-u50607.vm.elestio.app:6333), Redis (redis-genesis-u50607.vm.elestio.app:26379), FalkorDB (NOT DEPLOYED, Stage 2 ~$10/mo). 6 tiers: T1=Redis (working memory, session tokens, hot data), T2=PostgreSQL genesis_db (episodic, session history, RLM preference pairs), T3=Qdrant genesis_memories (semantic, 434+ axioms indexed, <200ms search), T4=KNOWLEDGE_GRAPH/ JSONL (intelligence, 300+ nodes, causal links), T5=Supermemory (persistent cross-session, vault 41f4785c), T6=FalkorDB (future graph, Graphiti MCP blocked). Cognitive Heartbeat every 10 min: Blackboard → SurpriseEngine(Violation+Novelty+Impact+Rarity) → AxiomGenerator(HIGH surprise only) → MemoryCortex. RLM Bloodstream: 5 modules in shadow mode first 30 days.

decisions: Qdrant for vectors — 768-dim nomic-embed-text

decisions: Surprise threshold for axiom generation: HIGH only (not mundane events)


title: L5: MCP Ecosystem — 13 Servers

key_content: 13 MCP servers. Quick lookup: CRM/contacts/SMS/bookings → ghl (269 tools), voice/Telnyx/call memory → genesis-voice-bridge (Port 8900), KG/memory/n8n → genesis-core (search_memory, trigger_workflow), browser automation → playwright (navigate/click/extract), email outreach → instantly-outreach (FROZEN), YouTube transcripts → youtube-transcript, persistent memory → sunaiva-memory, web search → brave-search, GitHub → github, deep reasoning → sequential-thinking, patents → patent-os. Core Genesis (Python): genesis-v2 (9 tools), genesis-core (8 tools including gemini_ctm_flush, gemini_respawn_signal), genesis-voice-bridge (Port 8900, SSE, Bearer auth), genesis-full. Business: ghl (node, 269 tools, services.leadconnectorhq.com), patent-os (validate_hallucination, assess_risk, SHA256 audit trail), instantly-outreach (FROZEN — banned until Kinan approval). Memory: sunaiva-memory, brave-search. Developer: github.

decisions: GHL MCP = 269 tools, eliminates browser automation for CRM

decisions: voice-bridge Port 8900 = voice call memory access during calls

decisions: Instantly-outreach FROZEN — outreach banned until Kinan approval

decisions: Patent-os uses SHA256 immutable audit trail for hallucination validation


title: L6: Voice Pipeline — End to End

key_content: PRODUCTION widget live. Assistant UUID: assistant-9c42d3ce-e05a-4e34-8083-c91081917637. Model: Gemini 2.5 Flash via OpenRouter. Voice: Telnyx NaturalHD Eucalyptus (AU female, professional). VAD: 500ms silence=respond, 80ms min speech. WebRTC: unauthenticated_web_calls: true. Embed code: <telnyx-ai-agent agent-id='...'> + script async. Full call flow: Prospect browser → AI Widget → Telnyx Platform → Gemini 2.5 Flash → voice-bridge Port 8900 → PostgreSQL+Qdrant+Redis → n8n → GHL. Lead capture tool: name, phone, service_type, urgency, best_callback_time. Post-call: transcript → PostgreSQL → Qdrant indexing → n8n Lead Capture → GHL contact + pipeline → SMS within 60 seconds (MCTB).

decisions: Official Telnyx widget component: use <telnyx-ai-agent> NEVER build custom SDK

decisions: LLM Secret: gemini-genesis-key ID 5dde93a7

decisions: voice-bridge on Port 8900 is memory access during active calls

decisions: SMS within 60 seconds of call = MCTB (missed call text back)

status: AUTHORITATIVE — PRODUCTION LIVE


title: L7: n8n Automation — 13 Active Workflows

key_content: Instance: https://n8n-genesis-u50607.vm.elestio.app. 13/20 workflows running. P0 Revenue workflows: Telnyx Lead Capture→GHL (ACTIVE), Lead Nurture MCTB 5-Touch (ACTIVE), Review Request Automation (ACTIVE), Tradie Outreach every 15min (ACTIVE), Stripe Lifecycle Handler (PLANNED). P1 Intelligence+Health: Morning Briefing daily 7am (ACTIVE), YouTube Scout every 2hr 8pm-4am (ACTIVE), Health Monitor every 5min (ACTIVE), Continuous Agent Spawner every 15min (ACTIVE), Rate Limit Reset daily 8pm AEST (ACTIVE), Genesis Evolution Sprint every 30min (ACTIVE), Memory Maintenance daily (ACTIVE), Open Deep Research on-demand (ACTIVE). 7 planned workflows remaining: Stripe lifecycle, voicemail transcription, social media posting, appointment reminder, reactivation campaign, competitive monitoring, customer success NPS.

decisions: Stripe Lifecycle Handler = highest priority planned workflow

decisions: Health Monitor → Telegram alerts on breach

decisions: Agent Spawner ensures 200 floor is maintained

decisions: Rate Limit Reset prevents overnight work interruption

status: AUTHORITATIVE — 13/20 active


title: L8: Knowledge Graph Structure and Axiom Cycle

key_content: Location: KNOWLEDGE_GRAPH/ (Local JSONL). Structure: entities.jsonl (300+ named nodes), relationships.jsonl (causal links, confidence 0-1), axioms/ (validated truths, auto-injected), entities/ (sub-directory for deep entities), research/ (patent maps, market pathways), indexes/ (searchable subgraphs). Entity schema: id, type, name, content, source_file, confidence, connections[], status, provenance. Entity types: RESOURCE, PATTERN, DECISION, RELATIONSHIP, CLIENT, AXIOM. Axiom Cycle: EVENT → Blackboard → SurpriseEngine(4D) → AxiomGenerator(HIGH only) → KG/axioms/ + Qdrant → System Prompt injection → Skill Factory (high confidence → new skill). SurpriseEngine 4D: Violation + Novelty + Impact + Rarity.

decisions: 300+ entities in KG — check before building anything

decisions: Axioms auto-injected into next session system prompt

decisions: High confidence axioms → Skill Factory → new Claude skill

decisions: Qdrant mirrors KG axioms for semantic search


title: L9: Revenue Evolution — $0 to $100K MRR

key_content: Current status: $0 revenue (products live, not at scale). Client #001: George Bunker FNQ, Inbound Pro $497/mo. Widget LIVE. Burn rate: ~$1,500 USD/mo (~$2,400 AUD). 12-month revenue path: Month 1 $1K (manual sniper, 5 worst tradie sites, 5:15am AEST emails), Month 3 $15K (30 clients, 10Web API, Instantly sequences, GHL webhooks), Month 6 $44K (agency channel, 1 agency × 50 clients × 20% attach × $97=$679 MRR), Month 12 $100K+ (182 clients @ $550 ARPU, memory lock-in). Product stack: 6 standalone products ($97-$497), 3 bundles ($397-$997). Website poach strategy: Trojan Horse replaces LocalSearch invoice at same price + AI features. Competitive moat: Month 9-12 — client switching cost > annual subscription.

decisions: Month 9-12 = memory lock-in inflection point

decisions: LocalSearch invoice replacement = Trojan Horse strategy

decisions: Agency channel = fastest path to $1K MRR


title: L10: Deep Think Roadmap — DT1 to DT35

key_content: 42 files in deep_think_results/ indexed to KG. 7 tiers: T1 Immediate Revenue (DT1 revenue pathway DONE, DT25 website poach DONE, DT25v2 composable pricing DONE), T2 Automation Engine (DT2 7 n8n workflows DONE, DT3 Radar Audit 30% partial — re-fire needed), T3 Competitive Moats (DT5 memory lock-in DONE, DT6 agent marketplace DONE, DT4 browser agents 87%), T4 Session Intelligence (DT8-DT10 + tapestry ALL DONE), T5 Phone Strategy (DT26 Number Shield Guarantee DONE), T6 Advanced Intelligence (DT27-DT35 READY to fire: FalkorDB, Voice Bridge MCP, Patents×DeepMind, Browser Army, KG Extraction, RLM Activation, Memory Gateway), T7 Vast-Scale Memory (10 synthesized prompts). Search: python3 scripts/deep_think_kg_ingest.py --query 'your question'.

decisions: DT3 Radar Audit = 30% partial, MUST re-fire

decisions: DT4 browser agents = 87% — nearly complete

decisions: DT27-DT35 = READY, fire when capacity available

decisions: Deep Think = strategic DNA of Genesis — read before major decisions


title: Genesis Persistent Context Architecture V2

key_content: Advanced persistent context architecture from Track B of Dual Epic PRD Sprint (73 stories, 9 modules, 2026-02-25). Key modules: Epoch Pipeline (session boundary detection, epoch crystallization), OpenClaw Bridge (AIVA ↔ Genesis bidirectional), Royal Dashboard (AIVA command interface), 7-phase orchestrator (session lifecycle management). Tests: tests/track_b/, tests/epoch/. Builds on Session Continuity Tapestry spec (DT8-DT10). Event sourcing + progressive hydration pattern.

decisions: OpenClaw bridge enables AIVA full genesis-system access

decisions: 7-phase session lifecycle: boot → hydrate → work → monitor → crystallize → handoff → respawn

decisions: All context state persisted to PostgreSQL — no session-bound memory loss

status: COMPLETED — 73/73 stories verified 2026-02-25


title: Genesis Infrastructure Stack — Elestio Core

key_content: Elestio managed infrastructure: PostgreSQL (postgresql-genesis-u50607.vm.elestio.app:25432, genesis_db), Qdrant (qdrant-b3knu-u50607.vm.elestio.app:6333, genesis_memories collection), Redis (redis-genesis-u50607.vm.elestio.app:26379), n8n (n8n-genesis-u50607.vm.elestio.app:443). Total cost: ~$46/mo. Elestio is MANAGED — cannot modify internal settings, only monitor and react. Connection pattern: use .vm.elestio.app domain (NOT .a.elestio.app). Python: psycopg2 for PostgreSQL, qdrant-client for Qdrant, redis-py for Redis.

decisions: Elestio $46/mo is Genesis's backbone — never self-host these

decisions: .vm.elestio.app is correct domain (NOT .a.elestio.app)

decisions: Managed = cannot modify internals, only configure via dashboard

decisions: PostgreSQL is primary DB — Redis for hot cache, Qdrant for vectors

status: LIVE — All 4 services operational


title: Execution Layer — RWL Story Format

file: docs/architecture/02-EXECUTION-LAYER.md (story format section)

key_content: Every task dispatched as Story dataclass: id (str), title (str), description (str), acceptance_criteria (List[Dict]), priority (int 1-10 default 5), model (str default gemini-2.5-flash), max_tokens (int default 8192), temperature (float 0.7), tools (List[str]), timeout_seconds (int default 120). Stories are atomic, testable, completable. After each story: black box tests + white box tests, 100% pass required. Verification stamp format: Story ID, Verified By, Verified At, Tests count, Coverage %. Entry point: core/genesis_execution_layer.py execute_task_sync().

decisions: Story cannot be complete with failing tests

decisions: execute_task_sync() is the one entry point

status: AUTHORITATIVE STANDARD


title: Agent Fleet — Model Cost Matrix and Routing Rules

key_content: Definitive model routing rules: Gemini 2.5 Flash ($0.15/MTok) → bulk, scraping, browser, fast tasks. DeepSeek-R1 Distill ($0.12/MTok) → fast reasoning, code review. DeepSeek-R1 671B ($0.55/MTok) → strategy, architecture. MiniMax M2.5 (Free/NIM) → content, marketing, volume. Kimi K2.5 ($1.07/MTok) → agentic, complex multi-step. Claude Haiku ($1.00/MTok) → simple extraction, grunt. Claude Sonnet ($9.00/MTok) → coordination, management. Claude Opus 4.6 ($15.00/MTok) → strategy ONLY, everything else forbidden. Jules Pro ($0/marginal) → code, tests, PRs, bugs, 100 tasks/day. Never use Opus where DeepSeek-R1 can handle it (27x cost difference).

decisions: Never Opus for reasoning — DeepSeek-R1 27x cheaper

decisions: MiniMax is FREE via NVIDIA NIM — use for all content tasks

decisions: Jules Pro marginal cost $0 — maximize usage for code tasks

decisions: Kimi K2.5 for complex agentic multi-step workflows

status: COST RULES LOCKED


title: Product Architecture — Voice Widget + ReceptionistAI

file: docs/architecture/09-REVENUE-EVOLUTION.md (product stack section)

key_content: 6 standalone products: AI Receptionist $497/mo, Website $397/mo, Database Reactivation $297/mo, Review Generator $197/mo, Talking Widget $197/mo, Missed Call Text Back $97/mo. 3 bundles: Agency Escape $397 (replaces LocalSearch invoice), Ironclad Front Desk $597 (core receptionist), Full Dominator $997 (all 6 products). Progressive discount: 1=0%, 2=15%, 3=25%, 4+=35%. ARPU at scale: $550/mo average (182 clients = $100K MRR). Client #001: George Bunker FNQ — Inbound Pro $497/mo. Widget UUID: assistant-9c42d3ce-e05a-4e34-8083-c91081917637.

decisions: Pricing is LOCKED — never override without Kinan approval

decisions: Agency Escape positions against LocalSearch/Sensis invoice

decisions: Full Dominator = max LTV, target high-intent buyers

decisions: ARPU target: $550/mo to hit $100K MRR at 182 clients

status: PRICING LOCKED


title: Axiom System — KG Heartbeat and Surprise Engine

key_content: Axiom generation pipeline runs every 10 minutes via genesis_heartbeat.py. SurpriseEngine scores events across 4 dimensions: Violation (0.35 weight), Novelty (0.25), Impact (0.25), Rarity (0.15). Scoring: MUNDANE → LOW → MEDIUM → HIGH → SHOCKING. AxiomGenerator fires ONLY on HIGH/SHOCKING events — compresses to truth statement. Output: JSONL entry to KNOWLEDGE_GRAPH/axioms/ + Qdrant vector embedding. Skill Factory trigger: if axiom confidence > 0.90 → generate new Claude skill. Auto-injection: axioms injected into next session system prompt via MemoryCortex. 434+ axioms currently indexed in Qdrant.

decisions: Surprise threshold: HIGH and above only (not MEDIUM or LOW)

decisions: 4D surprise scoring = holistic event evaluation

decisions: Skill Factory creates new skills from high-confidence axioms automatically

decisions: 434+ axioms indexed and semantically searchable

status: OPERATIONAL


title: Deep Think System — 42-File Intelligence Archive

key_content: 42 files indexed in deep_think_results/. Search interface: python3 scripts/deep_think_kg_ingest.py --query 'your question'. Models used: Gemini 2.5 Pro (complex strategy), Gemini 2.5 Flash (rapid synthesis). Tiers: T1 Revenue (3 files, all complete), T2 Automation (2 files, DT3 needs re-fire), T3 Moats (3 files, DT4 87%), T4 Session Intelligence (4 files, all done), T5 Phone Strategy (1 file), T6 Advanced Intelligence (6 files READY), T7 Vast-Scale Memory (10 prompts). Upcoming fires: DT27 FalkorDB+Graphiti, DT28 Voice Bridge MCP, DT29 Patents×DeepMind, DT30-35 browser army, KG extraction, RLM activation, memory gateway.

decisions: DT files are strategic DNA — consult before major decisions

decisions: DT3 re-fire is P1 (Radar Audit architecture incomplete)

decisions: DT27-DT35 fire when Genesis has capacity

decisions: Search DT files before building any major component

status: 42 FILES INDEXED — KG searchable


title: AIVA Architecture — Mac Mini M4 Sovereign Node

key_content: AIVA lives at Mac Mini M4 (192.168.1.57, Apple M4, 24GB RAM, 460GB disk, 380GB free). Ollama v0.15.6: qwen3:14b (9.3GB, 15-30 tok/s, primary brain), nomic-embed-text (274MB, local embeddings), text-embedding-3-small (alias for nomic-embed-text). OpenClaw Gateway v2026.2.21-2, port 18789, LAN bind. 3 agents: voice (Qwen 3 14B local), monitor (Qwen 3 14B local), researcher (Gemini 2.5 Flash OpenRouter, web only). Memory: LanceDB + nomic-embed-text, 768-dim vectors, fully local. Telegram: @AivaTel_bot, chat ID 434761400. 25+ tools, 28 skills, 13 cron jobs. SSH: ssh aiva-mini (user: aivagenesis). CRITICAL: NO SSH to 152.53.201.152 (Elestio VPS, not Mac Mini).

decisions: Mac Mini = sovereign brain — local Ollama, never cloud for core thinking

decisions: 152.53.201.152 = Elestio VPS (UNTOUCHABLE — NO SSH)

decisions: Researcher agent uses Gemini Flash only for web research — privacy-safe

status: OPERATIONAL — Sovereign node active


title: Genesis Stack Completion — 12 Modules (2026-02-25)

key_content: 253/253 tests across 12 modules built concurrently via parallel-builder swarm on 2026-02-25. M1: Infisical secrets (core/secrets/, 16 tests), M2: Ruff+Mypy+pre-commit (pyproject.toml, 4 tests), M3: GitHub Actions CI/CD (.github/workflows/, 14 tests), M4: Alembic migrations (alembic/ + core/models/, 20 tests), M5: Supabase Auth (core/auth/ + api/auth/, 25 tests), M6: Dramatiq task queue (core/task_queue/, 19 tests), M7: Langfuse observability (core/observability/, 27 tests), M8: Prometheus+Grafana (infra/monitoring/, 20 tests), M9: FalkorDB graph (core/graph/, 28 tests), M10: Resend email (core/email/, 22 tests), M11: Stripe billing (core/billing/ + api/billing/, 29 tests), M12: Obsidian+Mermaid (scripts/knowledge/, 29 tests). Full regression: python3 -m pytest tests/infra/ -v (5.36s).

decisions: Infisical = secrets management standard going forward

decisions: Langfuse = observability for all LLM calls

decisions: FalkorDB module built but not yet connected to Elestio instance

dependencies: tests/infra/ core/secrets/ core/auth/ core/task_queue/ core/observability/


title: Dual Epic PRD Sprint — Track A and B (2026-02-25)

key_content: 132/132 stories verified across 2 Epic PRDs. Track A: AIVA RLM Nexus PRD v2 — 59 stories, 9 modules. Track B: Genesis Persistent Context Architecture — 73 stories, 9 modules. Track A modules: preference learning, reward model, PPO engine, DPO trainer, Constitutional AI, gateway, dashboard, metrics API, integration. Track B modules: epoch pipeline, OpenClaw bridge, Royal Dashboard, 7-phase orchestrator, session DNA, delta inheritance, MemoryCortex, progressive hydration, integration. Test locations: tests/track_a/, tests/track_b/, tests/epoch/. Gold standard PRDs: docs/plans/AIVA_RLM_NEXUS_PRD_V2.md (59 stories) and docs/plans/GENESIS_PERSISTENT_CONTEXT_ARCHITECTURE_PRD.md (73 stories).

decisions: Track A = AIVA's self-improvement infrastructure (RLM)

decisions: Track B = Genesis session persistence infrastructure

decisions: Both tracks integrated at Royal Dashboard and OpenClaw bridge

decisions: Zero permanent failures across all 132 stories

status: COMPLETED — 132/132 stories 2026-02-25


title: PRD Atomic Story Doctrine — 17 Laws

key_content: Rule 17 locked after writing two Epic PRDs with 132 atomic stories. 14 PRD Laws: 1 story = 1 file + 1 class + 1 concern, every story has code skeleton with type-annotated signatures, every story names exact E: drive file path, every story has ≥3 BB tests + ≥2 WB tests pre-defined, every story has N implement + N run + N fix + N stamp budget, max 10 stories per module, map requirements to modules BEFORE story 1, final story = integration test, Component Interface Contracts required, Wave Execution Plan required, Global Verification Checklist required, Blueprint before PRD (never invent arch in PRD), title format 'N.NN: [Primary Artifact] — [Key Behavior]', write in append mode 1 module per chunk. Vague PRD = REJECTED.

decisions: PRD Doctrine is HARDWIRED and non-negotiable

decisions: Max 10 stories per module — split if more

decisions: Vague PRD (no file path, no skeleton, no tests) = rejected

decisions: Gold standard PRDs: AIVA_RLM_NEXUS_PRD_V2.md and GENESIS_PERSISTENT_CONTEXT_ARCHITECTURE_PRD.md

status: LOCKED RULE — v2.3.0


title: Voice Pipeline — Lead Capture and CRM Integration

file: docs/architecture/06-VOICE-PIPELINE.md (lead capture section)

key_content: Lead capture tool schema: name (string, required), phone (string, required), service_type (enum: plumbing/electrical/hvac/general), urgency (enum: emergency/scheduled/inquiry), best_callback_time (string). Post-call pipeline: transcript → PostgreSQL call_transcripts → voice-bridge processes → n8n /webhook/telnyx-lead → GHL contact creation → GHL pipeline add → SMS within 60 seconds (MCTB). Memory query at call start: voice-bridge queries Qdrant for caller history by phone number — enables AIVA to recognize returning callers.

decisions: 3 mandatory captures: name → phone → service_type (in order)

decisions: SMS within 60 seconds of call end via n8n MCTB workflow

decisions: Returning caller recognition via Qdrant phone lookup

decisions: Lead capture fires as Telnyx tool call during conversation

status: PRODUCTION ACTIVE


title: Genesis Hooks Architecture

file: .claude/hooks/

key_content: Hardwired hooks for Genesis session management. pre_compact_ctm.py: fires before context compaction, saves session state to handoff file, ensures no context loss. auto_respawn.py: monitors for session crashes, triggers respawn. boot_context_inject.py: injects BOOT_CONTEXT at session start. capability_audit.py: audits model/MCP/beta capabilities at session start, writes to capability_manifest.json. context_70pct_flag.sh: flags when context reaches 70% capacity. session_heartbeat.py: periodic session health signal. stop_state_flush.py: final state save on session stop. memory_context_inject.py: injects relevant memory from KG at session start. post_edit_verify.py: runs tests after file edits. thinking_block_monitor.py: monitors thinking budget usage.

decisions: pre_compact_ctm.py = most critical hook — prevents context loss

decisions: capability_audit.py runs every session start — capability manifest is always fresh

decisions: boot_context_inject.py = MEMORY.md + latest handoff injection

decisions: Hooks fire automatically — never requires human trigger

status: ACTIVE — All hooks deployed


title: Genesis Skills Registry

key_content: Skills registry v2.2.0 with 34 registered skills as of Opus 4.6 Hyperstack upgrade. Skill categories: execution (RWL swarm, rate maximizer, model routing), memory (KG write, axiom generation, Qdrant query), browser (Playwright MCP, Browser-Use, Crawl4AI), voice (Telnyx config, voice bridge, assistant management), business (GHL CRM, Stripe billing, email outreach), research (Deep Think, YouTube intelligence, patent research), infrastructure (Docker, n8n, Elestio monitoring). Skills are auto-promoted from high-confidence axioms via Skill Factory. Check registry before building any custom solution.

decisions: 34 skills registered — check before custom building

decisions: Skills registry = primary CHECK-EXISTING-FIRST tool

decisions: Skill Factory auto-promotes axioms to skills at high confidence

decisions: v2.2.0 is current version as of Hyperstack upgrade

status: 34 SKILLS — v2.2.0 active


title: Genesis Security Architecture — Infisical + Auth

file: core/secrets/ + core/auth/ (M1+M5 Stack Completion)

key_content: Two security modules from Stack Completion PRD (2026-02-25). M1: Infisical secrets management replacing hardcoded credentials. Pattern: from core.secrets import get_secret, SECRET_KEY = get_secret('SECRET_KEY'). All secrets pulled from Infisical vault at runtime. M5: Supabase Auth replacing custom auth. JWT tokens, RLS (Row Level Security) in PostgreSQL, email/OAuth flows. Auth middleware: from core.auth import require_auth. Integration: Supabase handles identity, PostgreSQL handles data, RLS enforces data isolation. 41 tests combined.

decisions: Infisical replaces all .env hardcoded credentials

decisions: Supabase handles identity (not custom auth)

decisions: RLS in PostgreSQL = customer data isolation

status: COMPLETED — M1+M5 verified 2026-02-25

dependencies: core/secrets/ core/auth/ api/auth/


title: Genesis Observability Stack — Langfuse + Prometheus

file: core/observability/ + infra/monitoring/ (M7+M8 Stack Completion)

key_content: Two observability modules from Stack Completion PRD. M7: Langfuse for LLM observability. Tracks: every LLM call (model, tokens, cost, latency), tool calls, trace hierarchy, user sessions. Pattern: from core.observability import trace_llm, @trace_llm decorator on all model calls. Dash: langfuse.company dashboard. M8: Prometheus + Grafana for infrastructure metrics. Metrics: agent counts, API latency, memory usage, queue depths, cost per hour. Grafana dashboards: agent fleet health, revenue metrics, Elestio stack health. 47 tests combined.

decisions: Every LLM call traced via Langfuse — no invisible API costs

decisions: Prometheus scrapes metrics every 15 seconds

decisions: Grafana dashboards replace 22 static HTML dashboards

decisions: Cost per hour = primary operational metric

status: COMPLETED — M7+M8 verified 2026-02-25

dependencies: core/observability/ infra/monitoring/


title: Genesis Billing Architecture — Stripe Integration

file: core/billing/ + api/billing/ (M11 Stack Completion)

key_content: Stripe billing module from Stack Completion PRD. 29 tests. Covers: subscription management ($497/$997/$1,497 tiers), webhook handling (payment.succeeded, subscription.cancelled, payment.failed), usage metering for voice minutes, proration calculations, trial management. Pattern: from core.billing import create_subscription, handle_webhook. Stripe Lifecycle Handler n8n workflow triggers on payment → provisions Telnyx number → creates GHL subaccount → activates widget. Customer portal for self-service billing management.

decisions: $497/$997/$1,497 pricing hardcoded in Stripe products

decisions: Webhook → n8n → Telnyx provisioning within 5 minutes of payment

decisions: Customer portal = zero-touch billing support

decisions: Usage metering for voice minutes tracked per subscription

status: COMPLETED — M11 verified 2026-02-25

dependencies:
core/billing/
api/billing/
n8n Stripe Lifecycle Handler


title: Genesis Task Queue — Dramatiq

file: core/task_queue/ (M6 Stack Completion)

key_content: Dramatiq task queue from Stack Completion PRD. 19 tests. Replaces ad-hoc task dispatch with structured queued execution. Queues: voice_tasks (high priority, 5 workers), agent_tasks (normal priority, 20 workers), email_tasks (low priority, 3 workers), analytics_tasks (background, 2 workers). Workers backed by Redis on Elestio. Pattern: from core.task_queue import dispatch_task, @task decorator. Dead letter queues for failed tasks with retry logic. Monitoring: Dramatiq tasks tracked in Langfuse traces.

decisions: Redis on Elestio as message broker for Dramatiq

decisions: Voice tasks get highest priority (5 dedicated workers)

status: COMPLETED — M6 verified 2026-02-25


title: Genesis Email Infrastructure — Resend

file: core/email/ (M10 Stack Completion)

key_content: Resend email infrastructure from Stack Completion PRD. 22 tests. Covers: transactional emails (welcome, billing, alerts, reports), template management (Jinja2 + React Email), bulk sending (lead nurture sequences), delivery tracking (opens, clicks, bounces). Pattern: from core.email import send_email, EmailTemplate. Integration: n8n triggers Resend for all automated emails. Morning briefing to Kinan, customer onboarding sequences, NAMP reports. All email content generated by MiniMax M2.5 (free content generation).

decisions: MiniMax M2.5 generates all email content (free)

decisions: Morning briefing = first automated email tested

status: COMPLETED — M10 verified 2026-02-25

dependencies:
core/email/
n8n automation workflows


title: FalkorDB Graph Database — Stage 2 Architecture

file: core/graph/ (M9 Stack Completion)

key_content: FalkorDB graph module from Stack Completion PRD. 28 tests. Module built but NOT connected to live Elestio instance (FalkorDB service not deployed). Graph schema: Nodes (Customer, Interaction, Axiom, Agent, Task, Memory), Relationships (REMEMBERED, INFLUENCED, GENERATED, CONNECTED_TO). Pattern: from core.graph import graph_client, create_node, create_relationship. DT27 FalkorDB+Graphiti spec is READY to fire when Elestio instance deployed (~$10/mo). Temporal episodic memory with <200ms recall target.

decisions: Module built, Elestio instance not yet deployed

decisions: Temporal episodic memory = Stage 2 competitive moat

status: MODULE BUILT — Elestio instance needed to activate


title: Genesis Database Migrations — Alembic

file: alembic/ + core/models/ (M4 Stack Completion)

key_content: Alembic migrations from Stack Completion PRD. 20 tests. Manages PostgreSQL schema evolution for genesis_db. Models: User, Subscription, CallTranscript, KGEntity, AgentTask, Preference, RewardScore, ConstitutionalCritique, EpochCheckpoint, SessionDNA. Pattern: alembic upgrade head (auto-applied in CI/CD). Migration history: initial schema, RLM tables, session persistence tables, billing tables. Prevents schema drift between environments. Auto-runs in GitHub Actions on merge to main.

decisions: Alembic manages all schema changes — no manual PostgreSQL DDL

decisions: Models in core/models/ = single source of truth for DB schema

decisions: RLM tables (aiva_rlm schema) are part of Alembic management

status: COMPLETED — M4 verified 2026-02-25


title: Genesis CI/CD Pipeline — GitHub Actions

file: .github/workflows/ (M3 Stack Completion)

key_content: GitHub Actions CI/CD from Stack Completion PRD. 14 tests. Workflows: ci.yml (test+lint on PR), deploy-staging.yml (auto-deploy to staging on main merge), deploy-production.yml (manual trigger + approval), db-migration.yml (Alembic upgrade on deploy). Pre-commit hooks: ruff (linting), mypy (type checking), pytest (unit tests). Pre-commit blocks: SQLite imports, hardcoded secrets, C: drive paths, no verification stamps. Quality gates: 80% coverage minimum, zero security vulnerabilities (bandit), zero type errors (mypy).

decisions: CI runs on every PR — blocks merge if failing

decisions: Production deploy requires manual approval

decisions: Pre-commit hooks enforce Global Genesis Rules automatically

decisions: Coverage minimum: 80% — fails CI below threshold

status: COMPLETED — M3 verified 2026-02-25


title: Genesis Knowledge Management — Obsidian + Mermaid

file: scripts/knowledge/ (M12 Stack Completion)

key_content: Obsidian + Mermaid knowledge management from Stack Completion PRD. 29 tests. Converts KG JSONL entities to Obsidian markdown with wikilinks. Generates Mermaid diagrams from relationship data. Pattern: scripts/knowledge/export_to_obsidian.py generates vault from KNOWLEDGE_GRAPH/. Architecture diagrams auto-generated as Mermaid from entity relationships. Obsidian vault in obsidian-vault/. Bidirectional links between entities. Tags from entity types. Template: entity → markdown file with metadata frontmatter + content + connections section.

decisions: KG is primary source of truth — Obsidian is generated view

decisions: Mermaid diagrams auto-generated from KG relationships

decisions: obsidian-vault/ syncs automatically from KG on session start

decisions: 29 tests = most-tested M12 module in Stack Completion PRD

status: COMPLETED — M12 verified 2026-02-25


title: Genesis Code Quality Standards — Ruff + Mypy

file: pyproject.toml (M2 Stack Completion)

key_content: Code quality infrastructure from Stack Completion PRD. 4 tests (meta-tests). Ruff: Python linter and formatter (replaces flake8+black+isort). Config in pyproject.toml: line-length=88, select E/W/F/I/N/UP, ignore E501. Mypy: strict type checking. Config: strict=true, python_version=3.11. Pre-commit hooks: ruff --fix (auto-format), mypy (type check), pytest --co (collect tests). This M2 is foundational — all other modules must pass Ruff+Mypy before being merged. CI enforcement: ruff check + mypy on every PR.

decisions: Ruff replaces flake8+black+isort (faster, unified)

decisions: Mypy strict mode — all functions must be type-annotated

decisions: Pre-commit auto-fixes lint issues before commit

status: COMPLETED — M2 verified 2026-02-25

dependencies:
pyproject.toml
.github/workflows/
pre-commit config


title: Genesis Voice Pipeline — Telnyx Production Widget Embed

key_content: Production embed code uses official Telnyx web component <telnyx-ai-agent assistant-id='assistant-9c42d3ce-e05a-4e34-8083-c91081917637' invite-button='true'>. George's assistant UUID: assistant-6f6f4ca2-3155-4930-95cb-27f59514af3e. Lead capture webhook: https://api.sunaivadigital.com/webhook/telnyx-lead. Full call flow: visitor -> WebRTC -> Telnyx cloud -> NaturalHD TTS (Eucalyptus) -> AIVA intent classify -> GHL lead capture tool -> n8n workflow -> GHL CRM.

decisions: Official web component over custom SDK (Native-First Rule 9)

decisions: Eucalyptus voice: Kinan-tested AU female NaturalHD

decisions: Unauthenticated web calls enabled for widget demos

dependencies:
Telnyx AI Assistant API
api.sunaivadigital.com
GHL webhooks


title: Genesis n8n Automation — Active Workflow Registry

key_content: 13/20 active workflows. P0 revenue workflows: Telnyx Lead Capture (every call -> GHL), Stripe Webhook Handler (payment -> onboarding), Daily Revenue Report (6am AEST), KaaS Maturity Tracker. P1 intelligence: KG Bloodstream Sync (hourly), AIVA Health Monitor (5min), Mentor Cycle Runner (daily 2am), Instantly Campaign Pulse (daily). P2 operations: n8n instance at n8n-genesis-u50607.vm.elestio.app:443. 7 remaining workflows: planned but not yet imported.

decisions: KaaS maturity workflow imported from n8n/kaas_maturity_workflow.json (P1 action)

decisions: Mentor pairs on daily 2am schedule to avoid peak hours

dependencies:
n8n-genesis-u50607.vm.elestio.app:443
GHL MCP
Telnyx webhook


title: Genesis Revenue Evolution — 12-Month MRR Ladder

key_content: Month 1-3: $0 -> $5K MRR (first 10 tradies at $497). Month 4-6: $5K -> $25K MRR (agency channel opens, composable pricing launch). Month 7-9: $25K -> $75K MRR (hyper-vertical agents, SubAIVA tier launch). Month 10-12: $75K -> $200K MRR (marketplace, enterprise tier). Website poach strategy: identify competitor clients via LinkedIn/GBP scraping. Memory lock-in moat: customer data accumulates in AIVA memory = switching cost increases monthly.

decisions: Website poach as primary acquisition (highest intent prospects)

decisions: Memory as entry product (stickiest, cheapest to deliver)

decisions: Agency channel for multiplication (20-33% recurring commission)

decisions: Composable pricing at Month 4 inflection


title: Genesis Deep Think Roadmap — 42-File Index Status

key_content: 42 files indexed across 7 tiers. Tier 1 (COMPLETE, already in KG): genesis_evolution_learnings, talking_widget_axioms, failure_evolution_log, rlm_axioms series. Tier 2 (READY for ingestion): gsb_supremacy_axioms, prd_doctrine_axioms, real_deep_think_axioms. Tier 3 (PARTIAL): hyper_vertical_agent_paradigm needs second pass. Deep Think query: python3 scripts/deep_think_kg_ingest.py --query 'your question'. All 42 files are KG-indexed for semantic search.

decisions: LightRAG for semantic KG search over JSONL grep

decisions: 7-tier classification by ingestion completeness

decisions: deep_think_kg_ingest.py as standard query interface


title: Genesis Agent Hierarchy — Hive Teams Configuration

key_content: 6 hive teams: FORGE (implementation, Jules Pro), SURFACE (UI/UX, Antigravity), BACKBONE (infra/DB), LEGION (volume execution, Kimi+MiniMax fleet), SCOUT (research, Gemini Flash), SENTINEL (monitoring, Claude Haiku). 200-agent floor mandate: Alpha Fleet 100x MiniMax M2.5, Bravo Fleet 100x Kimi K2.5. RAM-aware scaling config: 4GB/agent max, dynamic scaling based on available RAM. Agent spawn cost at full floor: ~$0.10/day.

decisions: Tiered model selection by task complexity (T1=Opus for orchestration, T7=Haiku for simple tasks)

decisions: 200-agent floor as non-negotiable scale target


title: Genesis Knowledge Graph — SurpriseEngine 4D Scoring

key_content: KG entity schema: id, type, name, observations[], relationships[]. Entity types: person, project, technology, decision, failure, insight, axiom. SurpriseEngine scores new information on 4 dimensions: Novelty (0-1), Importance (0-1), Confidence (0-1), Actionability (0-1). Composite surprise score triggers KG write at threshold >=0.50. Axiom Cycle: raw event -> surprise score -> entity write -> axiom generation -> RLM preference pair. 108 entity files, 15,357 records. 52 axiom files, 1,360 records.

decisions: 4D scoring prevents trivial information overload

decisions: 0.50 threshold balances write frequency with signal quality

decisions: JSONL over relational DB for KG files (portability, git-friendly)

decisions: Separate axioms and entities directories

status: operational


title: Genesis Execution Layer — Model Cost Matrix

key_content: Cost matrix: Claude Opus 4.6 ($15/$75 per MTok in/out), Claude Sonnet 4.6 ($3/$15), Claude Haiku 3.5 ($0.80/$4), Gemini 2.5 Flash ($0.15/$0.60), Gemini 2.5 Pro ($1.25/$10), Kimi K2.5 ($0.14/$0.56), MiniMax M2.5 ($0.20/$1.10). Execution modes: RWL_SWARM (parallel Gemini), RWL_SEQUENTIAL (dependent chain), HYBRID (Claude orchestrates Gemini executes), ALPHA_EVOLVE (recursive self-improvement), AGENT_TEAM (native Claude subagents). Rate Maximizer targets 90-95% API capacity utilization.

decisions: Gemini Flash as default swarm model (cost efficiency)

decisions: Opus only for orchestration and complex reasoning

decisions: Haiku for monitoring, audits, simple checks

decisions: Rate Maximizer as mandatory execution wrapper


title: Genesis MCP Ecosystem — 13 Server Registry

key_content: 13 MCP servers: ghl (269 tools, GHL CRM/automation), genesis-core (8 tools, memory+KG ops), genesis-voice-bridge (port 8900, Telnyx orchestration), genesis-full (extended tools), genesis-mem0 (mem0 memory abstraction), genesis-v2 (v2 architecture tools), patent-os (patent management), playwright (browser automation), instantly-outreach (FROZEN, campaign management), brave-search (web search), youtube-transcript (content extraction), sequential-thinking (chain-of-thought), graphiti-memory (graph memory). Quick lookup table available in architecture doc.

decisions: GHL MCP as primary CRM tool (269 tools replaces manual API calls)

decisions: Playwright for all browser automation (Browser-First Protocol Rule 11)

decisions: Instantly-outreach frozen until campaign credentials verified


title: Genesis System Overview — Locked Architectural Decisions

key_content: All locked decisions in one place: (1) Telnyx NaturalHD Eucalyptus voice (Kinan-tested, locked), (2) Mac Mini M4 for AIVA's sovereign brain (local, never cloud), (3) Elestio managed stack ($46/mo, PostgreSQL+Qdrant+Redis+n8n), (4) GHL as CRM (not Salesforce/HubSpot), (5) Instantly.ai for cold email (15 warmed accounts), (6) Netlify for frontend, (7) No SQLite ever (Rule 7), (8) No C: drive (Rule 6), (9) Gemini Flash as swarm model, (10) Cal.com for booking. Full system map as mermaid diagram.

decisions: Every locked decision documented to prevent rework

decisions: Architecture maps load before any session task (L0 = every session)

decisions: Decisions locked by Kinan are non-negotiable


title: Genesis Persistent Context Architecture V2 — Epoch Pipeline

key_content: 73 stories across 9 modules for session persistence. Module 1: Epoch Pipeline (capture session state). Module 2: OpenClaw Bridge (AIVA <-> Genesis). Module 3: Royal Dashboard (AIVA progress UI). Module 4: Context Compressor (summarize before compaction). Module 5: Heartbeat System (session health monitoring). Module 6: Handoff Generator (automatic CTM at 75% context). Module 7: Boot Context Injector (session start context loading). Module 8: Failure Recovery (crash detection + resume). Module 9: Integration Tests. All 73 stories verified complete as of 2026-02-25.

decisions: 7-phase orchestrator for epoch management

decisions: Handoff at 75% context threshold (not 90% — learned from crashes)

decisions: Boot context injection as mandatory hook

decisions: OpenClaw bridge enables AIVA <-> Claude Code bidirectional comms