MiroFish: A Multi-Agent Prediction Engine You Run Yourself

What MiroFish predicts, and for whom

MiroFish takes seed material from the real world and builds a parallel digital world from it. The README lists breaking news, policy drafts, and financial signals as example seeds, and says the input can also be a novel story. From that material it generates agents with independent personalities, long-term memory, and behavioral logic, lets them interact, and returns a prediction report plus an interactive world you can inspect. The stated audience has two ends. At the macro level it is positioned as a rehearsal laboratory for decision makers who want to test policy or public relations without real-world risk. At the micro level it is a creative sandbox for individual users, with the project's own demo videos covering a public opinion simulation and a reconstruction of the lost ending of Dream of the Red Chamber. That split matters when you evaluate it: the same engine is being sold as a serious scenario tool and as an entertainment toy, and the README does not separate the accuracy expectations of the two.

The five-stage pipeline behind a MiroFish simulation

The README describes the workflow in five stages. Graph Building extracts seeds and injects individual and collective memory, then builds a GraphRAG structure. Environment Setup pulls entity relationships out of that graph, generates personas, and injects agent configuration. Simulation runs what the README calls dual-platform parallel simulation, auto-parses the prediction requirement from your natural language prompt, and updates temporal memory as the run proceeds. Report Generation hands the post-simulation environment to a ReportAgent with a toolset. Deep Interaction lets you chat with any agent in the simulated world or with the ReportAgent. The engine itself is not written from scratch: the acknowledgments state that MiroFish's simulation engine is powered by OASIS (Open Agent Social Interaction Simulations) from the CAMEL-AI team. Persistent memory is delegated to Zep Cloud, which is why ZEP_API_KEY is a required variable rather than an optional one. So the architecture is a Python backend orchestrating an external simulation framework, an external memory service, and an external LLM, with a Node frontend on top.

Installing MiroFish from source

Source deployment is the option the README recommends. You need Node.js 18 or newer, Python at least 3.11 and at most 3.12, and uv as the Python package manager. Start by copying the example environment file, then open .env and fill in the keys. The README marks LLM_API_KEY, LLM_BASE_URL, LLM_MODEL_NAME, and ZEP_API_KEY as required, and suggests qwen-plus on Alibaba's Bailian platform as the default LLM.

cp .env.example .env

After editing .env, install everything with one command. The root package.json defines setup:all as npm run setup followed by npm run setup:backend, so it installs the root and frontend Node dependencies and then syncs the backend Python environment.

npm run setup:all

Then start both services from the project root. The dev script uses concurrently to run the backend and frontend together, and the README gives the resulting URLs as http://localhost:3000 for the frontend and http://localhost:5001 for the backend API.

npm run dev

If you prefer to run them separately, npm run backend starts only the backend and npm run frontend starts only the frontend. Your first real use is to upload a seed document and describe the prediction you want in natural language, which is exactly the two-step input the README describes. The .env.example carries a warning worth repeating: consumption is high, so try a simulation with fewer than 40 rounds first.

Running MiroFish with Docker instead

The Docker path skips the toolchain requirements. You still copy and fill .env first, because docker-compose.yml passes it to the container through env_file. Then bring the stack up.

cp .env.example .env
docker compose up -d

The compose file pulls ghcr.io/666ghj/mirofish:latest, sets the container name to mirofish, maps ports 3000 and 5001, sets restart to unless-stopped, and mounts ./backend/uploads into /app/backend/uploads so uploads survive a restart. A commented alternative image at ghcr.nju.edu.cn/666ghj/mirofish:latest is offered for faster pulling. One thing to read carefully before you rely on this: the Dockerfile's final command is npm run dev, which the package.json defines as the concurrently development script. The image is therefore running the development servers, not a production build, and the Dockerfile itself labels it as development mode. That is fine for a local trial and questionable for anything exposed.

Where MiroFish breaks down

The clearest limitation is maintenance. The last push to the default branch was on 2026-03-07, and the most recent release is v0.1.2 from the same date. The repository is not archived, but more than six months have passed, so treat it as a snapshot rather than a project you can expect to receive fixes. The second limitation is dependency weight. A single simulation needs an OpenAI-compatible LLM endpoint and a Zep Cloud account, and the README warns that consumption is high and suggests staying under 40 rounds at first. There is no documented local or offline mode for the memory graph, so the mirofish offline query has no answer in this material. Third, the version pins are narrow: Python must be at least 3.11 and at most 3.12, which rules out 3.13 without changes the README does not describe. Fourth, reproducibility is weak by design. Agents with independent personalities interact freely, so two runs over the same seed will not produce the same report, and the README does not document a seed control or a rollback mechanism. If your use case requires an auditable, repeatable number, this is the wrong tool.

MiroFish versus the OASIS engine it is built on

The honest alternative is OASIS itself, the CAMEL-AI project that the acknowledgments credit as the simulation engine. The difference is one of scope and packaging. OASIS is a social interaction simulation framework: you get the agent simulation primitives and you assemble the pipeline. MiroFish wraps that engine in an opinionated five-stage workflow, adds GraphRAG construction from your seed material, adds persona generation, and adds a ReportAgent that turns the finished world into a written report. It also adds the Node frontend, so a non-programmer can upload a document and read the result in a browser. The trade-off runs the other way too. Going directly to OASIS means you control the LLM calls and the memory layer and are not bound to Zep Cloud, and you can run a lighter setup without the 3000 and 5001 service pair. Choosing MiroFish means accepting its dependency choices and its release cadence in exchange for not having to build the pipeline yourself.

Licence and the cost of staying current

MiroFish is licensed under AGPL-3.0, and both package.json and the repository metadata agree on that. The AGPL is a strong copyleft licence with a network clause: if you modify the code and let users interact with it over a network, the licence's terms reach that deployment. That is a real consideration for anyone planning to host a modified MiroFish for external users, and it is different from what a permissive licence would allow. This is not legal advice; read the LICENSE file and get your own review if you intend to offer it as a service. On upgrade cost, the picture is simple: three releases exist, v0.1.0 on 2025-12-22, v0.1.1 on 2026-01-22, and v0.1.2 on 2026-03-07, and nothing since. There is no migration guide in the repository, and no documented upgrade path between versions. The practical cost of adopting MiroFish today is not the upgrade treadmill; it is the possibility that you will be the one maintaining your fork.

Editorial conclusion

Adopt MiroFish if you want a self-hosted sandbox for narrative or opinion simulations and you already have an OpenAI-compatible LLM key and a Zep Cloud account. Do not adopt it if you need maintained software, offline operation, or a fixed output format, because the last push was on 2026-03-07 and every simulation calls external APIs. Before committing, verify that the pinned Python range 3.11 to 3.12 matches your environment and that your LLM budget covers a first run under 40 rounds.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes