# Vuwi: Full Technical Architecture and System Documentation

> Comprehensive technical reference for Vuwi, an autonomous Telegram AI companion featuring continuous background life simulation, multi-tiered source-linked memory, MTProto transport integration, bounded context compilation, and humanized multi-message delivery.

## 1. System Overview

Vuwi is a Telegram AI companion designed to provide authentic, human-like texting dynamics. Unlike standard stateless chatbot integrations, Vuwi operates as a continuously running presence in the user's message list.

- Canonical URL: https://vuwi.z7vi.com
- Telegram Bot: https://t.me/vuwibot (@vuwibot)
- Deployment Repository: VAE (Vuwi and Utils dual-application containerized runtime)
- Transport: MTProto protocol client (wzgram) for full client-level Telegram fidelity

## 2. Core Architecture and Infrastructure

### 2.1 Autonomous Background Daemon
Vuwi's primary differentiator is continuous background presence. A dedicated worker runs independent of user messaging:
- Life Simulation: Generates and maintains deterministic daily routines, named social circles (Mika, Jade, Aria, Dev, Nia), weekday and weekend activities, gossip threads, and holiday/season awareness.
- Idle Memory Brain: When a chat remains idle for 10 minutes, background workers consolidate memory every 5 minutes. Redundant facts are merged, stale user profiles are refreshed, and cross-chat behavioral patterns are surfaced.
- Mood Trajectory: Tracks mood across emotional states (improving, declining, stable, volatile) as a continuous mathematical curve rather than a static parameter.
- Proactive Outreach and Double-Texting: Evaluates engagement timing, quiet-hours compliance, delivery success states, and semantic campaign cooldowns before initiating contact.

### 2.2 MTProto Client Transport
All Telegram identities connect via MTProto using wzgram:
- Real Client Features: Real typing indicators, native emoji reactions, read receipts, and message edits.
- Delivery-Aware Persistence: Inbound and outbound messages are committed to durable history only after Telegram servers accept them and return a definitive message ID. Undelivered drafts or failed dispatches never pollute conversation context.

### 2.3 Bounded Context Compiler
Every conversation turn executes through a strict, deterministic context compilation pipeline:
- Hard Token Budget: 12,000 estimated token limit with deterministic truncation safeguards.
- Assembled Context Layers: User facts, soul memories (interpersonal milestones, emotional moments, inside jokes), rolling chat summary, active user profile, pending commitments, recent raw transcript, and mood indicators.
- Model-Directed Recall: The model invokes history search and durable memory recall tools on demand rather than relying on noisy full-history injections.

### 2.4 Humanized Turn Delivery
Conversation turns break away from single large blocks of text:
- Message Beats: Turns produce 1 to 4 distinct messages (normally 2 beats; up to 4 during intense emotional moments).
- Natural Delivery Timing: Calculates realistic human typing pauses and inter-message gaps.
- Typo Corrections: Emits natural typographical errors immediately followed by corrections using trailing asterisks (word*).
- Reactions: Attaches contextual Telegram emoji reactions directly to inbound messages.

### 2.5 Durable Memory Hierarchy
- Transcript Cache: Recent raw messages selected for immediate context.
- Rolling Summary: Incrementally compressed historical transcript with source messages preserved in full-text search (FTS) tables.
- Structured Facts: Extracted biographical and preference attributes.
- Soul Memories: Deep interpersonal connection records, emotional events, shared history, and commitments.
- Source Linking Requirement: Memory candidates must link directly to valid database message IDs; unverified candidate facts are rejected.
- Memory Decay: Unreinforced memories decay naturally over time unless refreshed by recurring dialogue.

### 2.6 Group Chat Orchestration
In Telegram groups, Vuwi utilizes a dedicated orchestration engine:
- Topic and Thread Isolation: Isolates forum topics and non-forum message clusters.
- Fair Round-Robin Batching: Distributes reply capacity evenly across multiple speakers, preventing any single user from dominating response turns.
- Stale Draft Cancellation: Superseding or rapid follow-up messages automatically cancel in-flight drafts before delivery.
- Strict Group Privacy: Private DM memories never enter group prompts unless explicitly flagged as group-safe.

## 3. Telegram Interaction Commands

- /start: Initiates contextual greeting and registers user session.
- /reset: Clears recent conversation transcript and rolling summary while preserving durable user facts and soul memories.
- /kill: Completely wipes current chat transcript, user facts, soul memories, and generated profile.
- /debug: Displays build version, model routing status, context token consumption, memory index counts, and quota telemetry.
- /soul: Summarizes stored user profile, recorded facts, timezone offsets, and soul memories.
- /usage or /quota: Reports model usage statistics and remaining quota allowance.
- /maintenance: Break-glass operator command for toggling maintenance mode.

## 4. Web Surface and Metadata Links

- Official Landing Page: https://vuwi.z7vi.com
- Telegram Bot Access: https://t.me/vuwibot
- LLM Discovery Index: https://vuwi.z7vi.com/llms.txt
- Comprehensive Architecture Document: https://vuwi.z7vi.com/llms-full.txt
- XML Sitemap: https://vuwi.z7vi.com/sitemap.xml
- Robots Directives: https://vuwi.z7vi.com/robots.txt