MiroFish is an open-source swarm intelligence simulation engine that builds high-fidelity parallel digital worlds from real-world seed information, then populates them with thousands of autonomous AI agents to predict future outcomes. The project represents an emerging category of AI applications that goes beyond question-answering or content generation into social simulation and scenario forecasting. ## The Core Idea: A Digital Mirror of Reality Traditional AI prediction approaches rely on pattern matching in historical data. MiroFish takes a fundamentally different approach: it reconstructs a simulated version of the social or economic situation described in the input, then lets AI agents act within that simulation to generate emergent predictions. The idea draws from agent-based modeling traditions in social science, but supercharges it with modern LLMs. The engine's name combines 'Miro' (a phonetic nod to the Chinese concept of mirror or reflection) with 'Fish' referencing collective swarm behavior — thousands of individual agents forming coherent group dynamics, like fish in a school moving with apparent coordination despite each individual acting on local information. ## GraphRAG-Powered World Construction When a user provides seed information — a news article, policy draft, financial report, or social media thread — MiroFish uses GraphRAG to extract entities, relationships, and context into a knowledge graph. This graph forms the foundation of the simulated world: who the key actors are, what institutions exist, what the current state of affairs is, and what pressures or incentives are in play. The knowledge graph construction step is critical to prediction quality. Unlike naive RAG approaches that treat documents as bags of sentences, GraphRAG preserves the relational structure of information, enabling agents to reason about influence networks, supply chains, and social dynamics rather than just factual recall. ## Autonomous Agent Simulation Once the world is constructed, MiroFish instantiates thousands of independent AI agents, each assigned a personality profile, memory state, and behavioral logic drawn from the knowledge graph. An agent might represent a retail investor, a government official, a journalist, or a regional distributor — whatever actors are relevant to the prediction scenario. Each agent operates with independent decision-making, updating their beliefs and actions based on information from other agents and environmental events. Over successive simulation rounds, emergent social dynamics arise: sentiment cascades, policy feedback loops, market contagion, or narrative amplification. These emergent patterns constitute the prediction. ## Dynamic Variable Injection Users interact with the simulation from a 'God's-eye view,' able to inject external variables mid-simulation to test counterfactual scenarios. What happens if a regulatory announcement is made on day 30? What if a key executive resigns? What if a competitor launches a competing product? The system reruns the agent dynamics from the injection point, producing a forked prediction timeline. This capability transforms MiroFish from a passive prediction tool into an interactive strategic sandbox — organizations can stress-test decisions before committing to them. ## Demonstrated Use Cases The project's documentation highlights several compelling demonstrations. In public opinion modeling, feeding a university controversy report into MiroFish generates a 90-day sentiment trajectory showing opinion polarization, media amplification cycles, and eventual public memory decay. In literary scenario simulation, loading the first 80 chapters of a classical novel enables the engine to simulate alternative story branches based on character personality profiles and relationship graphs. Financial sentiment simulation is another validated use case: inputting breaking negative news and analyst reports to forecast differential reactions from retail investors, institutional funds, and financial media over a 30-day horizon. ## Technical Architecture MiroFish is built with a Python 3.11-3.12 backend handling LLM orchestration and simulation logic, paired with a Vue.js frontend for visualization and interaction. It supports any LLM accessible via the OpenAI SDK interface, with the documentation recommending Alibaba's Qwen-plus model for cost-performance balance. Zep Cloud handles long-term agent memory management, ensuring agents accumulate experience consistently across simulation rounds. Deployment is supported via Docker or direct source installation. The project is licensed under AGPL-3.0, requiring open-sourcing of derivative works but permitting commercial use. ## Current Status and Community MiroFish released version 0.1.1 in January 2026, reaching 4,200 GitHub stars within weeks of public announcement. The project originated from research into multi-agent social simulation and is actively developed by a small team based in China. Community engagement happens through a QQ group and a GitHub Discussions board, with the team actively responsive to issues and feature requests. For organizations exploring scenario planning, policy simulation, financial stress testing, or strategic war-gaming with AI, MiroFish offers an accessible entry point into agent-based simulation at a sophistication level previously reserved for dedicated simulation platforms.