MiroFish is an open-source swarm intelligence prediction engine that takes material such as news, policy drafts, financial signals, or novels along with a prediction question, then builds and simulates a digital parallel world where AI agents with distinct personalities and memories interact. The GitHub project was released in November 2025, and as of September 30, 2026 it had about 75,000 stars and is distributed under the AGPL-3.0 license.
In the README's words, the idea is to "rehearse the future in a digital sandbox and win decisions after countless simulations." MiroFish aims to take seed material and a natural-language request and build not just a report but an environment where you can talk inside the resulting world.
What MiroFish is: a digital parallel world from a single piece of seed material
The user uploads seed material, such as an analysis report or a novel, and writes in natural language what to predict. MiroFish extracts people, institutions, relationships, and memories from the material to build an agent world. Each agent is set up with its own personality, long-term memory, and behavioral logic, and the results of their interactions in the environment are compiled into a prediction report.
Users do not stop at reading the results; from a "god's-eye view" they can change conditions and variables and look at how the world flows again. The project's home page says that if you upload a report it immediately infers the future, and it promotes that even a paragraph of text can create a parallel world of up to a million agents. Upload formats are PDF, MD, and TXT. The screen lists the average cost of one standard simulation as about $5.
From decision rehearsal to novel endings
The macro use MiroFish proposes is a rehearsal lab for decision makers, testing several scenarios before actually carrying out a policy or PR strategy. On the micro side, it aims to be a personal creative sandbox for inferring a novel's lost ending or trying out imagined conditions.
MiroFish's goal is to let you see the result of every "what if," from serious forecasting to light simulations, so you can predict anything.
Demos: Wuhan University public opinion and the lost ending of Dream of the Red Chamber
In the MiroFish live demo, you can follow the graph construction, environment setup, and simulation screens for the Wuhan University case. It is a pre-configured static demo, and the deep conversation with agents is not connected to a real LLM. The demo also provides the input material, a PDF analyzing Wuhan University's brand reputation.
The first video shows the process of putting a Wuhan University public opinion report, made by the same developer's opinion analysis project BettaFish, into MiroFish and simulating it. The Wuhan University public opinion simulation intro video (Bilibili, 17 min) was posted on December 22, 2025 (Korea time).
The second case is an experiment that infers the lost ending based on the first 80 chapters of Dream of the Red Chamber, the classic Chinese novel. The Dream of the Red Chamber lost ending simulation (Bilibili, 14 min) was posted on January 20, 2026 (Korea time).
The README says it will go on to introduce financial forecasting and political news forecasting cases as well.
How it works: 5 steps from seed material to report
- Graph construction. It extracts information from the material and adds individual and group memory to build a GraphRAG knowledge graph. In the code, it builds the graph, entities, relationships, and episodic memory in Zep Cloud.
- Environment setup. Based on entities and relationships, it builds the simulation's ontology and generates each entity's persona, OASIS agent profile, and world settings.
- Simulation. It reflects the natural-language prediction request in the settings and rounds, and updates agents' activity and memory over time. "Dual-platform parallel simulation" is a structure that sets up Twitter-style and Reddit-style OASIS environments and runs them together.
- Report generation. ReportAgent examines the simulation results with search, insight analysis, and agent interview tools and writes the report.
- Deep interaction. You talk with individual agents in the resulting world or with ReportAgent to explore the flow described in the report further.
The example settings screen shows 39 agents, 120 hours of simulation, 60 minutes per round, and 120 rounds in total.
How to install MiroFish: source code and Docker
A source install requires Node.js 18 or later with npm, Python 3.11 to 3.12, the latest uv package manager, an LLM API key, and a Zep Cloud API key. First, copy the example environment file.
cp .env.example .envPut your LLM and Zep Cloud settings in .env. The README example uses Qwen-plus from Alibaba Bailian.
# 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_keyInstall all dependencies and start the dev server.
npm run setup:all
npm run devYou can split the install into steps with npm run setup (Node.js dependencies) and npm run setup:backend (Python backend dependencies). Run the frontend and backend with npm run frontend and npm run backend, respectively. The default addresses are http://localhost:3000 for the frontend and http://localhost:5001 for the backend API.
To use Docker, create the same environment file and then bring up Compose.
cp .env.example .env
docker compose up -dCost and the API keys to prepare
The MiroFish README says you can use any LLM API compatible with the OpenAI SDK format. The recommended model is Qwen-plus from Alibaba Bailian. Model calls and agent interactions can use a lot of tokens, so the README recommends running under 40 rounds at first. It explains that the Zep Cloud free monthly allowance may be enough for simple use.
The home page shows the average cost of one standard simulation as about $5. Actual spending can vary with the model, input material, number of agents, and round setup, so it is better to check with a small configuration first.
Who built it: the BettaFish developer and Shanda Group
The GitHub account 666ghj (BaiFu) is the developer who built MiroFish and BettaFish. BettaFish is a public opinion analysis project, and the input report for the Wuhan University case was also made by this project. For the simulation engine, it uses CAMEL-AI's OASIS.
The MiroFish README says it received strategic support and incubation from Shanda Group. Shanda founder Tianqiao Chen also introduced MiroFish as an incubated project. The repo was created on November 26, 2025 (Korea time), and releases run v0.1.0 (December 22, 2025), v0.1.1 (January 22, 2026), and v0.1.2 (March 7, 2026).
The license is AGPL-3.0. Even if you modify the software and offer it as a network service, source disclosure obligations under the license terms may apply, so check the full license text and its scope before commercial deployment.
Source: X @mirofish_ai
Source: X @tianqiao_chen
Source: X @whoisbaifu
Related posts
- The Harvard and MIT AI that "simulated 8.3 billion people" was really a 1-million-person coreset
- Google AX Agent Runtime: 4 Key Features That Earned 1,500 GitHub Stars in a Day
- How to install Unreal Agent: cut costs with an async agent harness
Sources: MiroFish repo and README, MiroFish home page, Live demo, BettaFish, CAMEL-AI OASIS