Architecture Overview

The Big Picture

Viventium is a modular system, not a monolith. Every piece does one job and connects through well-defined boundaries. That makes it possible to swap models, add surfaces, or extend capabilities without rewriting the core.

Here is the high-level flow:

You (voice, chat, Telegram, scheduled prompt)
  │
  ▼
┌─────────────────────────────────────┐
│  Main Agent  (frontal cortex)       │
│  LibreChat UI + AgentClient         │
└──────────┬──────────────────────────┘
           │
     ┌─────┴──────┐
     ▼             ▼
┌──────────┐  ┌──────────────────────────┐
│ Fast     │  │ Background Cortex Service │
│ Reply    │  │ (activation → execution   │
│          │  │  → insight merge)         │
│          │  └──────────┬───────────────┘
│          │             │
│          │       ┌─────┴──────────┐
│          │       ▼                ▼
│          │  ┌─────────┐   ┌────────────┐
│          │  │Red Team │   │ Other      │
│          │  │Cortex   │   │ Cortices   │
│          │  └─────────┘   └────────────┘
│          │
└──────────┘
     │
     ▼
┌────────────────────────────────────────────────────┐
│                  Shared Services                    │
│                                                    │
│  Memory System    Scheduling Cortex (MCP + SQLite) │
│  Voice Gateway    Connected Workspaces (MCPs)      │
│  Telegram Bridge  SearXNG / Firecrawl              │
│  GlassHive        Config (config.yaml)             │
└────────────────────────────────────────────────────┘

Core Components

Main Agent (Frontal Cortex)

The one you talk to. Built on LibreChat's agent infrastructure, extended with Viventium's activation layer. It handles the live conversation, decides when to invoke background agents, and merges their insights back in.

Internally this is still called the frontal cortex — the brain analogy for the conscious, coherent stream of thought you experience.

Background Cortex Service

Manages the lifecycle of background agents. Two phases:

1. Activation detection — a fast, lightweight check (currently powered by Groq for speed and cost) that evaluates whether the current message warrants deeper background work
2. Asynchronous execution — the selected cortex runs independently, uses its own tools and model, and produces structured output that merges back as a follow-up

The main reply never waits for background agents. That is the non-blocking principle.

Voice Gateway

Real-time voice through LiveKit, with:

• Whisper C++ — local speech-to-text, no audio leaves your machine
• Chatterbox — local text-to-speech for natural voice output
• Low-latency streaming optimized for natural interruption
• Full continuity with chat and messaging — same memory, same background agents

Voice is not a gimmick surface. It is designed as a full conversational channel with the same intelligence underneath.

Telegram Bridge

Mobile continuity through Telegram. Same main agent, same background agents, same memory. Supports text, voice notes, scheduled delivery, and background follow-through.

The Scheduling Cortex dispatches to Telegram when the user is away from the desktop surface.

Scheduling Cortex

A dedicated MCP server with its own SQLite store. It manages:

• Per-user task persistence
• CRUD + search tools exposed to the main agent
• A background scheduler loop that fires tasks on time
• Multi-channel dispatch (LibreChat UI, Telegram)
• Misfire handling for reliability

The main agent creates and manages schedules through tool calls. No special UI needed — scheduling is a capability, not a separate app.

Memory System

Memory in Viventium is layered, not a single blob:

The memory subsystem supports both v0.3's vector-based semantic/episodic recall and v0.4's key-value store with structured injection. Retrieval discipline matters more than storage volume — the system selectively injects relevant context rather than dumping everything.

Connected Workspaces (MCPs)

Model Context Protocol servers bridge Viventium to external systems:

• Google Workspace — Gmail, Calendar, Drive, Docs, Sheets, Slides, Tasks, Forms
• Microsoft 365 — Outlook, OneDrive, Excel, OneNote, To Do, Planner
• Web search — SearXNG (self-hosted, private)
• Web crawling — Firecrawl for deep page extraction
• Custom MCPs — extensible surface for any tool

GlassHive

The persistent worker runtime. Built on:

• FastAPI control plane managing worker lifecycle
• SQLite persistence for project and worker state
• Workstation profiles — codex-cli, claude-code, openclaw-general
• noVNC browser view for live visual inspection
• WebSocket terminal for real-time takeover
• MCP wrapper supporting streamable-http, stdio, and SSE

Each worker runs in an isolated sandbox. One worker, one sandbox, one project.

Configuration

Everything flows from one canonical config file:

~/Library/Application Support/Viventium/config.yaml

This file is the source of truth for:

• Which AI providers and models each component uses
• Which background agents are enabled and their activation thresholds
• Connected account settings
• Voice configuration
• Scheduling preferences

The installer writes it. bin/viventium doctor validates it. Runtime files compile from it into ~/Library/Application Support/Viventium/runtime/.

Where The Neuroscience Shows Up

The architecture maps to a simplified brain model:

This is not metaphor for marketing — it is the actual design principle that shapes how components interact.

Keep Reading

• Brain-Inspired System — The conceptual model behind this architecture
• Background Agents — How activation and follow-through work in detail
• Red Team Cortex — The bias-detection agent that challenges your thinking
• Projects, Workers & GlassHive — The execution layer in depth