Introduction
MiroFish is a next-generation AI prediction engine powered by multi-agent technology that has garnered over 51,667 stars on GitHub. This open-source project represents a significant leap forward in swarm intelligence systems, enabling users to predict social trends, simulate complex scenarios, and explore “what if” questions in a sophisticated digital sandbox environment.
At its core, MiroFish extracts seed information from the real world, such as breaking news, policy drafts, or financial signals, and automatically constructs a high-fidelity parallel digital world. Within this space, thousands of intelligent agents with independent personalities, long-term memory, and behavioral logic freely interact and undergo social evolution. Users can inject variables dynamically from a “God’s-eye view” to precisely deduce future trajectories, essentially rehearsing the future in a digital sandbox before making real-world decisions.
The project is powered by OASIS (Open Agent Social Interaction Simulations) from CAMEL-AI and has received strategic support and incubation from Shanda Group. Whether you’re a decision-maker looking to test policies at zero risk, or an individual user wanting to explore creative scenarios like deducing novel endings, MiroFish makes it possible to predict anything.
Architecture Overview
The MiroFish architecture represents a sophisticated multi-layered system designed to handle complex swarm intelligence simulations. At the foundation, the system integrates with external data sources and APIs, including social media platforms like Twitter and Reddit, as well as knowledge graph services through Zep Cloud integration. This foundational layer ensures that the simulation has access to real-world data and can maintain persistent memory across sessions.
The core architecture consists of several interconnected modules that work in harmony. The Graph Building module handles seed extraction and memory injection, constructing GraphRAG structures that enable agents to access contextual knowledge efficiently. This is where the system transforms raw input data into structured knowledge graphs that agents can query and reason about during simulations.
The Environment Setup layer is responsible for entity relationship extraction and persona generation. Each agent in the simulation receives a detailed persona configuration including MBTI personality types, age, gender, profession, and behavioral characteristics. This granular approach to agent definition ensures that the simulated population reflects the diversity and complexity of real-world social dynamics.
The Simulation Engine sits at the heart of the architecture, managing dual-platform parallel simulations across Twitter and Reddit environments. This engine handles the orchestration of thousands of agents, their interactions, and the temporal evolution of the simulated world. The engine supports dynamic memory updates, allowing agents to learn and adapt their behavior based on simulation events.
The Report Generation module, powered by ReACT-based agents, provides deep analytical capabilities for interpreting simulation results. This layer interfaces with the simulation environment to extract insights, identify patterns, and generate comprehensive prediction reports that users can act upon.
Finally, the Deep Interaction layer enables users to engage directly with the simulated world, chatting with individual agents or interacting with the ReportAgent to explore specific aspects of predictions. This bidirectional communication channel transforms MiroFish from a passive prediction tool into an interactive exploration platform.
5-Step Prediction Workflow
MiroFish implements a comprehensive 5-step prediction workflow that guides users from initial data input to final actionable insights. This structured approach ensures systematic progression through each phase of the prediction process while maintaining flexibility for different use cases.
Step 1: Graph Building serves as the foundation of the entire workflow. In this phase, the system performs seed extraction from uploaded materials, which can include data analysis reports, news articles, or even creative content like novel chapters. The seed information is processed to extract key entities, relationships, and events that will form the basis of the simulation. Individual and collective memory injection occurs simultaneously, where the system loads relevant historical context and knowledge into the simulation environment. The GraphRAG construction process creates a queryable knowledge graph that agents can reference during their interactions, enabling contextually aware behavior.
Step 2: Environment Setup transforms the abstract knowledge graph into a living simulation environment. Entity relationship extraction identifies the connections between different actors, objects, and concepts in the seed material. Persona generation creates detailed agent profiles with specific characteristics including MBTI personality types, demographic information, professional backgrounds, and behavioral tendencies. Agent configuration injection loads these personas into the simulation framework, preparing each agent for active participation in the social simulation.
Step 3: Simulation is where the magic happens. The system launches dual-platform parallel simulations across Twitter and Reddit environments, allowing agents to interact in familiar social media contexts. The auto-parse prediction requirements feature automatically interprets user queries and configures simulation parameters accordingly. Dynamic temporal memory updates ensure that agents remember their experiences and evolve their perspectives throughout the simulation. This creates emergent behaviors and unexpected outcomes that mirror the unpredictability of real-world social dynamics.
Step 4: Report Generation synthesizes simulation results into actionable insights. The ReportAgent, equipped with a rich toolset, performs deep interaction with the post-simulation environment to extract meaningful patterns and predictions. This agent can query specific aspects of the simulation, compare different scenarios, and identify key factors that influenced outcomes. The generated reports provide users with clear, interpretable results that can inform decision-making.
Step 5: Deep Interaction enables users to explore the simulation results in unprecedented detail. Users can chat with any agent in the simulated world to understand their perspectives, motivations, and decision-making processes. Interaction with the ReportAgent allows for follow-up questions and deeper exploration of specific prediction aspects. This interactive layer transforms static predictions into dynamic explorations, enabling users to test hypotheses and refine their understanding of potential futures.
Multi-Agent Simulation Flow
The multi-agent simulation flow in MiroFish represents a sophisticated orchestration of agent behaviors, platform interactions, and emergent social dynamics. This diagram illustrates how individual agents interact within the simulation environment to produce collective intelligence and predictive insights.
The simulation begins with agent initialization, where each simulated persona is loaded with its unique configuration. Agents are equipped with detailed profiles including MBTI personality types (such as INTJ, ESFP, etc.), age ranges, gender identities, professional backgrounds, and specific behavioral traits. These profiles influence how agents perceive information, form opinions, and interact with other agents in the simulation.
The dual-platform architecture enables simulations across both Twitter and Reddit environments simultaneously. Each platform has its own interaction patterns, content formats, and social norms that agents must navigate. Twitter simulations focus on short-form content, retweets, likes, and hashtag trends, while Reddit simulations involve longer-form discussions, upvote/downvote mechanisms, and subreddit-specific cultures. This dual approach provides a more comprehensive view of how information spreads across different social media ecosystems.
The knowledge graph memory system, powered by Zep Cloud integration, provides agents with persistent, queryable memory. Unlike traditional simulations where agents have limited or no memory, MiroFish agents can recall past interactions, track relationship evolution, and maintain consistent worldviews throughout extended simulations. This memory capability is crucial for realistic social simulation, as real humans draw on past experiences when making decisions.
The interaction engine manages agent-to-agent communications, content generation, and reaction mechanisms. Agents can create posts, comment on others’ content, share information, and form alliances or conflicts based on their personality configurations. The engine uses large language models to generate contextually appropriate responses that reflect each agent’s unique perspective.
Temporal dynamics are carefully managed throughout the simulation. The system tracks simulation time, schedules events, and ensures that agent behaviors evolve naturally over time. Dynamic memory updates occur at regular intervals, allowing agents to incorporate new experiences into their worldview and adjust their future behaviors accordingly.
The emergence layer captures collective behaviors that arise from individual agent interactions. Swarm intelligence phenomena, such as viral content propagation, opinion polarization, and consensus formation, emerge naturally from the bottom-up interactions of thousands of agents. These emergent patterns provide the predictive insights that users seek, revealing how social dynamics might unfold in real-world scenarios.
ReACT Report Generation
The ReACT (Reasoning and Acting) pattern implementation in MiroFish’s report generation system represents a sophisticated approach to automated analysis and insight extraction. This architecture enables the ReportAgent to perform complex reasoning tasks while taking concrete actions to gather information from the simulation environment.
The ReACT framework combines the strengths of reasoning-based approaches with action-oriented methodologies. At its core, the system alternates between thought processes and action execution, creating a transparent and interpretable decision-making pipeline. Each reasoning step produces a thought that guides subsequent actions, while each action yields observations that inform further reasoning.
The Thought component represents the agent’s internal reasoning process. When generating a report, the ReportAgent thinks through what information is needed, formulates hypotheses about the simulation results, and plans the most effective way to extract insights. This reasoning is made explicit in the output, allowing users to understand not just the conclusions but the logical path that led to them.
The Action component enables the agent to interact with the simulation environment through a defined toolset. Available actions include querying the knowledge graph for specific entities, retrieving agent conversation histories, analyzing interaction patterns, and extracting statistical summaries from the simulation data. Each action is purposeful and directed toward answering specific questions about the prediction.
The Observation component captures the results of each action, feeding new information back into the reasoning loop. Observations might include agent responses, network statistics, temporal trends, or content analysis results. These observations inform subsequent thoughts and actions, creating an iterative refinement process.
The toolset available to the ReportAgent includes graph traversal utilities for exploring entity relationships, text analysis tools for processing agent-generated content, statistical analysis functions for identifying patterns and outliers, and visualization generators for creating intuitive representations of simulation results. This comprehensive toolkit enables deep, multi-faceted analysis of complex social simulations.
The iterative loop continues until the agent has gathered sufficient information to address the user’s query comprehensively. Each iteration refines the understanding of the simulation results, progressively building toward actionable insights. The final output combines analytical rigor with interpretive clarity, providing users with predictions they can understand and act upon.
This ReACT-based approach offers significant advantages over traditional report generation methods. The explicit reasoning trail provides transparency and accountability, allowing users to verify the logic behind predictions. The action-oriented nature ensures that reports are grounded in actual simulation data rather than abstract speculation. The iterative refinement process produces increasingly accurate and nuanced insights as the agent explores different aspects of the simulation.
Installation and Setup
MiroFish offers two deployment options: source code deployment for maximum flexibility and Docker deployment for quick setup.
Prerequisites
| Tool | Version | Description | Check Command |
|---|---|---|---|
| Node.js | 18+ | Frontend runtime, includes npm | node -v |
| Python | 3.11-3.12 | Backend runtime | python --version |
| uv | Latest | Python package manager | uv --version |
Source Code Deployment
- Configure Environment Variables:
cp .env.example .env
Required environment variables:
# LLM API Configuration (supports any LLM API with OpenAI SDK format)
LLM_API_KEY=your_api_key
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus
# Zep Cloud Configuration
ZEP_API_KEY=your_zep_api_key
- Install Dependencies:
# One-click installation npm run setup:all - Start Services:
npm run dev
Service URLs:
- Frontend:
http://localhost:3000 - Backend API:
http://localhost:5001
Docker Deployment
# Configure environment
cp .env.example .env
# Pull and start
docker compose up -d
Ports: 3000 (frontend) / 5001 (backend)
Key Features Deep Dive
Multi-Agent Social Simulation
MiroFish’s multi-agent simulation capability sets it apart from traditional prediction tools. By simulating thousands of agents with unique personalities, the system captures the complexity of real-world social dynamics. Agents interact on Twitter and Reddit platforms, creating realistic content propagation patterns and opinion formation processes.
Knowledge Graph Memory with Zep Cloud
The integration with Zep Cloud provides persistent, queryable memory for all agents. This knowledge graph approach enables agents to maintain consistent worldviews, recall past interactions, and make decisions informed by accumulated experience. The GraphRAG construction ensures efficient retrieval of relevant context during simulations.
Detailed Agent Personas
Each agent receives a comprehensive persona configuration including:
- MBTI personality type (e.g., INTJ, ESFP, ENFJ)
- Age and demographic information
- Gender identity
- Professional background and expertise
- Behavioral tendencies and preferences
This granular approach ensures diverse and realistic agent populations that reflect the complexity of real-world communities.
Dynamic Temporal Memory Updates
Unlike static simulations, MiroFish agents continuously update their memories based on simulation events. This temporal awareness enables realistic evolution of opinions, relationships, and behaviors over time, capturing the dynamic nature of social systems.
Docker Support
The availability of Docker deployment makes MiroFish accessible to users without extensive technical setup. The containerized approach ensures consistent environments and simplifies deployment across different platforms.
Use Cases
Public Opinion Prediction
Analyze how public sentiment might evolve around breaking news, policy announcements, or social issues. Test different communication strategies and predict potential backlash or support patterns.
Financial Market Analysis
Simulate market reactions to economic indicators, corporate announcements, or geopolitical events. Understand potential market sentiment shifts before they occur.
Creative Content Exploration
Deduce alternative endings for novels, explore character motivations, or simulate how fictional worlds might evolve under different conditions. MiroFish has been used to predict the lost ending of “Dream of the Red Chamber” based on the first 80 chapters.
Policy Testing
Evaluate potential public reactions to proposed policies before implementation. Identify unintended consequences and optimize communication strategies for maximum public acceptance.
Crisis Management
Simulate information spread during crisis situations. Test response strategies and predict how different stakeholder groups might react to various communication approaches.
Conclusion
MiroFish represents a paradigm shift in prediction technology, combining swarm intelligence, multi-agent simulation, and knowledge graph memory to create a powerful platform for exploring possible futures. With over 51,667 GitHub stars, the project has demonstrated significant community interest and validation.
The 5-step workflow, from graph building through deep interaction, provides a structured yet flexible approach to prediction that can accommodate diverse use cases. The ReACT-powered report generation ensures that insights are grounded in simulation data and transparently derived.
Whether you’re a decision-maker seeking to test policies at zero risk, a financial analyst exploring market dynamics, or a creative individual curious about alternative scenarios, MiroFish offers the tools to rehearse the future before it happens. The open-source nature of the project, combined with Docker deployment support, makes it accessible to researchers, developers, and organizations worldwide.
As swarm intelligence and multi-agent systems continue to evolve, MiroFish stands at the forefront of practical applications that transform theoretical concepts into actionable predictions. The project’s vision of creating a swarm intelligence mirror that maps reality is becoming increasingly realized, enabling users to predict anything from serious policy outcomes to playful creative explorations.
For those interested in exploring the future of prediction technology, MiroFish provides both a powerful platform and an active community for collaboration and innovation. Visit the GitHub repository to get started, or try the live demo to experience the power of swarm intelligence firsthand.
