MiroFish: A Multi-Agent Simulation Engine That Predicts by Building Parallel Worlds
MiroFish is a swarm-intelligence engine that builds a parallel digital world from seed materials, letting thousands of interacting agents simulate future trajectories.
At a glance
- What is it?
- MiroFish is an AGPL-3.0 Python and Node.js engine that turns seed documents into a simulated society of agents, then answers prediction questions by running that society forward. It is a bold idea with real complexity and notable operational costs.
- Who is it for?
- Adopt MiroFish if you need to explore speculative scenarios with a narrative bent, such as predicting public opinion trends or novel endings, and you have the budget and patience for LLM API costs and multi-service setup. Do not adopt it for high-stakes financial or policy forecasting where accuracy is critical, because the simulation is qualitative, not statistical.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 13 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What MiroFish Actually Predicts and Who It Serves
MiroFish is a prediction engine built on multi-agent simulation. It takes seed information from the real world, such as news, policy drafts, or financial signals, and constructs a parallel digital world. Inside that world, thousands of agents with independent personalities, long-term memory, and behavioral logic interact. The user injects variables from a God's-eye view, and the simulation runs forward to produce a prediction report. The README's examples are telling: a public opinion simulation for Wuhan University and a prediction of the lost ending of Dream of the Red Chamber based on the first 80 chapters. This is not a quantitative forecasting tool. It is a narrative engine for exploring what-if scenarios. The intended audience is decision-makers who want to rehearse policies or public relations at zero risk, and individual users who want to play with speculative fiction. The dual audience is explicit in the vision section, which describes a rehearsal laboratory at the macro level and a creative sandbox at the micro level.
The Mechanism: From Seed to Simulation to Report
The workflow has five stages, and the README describes them in order. First, graph building: the engine extracts seeds from the input, injects individual and collective memory, and constructs a GraphRAG. Second, environment setup: it extracts entity relationships, generates personas, and injects agent configurations. Third, simulation: it runs a dual-platform parallel simulation, auto-parses the prediction requirement, and updates temporal memory dynamically. Fourth, report generation: a ReportAgent with a rich toolset interacts deeply with the post-simulation environment. Fifth, deep interaction: the user can chat with any agent in the simulated world or with the ReportAgent. The key architectural detail is that the simulation engine is powered by OASIS, an open-source project from the CAMEL-AI team. That is a concrete dependency, not a vague inspiration. The dual-platform parallel simulation suggests the engine runs two separate simulations concurrently, though the README does not explain why. The GraphRAG construction implies a knowledge graph over the seed material, which is how the agents get their initial context.
Getting It Running: Commands, Config, and the Python Version Trap
The README offers two deployment paths. The source code path requires Node.js 18 or later, Python 3.11 to 3.12, and the uv package manager. The setup begins by copying .env.example to .env and filling in three required keys: LLM_API_KEY, LLM_BASE_URL, and LLM_MODEL_NAME, plus ZEP_API_KEY for Zep Cloud. The LLM API must follow the OpenAI SDK format, and the README recommends Alibaba's Qwen-plus model via the Bailian platform. The install commands are npm run setup:all for everything, or npm run setup for Node dependencies and npm run setup:backend for Python. Starting the services is npm run dev, which launches both frontend and backend. Frontend runs on port 3000, backend on 5001. The Docker option is simpler: copy .env, then run docker compose up -d. The README warns that LLM consumption is high and suggests trying simulations with fewer than 40 rounds first. That warning is a practical constraint that any adopter should take seriously.
The Cost Problem: LLM APIs and Zep Cloud as Hidden Dependencies
MiroFish is not a self-contained engine. It depends on two external services: an LLM API and Zep Cloud for memory. The README notes that Zep Cloud has a free monthly quota sufficient for simple usage, but that is a quota, not a guarantee. The LLM API is the bigger issue. The README explicitly says high consumption and recommends fewer than 40 rounds. That is a direct admission that running a full simulation with thousands of agents will burn tokens quickly. The cost is not just monetary. Each round of simulation involves API calls, and the temporal memory updates mean the state grows over time. If you are evaluating MiroFish for a production use case, you need to budget for API spend, not just server costs. The README does not provide any cost estimates, so you must test with a small scenario first. This is a genuine limitation: the tool is free to install, but expensive to run at scale.
A Real Alternative: OASIS, the Underlying Simulation Engine
The README credits OASIS (Open Agent Social Interaction Simulations) from the CAMEL-AI team as the simulation engine. That is a direct pointer to an alternative. If you only need the agent simulation layer, you could use OASIS directly and build your own prediction pipeline on top. The difference is in scope. OASIS is a framework for social interaction simulations; it does not come with the graph building, report generation, or deep interaction features that MiroFish adds. MiroFish wraps OASIS with a frontend, a report agent, and a specific workflow. If you want a general-purpose agent simulation toolkit, OASIS gives you more control and fewer opinionated choices. If you want a turnkey prediction product, MiroFish is the integrated option. The trade-off is that MiroFish's added layers are exactly where the LLM cost and complexity come from. Using OASIS directly means you write your own graph construction and report generation, but you also avoid the Zep Cloud dependency if you choose a different memory store.
Licence and Maintenance: AGPL-3.0 with an Incubator Behind It
MiroFish is licensed under AGPL-3.0. That has implications for anyone who wants to modify and deploy it as a service: you may need to release your modifications under the same licence. This is not legal advice, but the AGPL is known for its network copyleft clause. The README also states that MiroFish received strategic support and incubation from Shanda Group, and the team is recruiting. That suggests active development, and the last push date of March 2026 with a release from the same day confirms ongoing work. The maintenance cost is moderate: you are dependent on the OASIS project for the simulation engine, and on Zep Cloud for memory, so you need to track updates in both. The README does not mention a migration path or upgrade notes, so expect breaking changes in early versions. The version numbers are all 0.1.x, which means the API is not stable. Adopters should pin versions and test upgrades carefully.
Where MiroFish Fails: When You Need Numbers, Not Stories
MiroFish is the wrong tool when you need statistical confidence. The output is a detailed prediction report, not a probability distribution. The README never mentions confidence intervals, calibration, or backtesting. The examples are qualitative: a public opinion trend, a novel ending. If you are a financial analyst who needs a point forecast with error bars, this engine will not give you that. The simulation is also non-deterministic. The README mentions dual-platform parallel simulation, but it does not say how to reconcile divergent outcomes. The agents have independent personalities and behavioral logic, which means the same seed material can produce different worlds. That is a feature for creative exploration, but a bug for reproducibility. The README's own warning about high consumption suggests that running enough rounds for statistical stability is prohibitively expensive. So the honest use case is exploration, not prediction in the actuarial sense.
Editorial conclusion
Adopt MiroFish if you need to explore speculative scenarios with a narrative bent, such as predicting public opinion trends or novel endings, and you have the budget and patience for LLM API costs and multi-service setup. Do not adopt it for high-stakes financial or policy forecasting where accuracy is critical, because the simulation is qualitative, not statistical. Before committing, verify that your LLM API key works with the OpenAI-compatible endpoint, that Zep Cloud is reachable, and that your Python version is between 3.11 and 3.12, as the README explicitly warns about high consumption and suggests testing with fewer than 40 rounds.
Community notes