666ghj/MiroFish

MiroFish is a self-hostable, LLM-driven simulation engine for constructing a parallel "digital world" from seed documents and running many agents through it. You supply source material (for example a news report, policy draft, financial signal, or novel) plus a natural-language prediction request; the system builds a knowledge graph, creates agent personas, runs the simulation, and returns a prediction report alongside an interactive world you can query.

How it works

The pipeline has four documented stages: seed extraction and GraphRAG construction; entity-relationship extraction and agent persona/configuration generation; a dual-platform parallel simulation with dynamic memory updates; and a ReportAgent that uses tools to interrogate the post-simulation environment. You can also chat with individual simulated agents or the ReportAgent afterward. The simulation engine is built on OASIS from the CAMEL-AI project, which is worth knowing if you already work with that ecosystem (README).

The two mechanisms that shape the experience are long-term agent memory (backed by Zep Cloud) and the "God's-eye view" variable injection, which lets you change conditions mid-run rather than only observing a fixed scenario. The README frames the fit broadly, from policy/PR rehearsal to creative exploration such as deducing a fictional ending; a prepared public-opinion demo and an online demo environment show the intended interface (live demo).

Requirements and cost to run

Both deployment paths require LLM API credentials and a Zep Cloud key. Any OpenAI-SDK-compatible LLM endpoint works; the README recommends Qwen-plus via Alibaba Cloud Bailian and explicitly warns that consumption is high, suggesting trial runs under 40 rounds (README, Bailian console, Zep).

Source deployment additionally requires Node.js 18+, Python 3.11–3.12, and the uv package manager; setup scripts install root, frontend, and backend dependencies, and the services run on ports 3000 and 5001. Docker deployment uses the same .env configuration and exposes the same ports (README).

Scope and caveats

The README does not publish accuracy benchmarks, validation datasets, or a formal evaluation of prediction quality; its claims are framed as a vision and workflow, not measured outcomes. "Predicting anything" should therefore be read as the project's ambition rather than a validated capability. Token consumption and the dependence on an external memory service are practical constraints, and simulation quality will track the seed material and chosen LLM. The project is licensed AGPL-3.0, which matters if you plan to modify it and offer it as a network service. The repository is young (created November 2025) and its star count reflects attention, not verified prediction reliability (repository).