What is MiroFish?
MiroFish, incubated by Shanda Group, takes seed material such as a news report, policy draft or novel, builds a knowledge graph from it, generates agent personas for the people and groups it finds, and runs them on simulated Twitter-like and Reddit-like platforms at the same time. A ReportAgent then reads the simulated world and writes a prediction report, and you can chat with any agent afterwards or inject new variables mid-run.
The simulation itself is OASIS from CAMEL-AI, which the README credits; MiroFish adds the pipeline, a Vue web app, Zep Cloud for agent memory and the report step. It needs an OpenAI-compatible LLM endpoint (the README recommends Alibaba's qwen-plus) and a Zep Cloud key, and runs from source or Docker Compose.
The repository was created on 26 November 2025, is AGPL-3.0, and has about 83,700 GitHub stars and 12,700 forks. The last tagged release is v0.1.2 (7 March 2026); a batch of reliability fixes landed in July 2026.
Is MiroFish worth it?
MiroFish is a well-packaged scenario simulator, not a forecaster, and the distinction decides whether it is worth your tokens. Upload a policy draft or a news report, describe what you want to know, and it builds personas for the people and groups in the text, lets them post, reply, follow and argue on two simulated platforms, then hands the result to a ReportAgent. The output reads like a forecast. As of this check the project publishes no accuracy benchmark or backtest, and the financial and political examples in the README are still marked as coming soon.
Most of the hard part is borrowed. The agent society is OASIS from CAMEL-AI, a peer-reviewed simulator built for up to one million agents and 23 actions; MiroFish's own config exposes 6 actions on the Twitter-like platform and 13 on the Reddit-like one. What MiroFish adds is the glue: seed extraction into a graph, persona generation, the web app, the report agent and the ability to interview agents after a run. That glue is the reason it has about 83,700 stars, and also the reason a team that only needs the simulation can go straight to OASIS.
Cost is the thing to plan for. Every agent action is an LLM call, so spend grows with agents times rounds; the README warns that consumption is high and suggests starting below 40 rounds, and the default is 10. Per-run token counts are not published. Memory goes through Zep Cloud, whose free tier gives 10,000 credits a month with variable rate limits; past that, Flex costs $125 a month for 50,000 credits.
The catch: the hosted dependencies and the licence both bite in serious settings. Uploaded documents and every persona's memory leave your network for your LLM provider and Zep, which rules out confidential material unless you switch to the MiroFish-Offline fork, built on Neo4j and Ollama. AGPL-3.0 means a hosted product built on modified code must offer its source to users. The web app has no login in the documented setup and the Flask secret key falls back to a fixed default, so it should stay on localhost. Releases stopped at v0.1.2 in March, with about 228 open issues and pull requests. And LLM agents tend to follow the crowd more than people do, which flatters herd effects.
Our take: treat a MiroFish run like a tabletop war game. It is good at surfacing reactions and arguments you had not thought of, and poor evidence for what will actually happen. Next to TradingAgents, which at least lets you backtest its calls, it asks for more faith.
Where it earns its place
A communications lead at a mid-sized consumer brand
See how a product-recall statement might play on social media before it goes out
Upload the draft statement and recent coverage, run a 10-round simulation, then interview the angriest personas about why. Costs are LLM tokens plus Zep's free tier; the value is a list of objections to answer, not a sentiment forecast.
A graduate student in computational social science
Run quick polarisation experiments without wiring OASIS up by hand
Seed MiroFish with a policy text, change one variable mid-run from the God's-eye view, and compare the two runs' reports. For publishable work, move to OASIS directly and control the agent prompts.
A novelist or game writer
Explore how a cast of characters might react to a plot twist
The README's own demo continues Dream of the Red Chamber from its first 80 chapters. Upload your manuscript, inject the twist and chat with characters afterwards; long manuscripts mean more graph extraction calls.
Before you commit
- Setup
- Copy .env.example to .env, add LLM_API_KEY, LLM_BASE_URL, LLM_MODEL_NAME and ZEP_API_KEY, then npm run setup:all and npm run dev (Node 18+, Python 3.11 to 3.12, uv), or docker compose up -d. The app serves on ports 3000 and 5001.
- Integrations
- Any OpenAI-compatible LLM API, with an optional second faster model; Zep Cloud for graph memory; OASIS and CAMEL for the simulation. Uploads accept PDF, Markdown and text files up to 50MB.
- Data and privacy
- Self-hosted app, but seed documents, persona memory and prompts go to your LLM provider and Zep Cloud. Simulation data is stored under backend/uploads. AGPL-3.0; the MiroFish-Offline fork swaps Zep and cloud LLMs for Neo4j and Ollama.
- Cost at scale
- No paid edition. LLM cost scales with agents times rounds and per-run token counts are not published; Zep's free tier is 10,000 credits a month, Flex $125/month for 50,000 credits.
- Limits
- No published accuracy benchmark; about 228 open issues and pull requests; no tagged release since v0.1.2 in March 2026; LLM agents over-herd relative to people; no built-in authentication.
What’s good
- Document-to-simulation pipeline with a web UI and no code to write
- Built on OASIS, a peer-reviewed social simulator
- Interview individual agents and the ReportAgent after a run
- Any OpenAI-compatible LLM endpoint; English and Chinese UI
What’s not
- No published accuracy benchmark or backtest
- Token spend grows with agents times rounds; no per-run figures
- Needs Zep Cloud, so documents and memory leave your network
- No login on the web app; last release March 2026
Best for
Comms, policy and research teams who want to stress-test how a public might react to a draft, and who will read the output as a scenario rather than a forecast.
MiroFish alternatives
MiroFish: common questions
- Is MiroFish worth it?
- MiroFish is the easiest way to watch a crowd of LLM personas react to a document, but nothing yet shows its predictions beat a thoughtful analyst. We rate it 3.6 out of 5.
- How much does MiroFish cost?
- Free and open source (AGPL-3.0). You pay for LLM tokens and for Zep Cloud memory beyond its free 10,000 credits a month; Zep Flex is $125/month.
- What are the downsides of MiroFish?
- No published accuracy benchmark or backtest; token spend grows with agents times rounds; no per-run figures; needs Zep Cloud, so documents and memory leave your network; no login on the web app; last release March 2026.
- Who is MiroFish best for?
- Comms, policy and research teams who want to stress-test how a public might react to a draft, and who will read the output as a scenario rather than a forecast.
- How much does MiroFish cost for a team or in production?
- No paid edition. LLM cost scales with agents times rounds and per-run token counts are not published; Zep's free tier is 10,000 credits a month, Flex $125/month for 50,000 credits.
- Is MiroFish safe for company data?
- Self-hosted app, but seed documents, persona memory and prompts go to your LLM provider and Zep Cloud. Simulation data is stored under backend/uploads. AGPL-3.0; the MiroFish-Offline fork swaps Zep and cloud LLMs for Neo4j and Ollama.
- What are the best MiroFish alternatives?
- The closest alternatives we have reviewed are TradingAgents and DeerFlow.
Answers checked Nov 3, 2026.