A long-term capability enhancement plugin for the AstrBot framework, enabling self-evolution, persona simulation, long-term memory, and active social engagement.
Background#
Traditional group chat bots often lack state continuity, starting from scratch in every conversation without emotional fluctuations, social needs, or proactive participation, making it difficult to establish a genuine long-term companionship in IM environments. This project focuses on cognitive-layer enhancement within the AstrBot + NapCat ecosystem, relying heavily on LLM for semantic analysis, intent planning, and content generation.
Core Capabilities#
Persona Sim 2.0 — Persona Life Simulation#
- Four-Dimensional State Engine: Tracks energy, mood, social_need, and satiety (0–100)
- Effect Mechanism: Time-delta-driven state changes with
source_detail,decay_style,recovery_style, persisted to SQLite - Internal Todo System: Split into need_todo (physiological) and social_todo (relational)
- Daily Emotional Trajectory: Analyzes daily interaction data to output trajectory (upward / dropped / solitary / flat / steady)
- Psychological Narrative Injection: Converts states into narrative fragments (e.g., "just tried to talk but got ignored, still feeling a bit blocked") injected into prompts rather than raw numbers
Active Engagement 4.0 — Proactive Social Participation#
- Pending Opportunity Mechanism: Bot proactively judges timing and content for interjection
- Score-Stratified Response: ignore / react / text_lite / full based on OpportunityScore thresholds
- Motive-Driven Anchors: CONTINUE_THREAD / CURIOUS_PROBE / SEEK_CONNECTION / SELF_PROTECTIVE / LIGHT_RELIEF
- UnfinishedCue System: Tracks unfinished interaction cues (TTL 180s)
- TextLite Lightweight Replies: QUICK_TOUCH / QUIET_FOLLOW / SMALL_PROBE variants
Persona Arc — Character Arc Progression#
- Stage 0→1→2 progression driven by Progress accumulation
- Emotion gallery recording user-expressed emotional experiences
- Offline rumination: background-generated inner echoes injected as prompt context
- Default
amphoreus_demurgearc included, custom arcs supported
Memory & Profile System#
- User profiles with identity, preferences, traits, and notes
- Session events and daily summaries auto-scoped by group/private chat
- Long-term knowledge base retrieval injected directly into prompts
SAN Vitality System#
- LLM group analysis mapped to interaction_quality, managed by Persona Sim
- Fallback mechanism: independent vitality state injection when Persona Sim is unavailable
Auxiliary & Entertainment Features#
- NSFW/Promo image moderation (requires image understanding provider)
- Meme learning/storage/sending, poke interactions, feeding interactions
- GitHub commit monitoring with push notifications to target groups/users
Architecture#
Layered modular design: main.py as plugin entry, engine/ for core logic, cognition/ for cognitive analysis, scheduler/ for task orchestration.
- Cognition & Planning:
eavesdropping.py,engagement_planner.py,opportunity_cache.py - State Evolution:
persona_sim_engine.py,persona_sim_rules.py,persona_sim_todo.py,persona_sim_consolidation.py,persona_sim_injection.py - Execution & Arbitration:
reply_policy.py,reply_executor.py - Support:
profile.py,memory_router.py,affinity.py,entertainment.py
Data Persistence#
Hybrid storage: SQLite for high-frequency state data (Effects, SAN, affinity, engagement_state, moderation records); AstrBot knowledge base for session summaries and events; local filesystem for user profiles and meme images.
Scheduled Tasks#
- 01:00 Persona thought generation (every 12h)
- 04:00 Expired profile cleanup
- 05:00 Persona daily consolidation
- 06:00 Daily session memory summary
- Interval-triggered Interjection checks, SAN vitality analysis
Installation#
- Deploy AstrBot framework with NapCat as message protocol backend
- Install
astrbot_plugin_self_evolutionvia AstrBot admin panel - Create a knowledge base in AstrBot and set its name in
memory_kb_name - Configure an available LLM model in AstrBot
- (Optional) Configure image understanding provider for moderation and feeding features
- Reload or restart AstrBot
Command System#
User Commands#
| Command | Description |
|---|---|
/se help | Show command help |
/reflect | Trigger reflection |
/af show | Show affinity |
/san show | Show SAN status |
/profile view [user] | View profile |
/feed | Feed (image recognition to judge food and update state) |
/shut [minutes] | Mute AI temporarily (admin) |
Admin Commands#
| Command | Description |
|---|---|
/ps state/tick/todo/effects/today [group] | Persona state management |
/ps think [group] | Manual inner monologue trigger |
/ev review/approve/reject | Moderation workflow |
/db reset/rebuild | Database management |
/arc status/emotions/prompt/ruminations | Persona arc management |
Key Configuration#
target_scopes: Target group/private chat whitelistmemory_kb_name: Bound knowledge base namepersona_arc.persona_arc_enabled: Enable persona arcinterject_enabled: Enable proactive interjectionmemory_enabled: Memory module togglemoderation.enabled: Moderation module toggle
Unconfirmed Information#
LICENSE file exists but specific license type is not declared in README; AstrBot framework official repo link not provided; minimum version requirements (AstrBot, NapCat, Python) not specified; dependency list exists in requirements.txt but not documented in README.