MiroFish: Open-Source Swarm Prediction Engine

MiroFish is an open-source engine that predicts what will happen next by building a small synthetic society and letting it run. You hand it seed material, a news story, a policy draft, a financial signal, a novel, and it extracts the entities, generates personas, wires up their relationships, then turns thousands of LLM-driven agents loose to interact until a pattern falls out. The output is a report on where things drift, not a number with a confidence interval.

The repo, 666ghj/MiroFish, went up on November 26, 2025 and passed 70,800 stars by August 10, 2026, which is roughly 275 a day sustained across eight months. It's Python, AGPL-3.0, and it has strategic backing and incubation from Shanda Group rather than being a weekend project that got lucky on trending.

Key Takeaways:

• It simulates rather than forecasts. There's no trained predictive model here; the prediction comes out of agent behaviour in a generated environment.
• The simulation core is OASIS from CAMEL-AI, not something MiroFish wrote from scratch. Worth knowing before you attribute the whole stack to one team.
• Two API keys are required to run anything: an OpenAI-compatible LLM endpoint and a Zep Cloud key for agent memory.
• The README tells you to keep your first runs under 40 rounds because token consumption is heavy. That warning is in the quick-start, not buried in an issue thread.
• AGPL-3.0 is the constraint that matters commercially. Offering a modified MiroFish over a network triggers the source-disclosure obligation, which is exactly the case most SaaS teams are in.

What MiroFish actually is

Call it a rehearsal room. The pitch on the repo is "predicting anything," and the mechanism behind that phrase is worth being precise about, because it isn't statistical forecasting in any sense a quant would recognise.

A prediction run starts with seed material you upload plus a plain-language description of what you want to know. From there MiroFish extracts entities and their relationships, builds a knowledge graph over them, generates personas with their own histories and behavioural logic, and populates a simulated environment. The agents then interact over many rounds. Their collective behaviour, arguments spreading, opinions hardening, someone changing their mind, is the signal. A ReportAgent reads the finished world and writes up what happened.

You can also intervene mid-run. The docs describe injecting variables from a "God's-eye view," which in practice means changing a condition partway through and watching how the population responds. After the run you can talk to any individual agent in the simulated world and ask why it did what it did.

Two demos are published rather than described. One simulates public opinion around a Wuhan University incident, seeded from a report generated by BettaFish. The other feeds the first 80 chapters of Dream of the Red Chamber into the engine and lets it deduce the lost ending, several hundred thousand words of input producing a fictional-but-coherent continuation. That second one tells you more about the tool's real nature than the marketing does: it's a narrative engine that happens to be pointed at reality.

There's a hosted demo if you want to see the interface before installing anything.

How a prediction run works, end to end

The pipeline has five stages, and the README names them plainly.

Graph building pulls seeds apart and injects both individual and collective memory, constructing a GraphRAG index over the result. Environment setup extracts entity relationships, generates the personas, and pushes agent configuration into the world. Simulation runs dual-platform in parallel, parses your prediction requirement automatically, and updates temporal memory as rounds progress. Report generation hands a toolset to the ReportAgent so it can interrogate the finished environment instead of just summarising a log. Deep interaction is where you chat with individual agents or with the report writer.

The multi-agent prediction step is where the token bill lives. Every round is many agents each producing text, and the count compounds; a 40-round ceiling on your first attempt exists because someone burned money learning that lesson already.

Memory is not homegrown either. Agent memory runs through Zep, a hosted service with a free monthly tier that the README says covers light use. If you're planning to run this offline or inside a locked-down network, that dependency is the first thing to check, and it's the kind of detail that separates a demo from a deployment. Persistent memory across turns is what makes the residents behave like people rather than like a chat log, a distinction we've written about in agent memory versus chat history.

What it can predict, and what it can't

The honest answer: it produces plausible narratives about how a group of people might react to something, and its usefulness depends entirely on whether that's what you needed.

Where the shape of the tool fits the shape of the question, public opinion movement, how a message might land with different constituencies, which faction hardens and which fragments, the simulation gives you something a single LLM prompt doesn't. You get disagreement, second-order effects, and a population rather than one model's averaged opinion. The repo's own topic tags point squarely at this: public opinion analysis, social prediction, multi-agent simulation.

Where it doesn't fit is anything requiring calibrated probability. The tags also list financial forecasting, and the README teases financial and political prediction examples as "coming soon." Read that carefully. As of August 2026 there is no published accuracy benchmark, no backtest, and no leaderboard for MiroFish. No hit rate, no baseline comparison, nothing. That absence isn't a criticism of the project, which is upfront that it's a simulation engine, but it does mean any claim that it predicts markets is a claim nobody has evidence for yet, including the maintainers.

So treat the output as a structured way to think through scenarios, closer to a war game than to a model. The failure mode to watch for is the one every simulation shares: the personas came from an LLM's priors about how people behave, so the simulation can only surprise you within the bounds of what the model already believes. Feed it a population it has no good priors for and you'll get confident nonsense, delivered in the same format as the good runs.

The AGPL-3.0 question, if you're a company

MiroFish is licensed under AGPL-3.0, and that's a genuinely different proposition from the MIT and Apache licences most of the repos in this space carry.

Standard GPL obligations trigger on distribution. AGPL adds section 13, which extends the same obligation to network use: if users interact with a modified version over a network, you have to offer them the corresponding source of your modified version. Running it internally for your own team is fine. Wrapping it in a product and letting customers hit it through a browser is the case the licence was written for, and it means your modifications go out with it.

"Open source, free to use commercially" is a sentence you'll see repeated about this repo. It's true and it's incomplete. Free to use, yes. Free to build a closed hosted product on, no, not without either publishing your changes or negotiating separately with the copyright holder. Given Shanda's involvement, a commercial licence conversation is at least a plausible route, though nothing public documents one.

Ask your legal team before the pilot, not after.

Running it: what the setup actually costs

Two install paths exist. Source deployment wants Node 18 or newer, Python between 3.11 and 3.12, and uv; npm run setup:all handles root, frontend and backend dependencies in one shot, then npm run dev brings up the frontend on port 3000 and the backend on 5001. Docker Compose is the other route and reads the same .env.

The configuration is where the real requirements surface. LLM_API_KEY and LLM_BASE_URL accept any OpenAI-SDK-compatible endpoint; the README recommends Qwen-plus through Alibaba's Bailian platform, which tells you something about where this project's centre of gravity sits. ZEP_API_KEY is the memory dependency.

Then the line that deserves more attention than it gets: high consumption, try simulations with fewer than 40 rounds first. Thousands of agents, each generating text every round, is a lot of inference. Nobody publishes a per-run cost figure, so budget by starting small and measuring your own bill rather than trusting an estimate.

One more thing worth flagging for anyone tracking version signals. The last tagged release is v0.1.2 from March 7, 2026, while commits landed as recently as August 3. Development is active; the release cadence just isn't. If your procurement process cares about tagged versions, that gap is a conversation you'll need to have.

A swarm of simulated agents versus agents that do the work

There's a useful distinction hiding in this project, and it applies well beyond MiroFish.

Simulation agents exist to model behaviour. They're synthetic on purpose; nothing they do touches a real system, and the whole value is that you can run the scenario a hundred times and throw away ninety-nine. Working agents are the opposite. They read your actual inbox, open your actual repo, and their output is a change in the world that you have to live with. Multi-agent coordination shows up in both worlds, and we've covered the working-agent side of it in running agents as a group and in the difference between generative AI, AI agents and agentic AI.

Teams sometimes reach for a simulation framework when what they wanted was the second kind. If the goal is "understand how a decision might play out," MiroFish is aimed at exactly that. If the goal is "have something monitor this and act while I'm asleep," a simulation of a town won't do it, and no amount of agent count fixes the mismatch.

FAQ

How much does MiroFish cost?

The software costs nothing; running it does. There is no licence fee, but a run needs an LLM endpoint and a Zep Cloud key, and the quick-start warns that consumption is heavy enough to cap your first attempts at 40 rounds. Nobody publishes a per-run figure, so measure a small run before budgeting. Commercially, AGPL-3.0 is the real cost: modify it and let users reach it over a network and you owe them your modified source. Internal use doesn't trigger that; a customer-facing hosted product does.

What is a MiroFish?

A swarm intelligence engine: software that produces a result from many simple agents interacting rather than from one model reasoning alone. The behaviour you care about emerges from the interactions, which is why the count matters and why no individual agent in the run holds the answer. MiroFish applies the idea to prediction by generating a population, giving each member a persona and memory, and reading the outcome off their collective behaviour.

Who created MiroFish?

The repo sits under the GitHub account 666ghj, and the README states the project has received strategic support and incubation from Shanda Group, with recruiting handled through a shanda.com address. The simulation core comes from CAMEL-AI's OASIS project, credited in the README.

How accurate are MiroFish's predictions?

Unknown, publicly. As of August 2026 no benchmark, backtest or accuracy figure has been published for it. The demos show plausible narrative output on public opinion and on a literary reconstruction, neither of which has a ground truth you can score against. Anyone quoting an accuracy number for this tool is quoting something that doesn't exist.

How can I use MiroFish?

Two install paths: source deployment (Node 18+, Python 3.11–3.12, uv, then npm run setup:all and npm run dev) or Docker Compose, with the frontend on port 3000 and the backend on 5001. Either way you configure two keys first: an LLM endpoint (any OpenAI-compatible API; the README recommends Qwen-plus via Alibaba Bailian) and Zep Cloud for agent memory. Neither has a documented offline substitute, so a fully air-gapped deployment would need work. There is also a hosted demo if you only want to look.