English | 中文 | 繁體中文 | 한국어

🚀 Features • 🏁 Getting Started • 📦 Building & Running • 🛠️ Tech Stack

---

📖 Overview

Erii is an AI group chat bot system based on a multi-dimensional psychological model. Unlike traditional Q&A bots, Erii has an emotion system, long-term memory, conversation flow and proactive behaviors, enabling it to participate in group chats like a real person, interjecting, breaking the ice, and adjusting speaking style based on emotional state.

✨ Core Features:

• 🎭 Emotion System: Based on PAD model, simulating real emotional responses
• 🧠 Long-term Memory: Multi-dimensional recording of user profiles, preferences, and group chat facts
• 🌊 Flow Mechanism: Dynamically adjusts participation depth based on topic engagement
• ⚡ Proactive Behaviors: Initiates conversations based on impulse values for ice-breaking and daily interactions

🚀 Features

🧠 Core Systems

🎭 Emotion System (Emotion)

• PAD Three-Dimensional Emotion Model - Pleasure, Arousal, Dominance
• Dynamic Emotion Regulation - Real-time emotional state adjustment based on conversation content
• Emotional Expression - Affects reply tone, emoji usage, reply delay
• Long-term Mood - Maintains baseline mood tone, influencing overall behavioral tendencies

💾 Memory System (Memory)

• Multi-dimensional Memory - User profiles, preference settings, factual knowledge, conversation summaries
• Three-level Scope - Global memory, group memory, member-group memory
• Semantic Retrieval - Intelligent memory recall based on vector similarity
• LLM-driven - AI automatically extracts and manages long-term memory

🌊 Flow System (Flow)

• Engagement Quantification - 0-100 flow value, three-stage state machine
• Topic Matching - Quickly enters flow state when encountering interesting topics
• Focus Mechanism - Locks onto conversation goals during high flow, filtering irrelevant distractions
• Overheat Protection - Simulates fatigue to prevent excessive output

⚡ Volition System (Volition)

• Impulse Calculation - Calculates desire to speak proactively based on emotion, flow, and keywords
• Three Interjection Modes - Interrupt, Icebreak, Routine
• Social Awareness - Detects serious topics and group emotions to avoid inappropriate comments
• Fatigue Suppression - Accumulates fatigue after proactive speaking to prevent spamming

🧬 Evolution System (Evolution)

• Vocabulary Learning - Automatically learns new words and memes from group chats
• Semantic Understanding - Records word meanings, usage scenarios, and tones
• Natural Integration - Naturally uses learned group chat expressions in appropriate scenarios

🎭 Meme System (Meme)

• Meme Extraction - Automatically extracts trending phrases and memes from group chats
• Vector Storage - Semantic vector representation, supporting similarity retrieval
• Popularity Tracking - Tracks usage frequency and popularity of high-frequency words

🔌 Built-in Plugins

Plugin	Type	Description
speech	AgentExtension	Text-to-speech plugin using MiniMax TTS
lolisuki	RouteExtension	Anime image plugin from lolisuki.cn
net-ease-music	PassiveExtension	NetEase music plugin for music cards
qa	RouteExtension	AI Q&A plugin with web search
qq-face	PassiveExtension	QQ emoji semantic matching plugin
reminder	AgentExtension	Scheduled reminder plugin
seeddream	RouteExtension	AI image generation plugin

💬 Conversation Enhancement

• Context Understanding - References historical conversations and long-term memory
• Multiple Personas - Supports multiple bot role configurations
• Emotional Resonance - Perceives group atmosphere, adjusts participation style

🏁 Getting Started

📋 Prerequisites

Before you begin, ensure you have the following installed:

• JDK 17+
• Gradle 8.0+
• NapCat - QQ integration service
• LLM API Key - Google Gemini / DeepSeek / MiniMax API

⚙️ Installation & Configuration

1. Clone the repository

   git clone https://github.com/spcookie/Erii.git
   cd Erii

2. Configure environment variables Copy and edit the environment template:

   cp .env.local.template .env.local
   nano .env.local

   Main configuration items:

   • CHOICE_MODEL: Select LLM provider (GOOGLE / DEEP_SEEK / MINIMAX)
   • Corresponding API Key configuration
   • NAPCAT_TOKEN: NapCat authentication token
   • ENABLE_GROUPS: List of enabled groups

3. Configure the bot Copy and edit the configuration template:

   cp application.conf.template application.conf
   nano application.conf

   Main configuration items:

   • llm.choice-model: Select LLM provider (GOOGLE / DEEP_SEEK / MINIMAX)
   • onebot.bots: QQ bot connection information
   • groups.enable-groups: List of enabled groups

4. Start the development server

   ./gradlew run

🐳 Docker Deployment

Start Erii main service

docker-compose up -d

Start NapCat QQ integration service

cd docker/napcat-docker && docker-compose up -d

Start Playwright browser service

cd docker/playwright-docker && docker-compose up -d

🛠️ Tech Stack

🖥️ Backend Framework

• Language: Kotlin 1.9+
• Web Framework: Ktor 2.3+
• Build Tool: Gradle 8.0+
• Database: H2 (Embedded)
• ORM: Exposed
• Dependency Injection: Koin
• Task Scheduling: JobRunr

🤖 Bot Integration

• Bot Framework: Mirai + Overflow
• Integration Service: NapCat (WebSocket)
• LLM: Google Gemini API / OpenAI Compatible API

🔌 Extension Architecture

• Plugin Framework: PF4J
• SPI Interface: erii-spi module defines extension points

📦 Building & Running

Command	Description
./gradlew compileKotlin	Compile Kotlin code
./gradlew build	Build the entire project
./gradlew run	Start development server
./gradlew buildFatJar	Build fat JAR with all deps
./gradlew buildImage	Build Docker image
./gradlew test	Run all tests

📂 Project Structure

Erii/
├── erii-common/                 # 📦 Common module
│   └── src/main/kotlin/uesugi/common/
│       ├── EventBus.kt          # Async/sync event bus
│       ├── BotRole.kt           # Bot role definitions
│       ├── ChatToolSet.kt       # Chat toolset
│       └── ...
├── erii-core/                   # 🧠 Core module
│   └── src/main/kotlin/uesugi/
│       ├── Application.kt       # Ktor application entry
│       ├── config/              # Configuration and DI
│       │   ├── IOC.kt          # Koin DI configuration
│       │   ├── LLMFactory.kt   # LLM factory
│       │   └── ...
│       ├── core/
│       │   ├── agent/          # AI Agent
│       │   │   └── BotAgent.kt  # Core AI Agent
│       │   ├── route/          # Routing system
│       │   │   └── RoutingAgent.kt  # LLM routing
│       │   ├── state/          # Core AI state systems
│       │   │   ├── emotion/     # Emotion system
│       │   │   ├── memory/      # Memory system
│       │   │   ├── flow/        # Flow system
│       │   │   ├── volition/    # Volition system
│       │   │   ├── evolution/   # Evolution system
│       │   │   └── meme/        # Meme system
│       │   ├── bot/            # Bot role management
│       │   │   └── BotRoleManager.kt
│       │   ├── message/        # Message handling
│       │   │   └── history/    # History service
│       │   ├── plugin/         # Plugin implementations
│       │   ├── rule/           # Rule engine
│       │   └── component/      # Components
│       │       ├── browser/   # Browser (screenshot/markdown fetching)
│       │       ├── embedding/  # Vector embedding
│       │       ├── search/     # Search service
│       │       └── storage/    # Storage (vector/object)
│       └── server/             # HTTP API routes
├── erii-spi/                    # 🔌 SPI interface module
│   └── src/main/kotlin/uesugi/spi/
│       ├── AgentExtension.kt   # Agent extension interface
│       ├── PluginDefinition.kt # Plugin definition annotation
│       └── processor/           # Annotation processor
├── erii-plugins/                # 🎨 Plugin modules
│   ├── speech/                  # MiniMax TTS
│   ├── lolisuki/                # Anime images
│   ├── net-ease-music/          # NetEase music search & cards
│   ├── qa/                      # AI web search Q&A
│   ├── qq-face/                 # QQ emoji semantic matching
│   ├── reminder/                # Scheduled reminders & delayed messages
│   └── seeddream/               # AI image generation
└── build.gradle.kts             # Root build configuration

🗺️ Architecture

Erii uses an event-driven architecture with EventBus for system decoupling.

Message Received (NapCat/Mirai)
       │
       ▼
GroupMessageEventListener
       │
       ▼
HistoryService (Save History)
       │
       ▼
RoutingAgent (LLM Intent Classification) / CmdRuleRegister (Command Matching)
       │
       ▼
RouteCallEvent (Dispatched via EventBus.postAsync)
       │
       ▼
BotAgent (Consumes events, executes AI Agent)
       │
       ▼
State Updates (Emotion, Memory, Flow, Volition, Evolution, Meme)

Plugin Extension Points

Extension Type	Description	Matching Method
AgentExtension	General Agent extension	Combined usage
RouteExtension	LLM routing extension	RoutingAgent intent classification
CmdExtension	Command extension	/xxx command matching
PassiveExtension	Passive extension	Background tasks/event listeners

📄 License

This project is open source under the MIT license.

Repobeats

Star History