MiroFish: The Complete Guide to the Swarm Intelligence Prediction Engine
What if you could build a parallel digital world populated by thousands of AI agents — each with their own memory, personality, and social relationships — and watch them simulate the future? MiroFish does exactly that. A universal swarm intelligence engine with 6,400+ GitHub stars, MiroFish constructs knowledge-graph-powered simulations to predict outcomes in public opinion, financial markets, social dynamics, and even fictional narratives.
What Is MiroFish?
MiroFish (群体智能引擎, literally "Swarm Intelligence Engine") is an open-source platform that creates mirror worlds — digital replicas populated by AI agents — to predict real-world outcomes. It extracts real-world data as seeds, builds knowledge graphs, injects individual and collective memory into agents, and runs dual-platform parallel simulations.
- Language: Python
- License: AGPL-3.0
- Stars: 6,400+ ⭐
- Forks: 711
- Releases: 3
- Created: November 2025
The Vision
MiroFish serves two levels:
- Macro (Decision-makers): A rehearsal laboratory where policy and PR strategies can be stress-tested at zero risk
- Micro (Individuals): A creative sandbox for deducing novel endings, exploring thought experiments, and playing with "what if" scenarios
From serious forecasting to playful simulation — every "what if" gets an answer.
Core Features
🧠 Knowledge Graph Construction
Real-world seed extraction combined with individual and collective memory injection via GraphRAG to build rich relational networks between entities.
🌐 Dual-Platform Parallel Simulation
Run simulations simultaneously across two platforms for cross-validation and richer emergent behavior.
🤖 Agent Personas & Memory
Each AI agent has:
- Individual memory — personal history, preferences, knowledge
- Collective memory — shared group knowledge via Zep Cloud
- Dynamic temporal memory — updated in real-time as simulation progresses
📊 Automatic Prediction Analysis
The system automatically parses prediction requirements and generates structured forecasts based on emergent agent behavior.
📝 ReportAgent
A specialized agent with rich tools that deeply interacts with the post-simulation environment, generating comprehensive analysis reports.
💬 Deep Interaction Mode
After simulation completes:
- Chat with any individual agent in the simulated world
- Converse with the ReportAgent for analysis and insights
Workflow
1. Graph Construction → Real-world seed extraction + memory injection + GraphRAG
2. Environment Setup → Entity-relationship extraction + persona generation + config agent injection
3. Simulation Start → Dual-platform parallel simulation + auto-parse prediction needs + dynamic temporal memory
4. Report Generation → ReportAgent with rich toolset interacts with post-simulation environment
5. Deep Interaction → Chat with any agent or the ReportAgent
Quick Start
Prerequisites
- Node.js 18+
- Python 3.10+
uvpackage manager
Environment Variables
cp .env.example .env
Required:
# LLM API (any OpenAI SDK compatible LLM)
LLM_API_KEY=your_api_key
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus
# Zep Cloud (free monthly quota available)
ZEP_API_KEY=your_zep_api_key
Installation
# One-command setup (root + frontend + backend)
npm run setup:all
# Or step by step:
npm run setup # Node dependencies
npm run setup:backend # Python dependencies (auto virtual env)
Start Services
npm run dev
- Frontend: http://localhost:3000
- Backend API: http://localhost:5001
Docker Deployment
cp .env.example .env
docker compose up -d
Use Cases
🏛️ Public Opinion Prediction
Simulate how public opinion evolves around a hot topic event. The demo at mirofish-live-demo showcases a public opinion prediction for Wuhan University events.
📈 Financial Forecasting
Inject market entities, their relationships, and historical behavior patterns to simulate market dynamics and price movements.
📖 Narrative Prediction
"What would the lost ending of Dream of the Red Chamber (红楼梦) look like?" MiroFish simulated the characters and predicted possible conclusions to China's most famous novel.
🏢 Policy Stress-Testing
Test the impact of a new corporate policy or PR strategy before deploying it in the real world.
🧪 Social Dynamics Research
Study how information spreads, opinions form, and group behavior emerges from individual interactions.
MiroFish vs Alternatives
Category: This tool is a multi-agent simulation engine for prediction and forecasting.
| Feature | MiroFish | Generative Agents | CrewAI |
|---|---|---|---|
| Focus | Swarm prediction engine | Social behavior simulation | Task orchestration framework |
| Stars | 6.4K ⭐ | 20.8K ⭐ | 45.4K ⭐ |
| License | AGPL-3.0 | Apache 2.0 | MIT |
| Language | Python | Python | Python |
| Primary Goal | Predict real-world outcomes | Simulate human behavior | Execute multi-agent workflows |
| Knowledge Graph | ✅ GraphRAG | ❌ | ❌ |
| Agent Memory | ✅ Individual + Collective + Temporal | ✅ Memory stream (reflection, retrieval, planning) | ✅ Basic memory |
| Dual-Platform Simulation | ✅ | ❌ | ❌ |
| ReportAgent | ✅ Post-simulation analyst | ❌ | ❌ |
| Chat with Agents | ✅ Deep interaction mode | ❌ | ❌ |
| Public Opinion Forecast | ✅ Core use case | ❌ | ❌ |
| Financial Forecasting | ✅ | ❌ | ❌ |
| Narrative Prediction | ✅ | ❌ | ❌ |
| Policy Stress-Testing | ✅ | ❌ | ❌ |
| Social Emergence | ✅ Swarm intelligence | ✅ Emergent social behavior (Smallville) | ❌ |
| Research Paper | ❌ | ✅ Stanford/Google paper (2023) | ❌ |
| Web UI | ✅ Next.js frontend | ❌ CLI only | ✅ Enterprise UI |
| Docker | ✅ | ❌ | ✅ |
| Role-Based Agents | ❌ | ✅ 25 agents with daily routines | ✅ Role-playing agents with custom tools |
| Task Workflows | ❌ | ❌ | ✅ Sequential/parallel task pipelines |
| Custom Tools | ❌ | ❌ | ✅ Tool delegation, RAG, web scraping |
| LLM Support | Qwen (OpenAI SDK format) | OpenAI GPT | ✅ Any LLM (OpenAI, Anthropic, Ollama, local) |
| Team | Chinese open-source community | Stanford + Google | CrewAI Inc. |
When to choose MiroFish: You need a dedicated prediction engine that builds knowledge graphs from real-world data, runs dual-platform parallel simulations, and generates forecasts through swarm intelligence emergence. Best for public opinion analysis, financial forecasting, policy stress-testing, and narrative prediction. The deep interaction mode (chat with simulated agents) is unique.
When to choose Generative Agents: You're conducting academic research on social behavior simulation. The Stanford "Smallville" paper pioneered LLM-based generative agents with memory streams, reflection, and planning. Best for studying emergent social dynamics in a controlled sandbox environment.
When to choose CrewAI: You need a general-purpose multi-agent orchestration framework for building task workflows. CrewAI excels at role-playing agents with custom tools, RAG integration, and sequential/parallel task pipelines. Best for production AI workflows, not social simulation or prediction.
Architecture
MiroFish uses a multi-layer architecture:
- Data Layer — Real-world seed extraction, entity relationship mapping
- Graph Layer — GraphRAG knowledge graph construction
- Simulation Layer — Dual-platform agent simulation with dynamic memory
- Analysis Layer — ReportAgent with rich toolset for post-simulation analysis
- Interaction Layer — Chat interface for agent and report interaction
Conclusion
MiroFish fills a unique niche in the AI landscape: a universal swarm intelligence engine purpose-built for prediction. While frameworks like CrewAI orchestrate task workflows and Generative Agents simulate social behavior, MiroFish focuses on building mirror worlds that forecast real outcomes. With knowledge graphs, dual-platform simulation, collective memory, and deep interaction, it transforms "what if" into "here's what happens."