MaiBot

Processes incoming messages through a multi-stage pipeline (ChatStream → HeartFlow → HeartFChatting Loop) that maintains conversation context, manages chat state, and routes messages to appropriate handlers. Uses a stream-based architecture that decouples message ingestion from processing, enabling asynchronous handling of multiple concurrent conversations while preserving temporal ordering and relationship context within each chat thread.

Maintains a persistent database of user relationships, interaction history, and personal information (Person Information & Relationships system) that is queried during reply generation to build contextually rich prompts. Retrieves relevant past interactions, known preferences, and relationship dynamics from SQLite storage, then injects this context into the LLM prompt to enable the bot to reference shared history and adapt tone based on relationship type (friend, acquaintance, etc.).

Provides a two-tier configuration system: bot_config.toml for bot-level settings (frequency controls, plugin paths, platform adapters) and model_config.toml for LLM provider credentials and model selection. Configuration is loaded at startup and can be partially reloaded via WebUI API without full restart. Includes environment variable overrides for sensitive credentials (API keys) and official default configurations for common setups.

Implements a SQLite-based message storage system that persists all messages, user relationships, and interaction metadata to a local database. Provides query interfaces for retrieving message history by chat, user, or time range, and supports efficient retrieval of recent messages for context building. Database schema is automatically initialized on first run and includes indexes for common query patterns.

Implements configurable frequency control mechanisms (response_probability, cooldown_seconds, max_responses_per_hour) that limit bot participation in group conversations. Uses probabilistic decision-making combined with time-based cooldowns to create realistic participation patterns that vary by context and relationship. Frequency controls are evaluated by the ActionPlanner during message processing to decide whether the bot should respond.

Provides Docker containerization with multi-architecture support (amd64, arm64) and automated CI/CD pipelines for building and pushing images. Includes Dockerfile for containerized deployment, docker-compose support for local development, and GitHub Actions workflows for automated builds on push/release. Enables easy deployment to cloud platforms and ensures consistent runtime environment across development and production.

Captures and learns user-specific speaking patterns, slang, and jargon through an Expression Learning system that analyzes messages, extracts linguistic patterns, and stores them in a knowledge base (LPMM Knowledge Base). During reply generation, the Replyer applies learned expressions as post-processing rules to transform formal LLM outputs into bot-specific speaking styles, enabling the bot to gradually develop a unique voice that mirrors the communication patterns of its social circle.

Uses an ActionPlanner component that analyzes conversation context and decides whether the bot should respond, what action to take (reply, react, ignore), and how to execute it. The planner evaluates ActionModifier rules and Activation Rules (frequency controls, context triggers, relationship-based conditions) to determine if the bot should participate, enabling autonomous decision-making that avoids constant responses and creates realistic conversation participation patterns without explicit command triggers.

Provides a unified LLMRequest orchestration layer that abstracts multiple LLM providers (OpenAI, Anthropic, Ollama, etc.) through a common interface. Implements model selection logic that chooses between configured models based on availability, cost, or performance characteristics, and includes automatic failover to backup models if the primary provider fails. Supports streaming responses and handles provider-specific API differences transparently.

Provides a plugin architecture with four component types: Actions (BaseAction) for custom behaviors, Commands (BaseCommand) for user-triggered operations, Event Handlers for lifecycle events, and Tools (BaseTool) for external integrations. Plugins are discovered and loaded at runtime from a plugins directory, with each component type implementing a standard interface that integrates into the message processing pipeline. Enables developers to extend bot capabilities without modifying core code.

Implements a dual-layer memory system: the Memory Retrieval System queries stored interactions and relationships during reply generation, while the Dream System periodically processes and consolidates memories during idle periods. Dreams analyze past interactions, extract key insights, and update the LPMM Knowledge Base with consolidated knowledge, enabling the bot to learn from experience and refine its understanding over time without explicit training.

Implements separate reply generation pipelines (group_generator.py, private_generator.py) that adapt response style, length, and tone based on chat context. Group replies are shorter and more conversational to fit natural group dynamics, while private replies are longer and more detailed. Both pipelines use the same underlying Replyer architecture but apply different prompt templates and post-processing rules, enabling context-aware response adaptation.

Provides a web-based dashboard and REST API server (WebUI Server Architecture) that enables remote monitoring and control of the bot. Implements WebSocket communication for real-time updates, REST API routes for configuration and status queries, and a frontend dashboard for visualization. Includes authentication and security mechanisms to protect bot operations from unauthorized access.

Provides a platform adapter abstraction layer that enables the bot to connect to multiple chat platforms (QQ, Discord, Telegram, etc.) through a unified interface. Each platform adapter implements message sending, receiving, and event handling for its specific protocol, while the core bot logic remains platform-agnostic. Adapters handle platform-specific formatting (emojis, mentions, media) and translate between platform-specific and bot-internal message formats.