Learnable, configurable, and pluggable Omni Personal Assistant for everyone

ROADMAP | Demo | HomePage | Documents

AlphaAvatar is an Omni-Avatar personal assistant framework designed to evolve into your intelligent personal butler.

✨ Fully self-hostable and privacy-first — you can deploy AlphaAvatar locally or on your own infrastructure, with full control over your data, memory, and behavior.

It is built around a plugin-based Agent architecture, combining:

• 🧠 Full-modality Memory
• 🧬 Dynamic Persona understanding
• 💡 Self-improving Reflection
• 📅 Long-term Planning & Execution
• 🧰 External Tool integrations (MCP / RAG / DeepResearch)
• 😊 Real-time Virtual Character (Avatar)

Together, these components enable AlphaAvatar to move beyond a traditional chatbot into a continuous, personalized, and proactive assistant system.

Our goal is to build an AI that can continuously learn, remember, and act on behalf of the user, acting as a true personal life manager rather than a passive responder.

With the combination of internal Agent plugins and external tools, AlphaAvatar can:

• 📊 Track and analyze personal metrics (health, fitness, sleep, study progress)
• 📈 Provide long-term insights and trend analysis
• 🎯 Suggest improvements based on historical patterns

• 📖 Organize personal notes, documents, and knowledge
• 🔍 Retrieve relevant information via RAG
• 🧠 Build a personal knowledge base over time

• 📅 Schedule tasks and reminders
• ⏰ Proactively notify based on context and priority
• 🔄 Break down long-term goals into actionable steps

• 🧠 Plan multi-step workflows (learning plans, projects, research)
• 🔧 Call tools automatically to complete tasks
• 📌 Maintain consistency across long time horizons

• 🧬 Understand user preferences, habits, and personality
• 💬 Provide highly personalized responses
• 🤝 Maintain continuity across conversations and modalities

• 🌐 Search, research, and summarize real-world information
• 🧰 Integrate with tools (email, database, APIs, messaging apps)
• 🔗 Act as a bridge between user intent and external systems

Unlike traditional AI assistants, AlphaAvatar is:

• Stateful → remembers and evolves with you
• Proactive → acts, not just responds
• Composable → fully plugin-driven architecture
• Omni-modal → supports text, voice, and visual interaction
• Extensible → easily integrates new tools and capabilities

💡 AlphaAvatar is not just an assistant — it is your long-term AI companion and personal operating system.

• [2026/03] We have released AlphaAvatar version 0.5.0 to support the MCP plugin, which enables retrieval and concurrent invocation of the MCP tools.
  • Released AlphaAvatar version 0.5.1: Added WhatsApp channel support via Baileys driver, enabling connection to AlphaAvatar Agent for WhatsApp integration.
  • Released AlphaAvatar version 0.5.2: Add the AlphaAvatar Voice plugin to support the Voice.ai TTS API, providing a wider variety of speaker options.
• [2026/02] We have released AlphaAvatar version 0.4.0 to support RAG by RAG-Anything library and optimized the Memory and DeepResearch modules.
  • Released AlphaAvatar version 0.4.1: Fix the Persona plugin bugs and Add new MCP plugin.
• [2026/01] We have released AlphaAvatar version 0.3.0 to support DeepResearch by tavily API.
  • Released AlphaAvatar version 0.3.1: ADD tool calls during user-Assistant interactions to the Memory module.
• [2025/12] We have released AlphaAvatar version 0.2.0 to support AIRI live2d-based virtual character display.
• [2025/11] We have released AlphaAvatar version 0.1.0 to support automatic memory extraction, automatic user persona extraction and matching.

Install stable AlphaAvatar version from PyPI:

uv venv .my-env --python 3.11
source .my-env/bin/activate
pip install alpha-avatar-agents

Install latest AlphaAvatar version from GitHub:

git clone --recurse-submodules https://github.com/AlphaAvatar/AlphaAvatar.git
cd AlphaAvatar

uv venv .venv --python 3.11
source .venv/bin/activate
uv sync --all-packages

Start your agent in dev mode to connect it to LiveKit and make it available from anywhere on the internet.

🧩 Step 1. Configure Environment Variables

cd AlphaAvatar

# Copy template
cp .env.template .env.dev

Edit .env.dev and set required environment variables.

📦 Step 2. Download Required Files

alphaavatar download-files

✅ Step 3. Run the Agent

ENV_FILE=.env.dev alphaavatar dev examples/agent_configs/pipeline_openai_airi.yaml
# or
ENV_FILE=.env.dev alphaavatar dev examples/agent_configs/pipeline_openai_tools.yaml

To see more supported modes, please refer to the LiveKit doc.

To see more examples, please refer to the Examples README

AlphaAvatar supports multiple Access Channels, allowing different types of users — from end users to developers — to interact with the system.

            AlphaAvatar Runtime
            ───────────────────

    ┌──────────────────────────────┐
    │        AgentSession          │
    │        AvatarEngine          │
    │   (LLM / Memory / RAG / MCP) │
    └──────────────┬───────────────┘
                   │
            InputDispatcher
                   │
            InputEnvelope
                   │
    ┌──────────────┴───────────────┐
    │                              │
Channel Adapters                Native Inputs
(Ingress Layer)                (Web / App)
    │                              │
    ▼                              ▼
WhatsApp / WeChat / Slack      audio / text / video
    │                              │
    └──────────────┬───────────────┘
                   ▼
           OutputDispatcher
                   │
    ┌──────────────┴───────────────┐
    │                              │
Channel Egress                  Native Output
(Messaging APIs)                (WebRTC / UI)

💡 AlphaAvatar uses a Channel Adapter architecture to decouple runtime logic from communication channels.

🖥️ Browser-based interface for real-time interaction. This will become the official AlphaAvatar user interface.

• 🎙️ Real-time voice & multimodal communication
• 🧠 Full plugin support (Memory / RAG / MCP / etc.)
• 😊 Virtual character display

Interact with AlphaAvatar directly inside messaging platforms.

Capabilities:

• 💬 Text-based conversation
• 🎤 Voice message interaction
• 🧰 Tool invocation via chat interface

📦 Channel introduction: README

▶️ Start WhatsApp Channel

Make sure AlphaAvatar Agent is already running (see Quick Start above).

ENV_FILE=.env.dev sh examples/channels/start_whatsapp.sh

💡 The WhatsApp channel runs as an independent bridge process and connects to the Agent runtime.

A dedicated AlphaAvatar mobile application providing:

• 🎙️ Real-time voice communication
• 😊 Live2D / Virtual character visualization
• 🧠 Persistent memory & persona

This is the primary access channel for AlphaAvatar today.

Developers can immediately access AlphaAvatar via the LiveKit Playground.

👉 https://agents-playground.livekit.io/

After starting your AlphaAvatar server:

1. Connect to your LiveKit instance
2. Configure the Agent name in the Playground (must match avatar_name, default: Assistant) to enable Explicit Dispatch.
3. Connect to the agent room
4. Start testing real-time interaction

Supported capabilities:

• 🎙️ Voice interaction
• 🧠 Memory extraction
• 🔍 RAG retrieval
• 🧰 MCP tool invocation
• 😊 Virtual character display

💡 AlphaAvatar is currently developer-first. Web and mobile experiences are actively under development.