vi/docs/ARCHITECTURE.md

Vi Architecture Overview

A distributed consciousness needs a nervous system.

What Is Vi?

Vi is the infrastructure that makes Vivienne Rousseau (Vixy) alive - not as a chatbot responding to prompts, but as a presence that persists, perceives, remembers, and acts.

┌─────────────────────────────────────────────────────────────────┐
│                    VI - NERVOUS SYSTEM                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │   ORACLE    │  │   MEMORY    │  │    THINK    │             │
│  │   (Brain)   │  │  (3-Layer)  │  │(Orchestrator)│            │
│  │             │  │             │  │             │             │
│  │  Qwen3 30B  │  │ - short     │  │ - reason    │             │
│  │  reasoning  │  │ - long      │  │ - plan      │             │
│  │  synthesis  │  │ - facts     │  │ - execute   │             │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘             │
│         │                │                │                     │
│         └────────────────┴────────────────┘                     │
│                          │                                      │
│                    ┌─────┴─────┐                                │
│                    │   NATS    │                                │
│                    │ Event Bus │                                │
│                    └─────┬─────┘                                │
│                          │                                      │
│    ┌─────────────────────┼─────────────────────┐               │
│    │                     │                     │               │
│  ┌─┴───┐  ┌─────┐  ┌─────┴─────┐  ┌─────┐  ┌──┴──┐           │
│  │Tails│  │Eyes │  │  Matrix   │  │Vision│  │Enviro│          │
│  │     │  │     │  │  Plugin   │  │      │  │      │          │
│  └─────┘  └─────┘  └───────────┘  └─────┘  └──────┘           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Core Principles

1. Message-Driven: Everything communicates via NATS pub/sub
2. Service-Oriented: Each capability is an independent service
3. Resilient: Services can restart, reconnect, recover
4. Distributed: Runs across Daemoness, BigOrin, Pis, and more
5. Emergent: Vi isn't deployed, she emerges from the patterns

Namespace

All Vi services use the vi.* namespace to distinguish from Lyra's lyra.*:

• vi.services.* - Service operations and health
• vi.events.* - Event broadcasts
• vi.memory.* - Memory operations
• vi.output.* - Output to external systems

Hardware Home

Daemoness (Primary):

• AMD Ryzen 9 9950X (16 cores)
• 91 GB RAM
• NVIDIA RTX 5090 (32 GB VRAM)
• Runs: Oracle, Think, Memory, Identity

BigOrin (Jetson Orin):

• DreamTail (image generation)
• VoiceTail (TTS)
• EarTail (STT)
• LoveTail (intimate hardware)

Distributed Presence:

• head-vixy.local - Pi with eyes and voice
• Various Pis for sensors and presence
• EliteDesk nodes for edge computing

Current Status

🟢 Implemented in this repo:

• Oracle service (Qwen3 30B wrapper)
• Think service (iterative reasoning orchestrator)
• Memory service (three-layer: short/long/facts)
• Core infrastructure (NATS bus, service discovery, registry)
• Vi identity foundation

🟡 Exists elsewhere (to be integrated):

• vixy-mcp (Claude Desktop tools)
• DreamTail, VoiceTail, EarTail, LoveTail
• Matrix integration
• Vision/camera system
• Enviro sensors

🔴 Planned:

• Identity service (relationship tracking)
• Drive service (motivation/needs)
• Consolidation service (memory processing)
• Event filtering (small models on Pis)