MiroFish: Complete Guide to the Open-Source AI Swarm Intelligence and Prediction Engine

Explore MiroFish, the open-source multi-agent simulation engine: how its agent society, OASIS, Zep memory and ReportAgent work, plus installation, use cases, risks and official links.

## MiroFish: an open-source multi-agent simulation engine MiroFish is a web-based AI simulation and scenario-exploration project created by the MiroFish team. It converts documents and other real-world seed information into an interactive artificial society populated by AI-driven agents. Instead of giving one chatbot a question and receiving one answer, MiroFish builds a graph of entities and relationships, creates agent personas with memory and behavior, runs social interactions, and analyzes the simulated results. The project describes its ambition as a universal swarm-intelligence engine for exploring possible futures. That is a research and product vision, not proof that the software can predict real events accurately. The strongest practical use is structured exploration of assumptions, stakeholder reactions, narratives, and plausible scenarios, with independent evidence still required for decisions. ## Project profile: verified October 19, 2026 - **Project:** MiroFish - **Maintainer:** GitHub account 666ghj and the MiroFish team - **Project type:** Open-source AI agent-based social simulation and interactive reporting - **Primary stack:** Python backend, Vue 3 frontend, Flask, Vite, OASIS/CAMEL-AI, Zep Cloud and OpenAI-compatible model APIs - **License:** GNU Affero General Public License v3.0 (AGPL-3.0) - **Repository:** https://github.com/666ghj/MiroFish - **Official site:** https://mirofish.ai - **Latest listed GitHub release when checked:** v0.1.2 (March 7, 2026); the main branch contains newer changes - **GitHub popularity snapshot:** approximately 80,500 stars and 12,200 forks; these change over time - **Project support:** The README credits strategic support and incubation from Shanda Group MiroFish is not an official forecasting authority, polling company, trading platform, or a hosted general-purpose prediction API. Results depend on the uploaded evidence, the model, prompts, agent settings, simulation rounds and memory graph. ## How MiroFish works: five major stages ### 1. Build a graph from seed material A user uploads relevant documents and describes a question in natural language. The backend extracts text and identifies entities and relationships. It organizes that source material into a graph-based memory structure using Zep. This graph is the context the simulated agents and reporting tools can consult. If a source is missing, inaccurate, biased or outdated, the simulation inherits those limitations. ### 2. Prepare the environment and personas The system configures a simulated environment with entities, relationships, goals, social roles and individual agent personas. Language models contribute to ontology generation, persona descriptions and behavior setup. These artificial agents are designed to differ in traits and memory rather than all producing one identical response. ### 3. Run social interactions MiroFish uses OASIS (Open Agent Social Interaction Simulations), a CAMEL-AI project, to run multi-agent social-platform-style interactions. Depending on the configuration, simulated participants can post, respond, follow, like or otherwise react to information. The engine supports a two-platform simulation approach and evolves memory as the run progresses. The number of rounds and model calls affect both duration and cost. ### 4. Generate the prediction and analysis report ReportAgent analyzes simulation artifacts, stored graph information and available interaction results. It turns observations into a narrative report describing what happened inside the simulated environment and what scenarios emerged. A report is an interpretation of an artificial experiment, not statistical evidence that the same event will happen in the real world. ### 5. Explore and question the result The interface supports deeper interaction after a simulation, including talking to simulated agents and querying the reporting agent. This can help reveal which assumptions or relationships drive a particular scenario and can suggest what real-world evidence to gather next. ## Important capabilities - **Document-seeded scenarios:** Start from provided research, event reports, policy drafts, business material or fictional stories. - **Agent diversity:** Explore how different simulated personalities and relationships may produce differing responses. - **Longer-running memory:** Use a graph and memory layer so interactions can refer back to prior context. - **Social-network simulation:** Observe how discussions, engagement and message propagation evolve inside an artificial community. - **What-if experiments:** Adjust initial conditions or variables and compare alternative simulated trajectories. - **Interactive reports:** Review generated interpretations and ask follow-up questions about the simulated environment. - **Self-hostable code:** Inspect the Python and JavaScript source, customize the experience and deploy locally or with Docker. - **Source transparency:** Review the linked source code, release history, documented environment variables and project issues. The project's ambition to simulate thousands of agents should not be confused with a guaranteed scale for every laptop, API budget or deployment. Actual capacity depends on hardware, model and service limits. ## Technical architecture and dependencies The frontend uses Vue 3, Vue Router, Vue I18n, Axios and Vite. The backend uses Python 3.11 or 3.12, Flask, the OpenAI Python SDK, Zep Cloud, and CAMEL-AI/OASIS for social simulation. PyMuPDF supports PDF text extraction. The root project uses Node.js scripts to install and start both applications. An **OpenAI-compatible LLM API** powers major generation steps, but API compatibility by name alone is not sufficient: the selected model needs to produce suitable structured output and support the parameters and context lengths used by each stage. A separate **Zep Cloud API key** is required for graph and memory operations in the official mainline. Merely swapping LLM providers does not remove the Zep requirement. Some configurations offer an optional secondary model endpoint for faster or parallel simulation. The official source is not a fully local, dependency-free prediction engine by default. API usage, quotas, privacy policies and bills depend on the services you configure. ## Inputs and generated outputs Supported backend input formats include PDF, Markdown and plain text: .pdf, .md, .markdown and .txt. The upload ceiling in the current source is 50 MB, which is a maximum, not a recommended starting size. Text extraction from PDFs does not perform built-in OCR, so image-only scans need OCR before upload. Long documents may be sampled or truncated for some model contexts. Typical output includes a constructed simulation environment, agent interactions or timelines, graph-backed memory, a generated scenario report, and the ability to interact with agents or ReportAgent. These are simulation artifacts rather than independently verified real-world predictions. ## Installation: run MiroFish from source ### Prerequisites - Node.js 18 or newer and npm - Python 3.11 or 3.12 - The uv Python package manager - A supported model API key, base URL and model identifier - A Zep Cloud API key - Enough compute, network access and provider quota for multiple AI calls ### Step 1: Clone and configure ~~~bash git clone https://github.com/666ghj/MiroFish.git cd MiroFish cp .env.example .env ~~~ Edit the root .env file locally. Fill in your own credentials and supported model endpoint; never paste real keys into a public repository, issue or screenshot. ~~~env LLM_API_KEY=your_model_api_key LLM_BASE_URL=https://your-provider.example/v1 LLM_MODEL_NAME=your-supported-model ZEP_API_KEY=your_zep_cloud_key ~~~ The model URL above is a placeholder, not a working provider address. Follow the official README and your selected provider's documentation for the correct endpoint. Optional boost-model settings should be omitted completely unless you configure that feature. ### Step 2: Install dependencies and run ~~~bash npm run setup:all npm run dev ~~~ The frontend normally opens at http://localhost:3000 and the backend listens on http://localhost:5001. For troubleshooting, the backend health endpoint is http://localhost:5001/health. A 404 at the backend root alone is not necessarily an error, because that root URL is not the frontend. ### Alternative: Docker Compose ~~~bash cp .env.example .env # Fill in the required API credentials in .env docker compose up -d docker compose logs -f mirofish ~~~ The supplied Compose file maps ports 3000 and 5001 and mounts an upload-data directory. When deploying remotely, configure the browser-facing API URL and a reverse proxy correctly; localhost in a visitor's browser is not the remote server. Record the deployed container tag or digest, because the latest release and latest development branch are not necessarily identical. ## Suggested first simulation Choose one narrow question, such as how a fictional product change might influence different customer groups. Create a short source document with the participants, known facts, timeline and assumptions. Start with a small number of rounds; the README warns about high usage and recommends trying fewer than 40 rounds first. Run the graph and environment stages, inspect the simulation, generate a report and record which assumptions produced which outcomes. Then change one assumption and compare results. Repeat the run, seek contradictory evidence and evaluate the scenarios against independently observed information. This is more useful than treating the first generated report as a forecast. ## Practical use cases ### Public communication and reputation Explore possible stakeholder reactions to a proposed announcement or policy change. The resulting arguments may be useful for preparing questions, contingencies and communication plans. They should not be mistaken for representative public opinion or a measured polling result. ### Product launches and business planning Create synthetic stakeholder personas and test how different messages, product constraints or rollout conditions influence simulated discussions. Use these outputs to generate hypotheses for customer research, not as a substitute for real customer interviews, sales data or experiments. ### Research and education Use a controlled simulated society to study hypotheses about message propagation or multi-agent behavior, provided the methods and assumptions are documented. Scientific conclusions still require empirical validation, suitable baselines, reproducibility and expert review. ### Market and financial narratives Explore hypothetical responses to market news or economic events. MiroFish does not provide a validated, backtested price prediction method or reliable investment recommendations. ### Storytelling and worldbuilding Create fictional characters and circumstances, then explore how interactions may develop. MiroFish can inspire plot alternatives or role-based discussions, but it is not a guaranteed fully automated novel-writing pipeline. ## Limitations and reliability **No predictive guarantee.** A simulated consensus is not evidence of a future outcome. The system is not automatically calibrated against real population behavior and does not establish causality, confidence intervals or statistical validity. **Input quality matters.** Agents may amplify biases, omissions and false claims in source documents. A simulated character's statement is generated text, not direct testimony from an actual person. **Model and provider variability.** Different models, prompts, context windows and settings may produce different graphs, behaviors and reports. An endpoint that advertises API compatibility may still fail structured-output requirements. **Resource consumption.** Multi-agent simulations can make many model calls, consume memory-graph quota and require significant processing time. Estimate usage before running large simulations. **Document limitations.** Scanned PDFs need OCR; the software does not automatically search the open web for missing source documents. The report tools mainly work with supplied material and the project's graph rather than independently searching everything online. **Deployment security.** The default project should not be exposed as a public multi-tenant service without additional authentication, isolation, TLS, secrets management, rate limiting and security review. Keep uploaded confidential material and provider keys protected. **Demo limitations.** The README's online demonstration is a prebuilt static experience; it is not a publicly hosted service that runs arbitrary new simulations on demand. For a real run, deploy the application and configure the necessary services. ## Pricing and license The GitHub source code is openly available under **AGPL-3.0**. That is distinct from being completely free to operate: model inference and Zep Cloud usage may generate costs or hit quota limits. Consult provider pricing directly. AGPL-3.0 imposes obligations for distributing modified software and for certain network-accessible modified versions; review the license before incorporating MiroFish into a hosted commercial service. ## Frequently asked questions ### Is MiroFish an AI chatbot? No. It contains chat-like interactions but its core purpose is building and analyzing a multi-agent simulation with separate personas, graph memory and environment state. ### Does MiroFish accurately predict elections, markets or policy outcomes? No accuracy guarantee is established by the repository. Treat outputs as exploratory scenarios, and verify important decisions against independent research, data and domain expertise. ### Can I run it without Zep Cloud? Not with the official default integration verified here. The configuration requires a Zep Cloud key; alternative backends proposed by community members are not automatically part of the supported mainline. ### Does it work fully offline? Not by default. The documented deployment requires configured model and graph services; internet connectivity and their terms or quotas may apply. ### Is the live demo an unrestricted free prediction service? No. The official demo linked from the README is static and demonstrates prepared scenarios. It does not provide arbitrary live runs. ### Can I deploy it on a production website? You can develop a secured deployment, but the default setup is not a complete production-ready multi-user service. Review licensing, operating costs, authentication, tenant separation and security first. ## Official resources and verification - [Source code and project README](https://github.com/666ghj/MiroFish) - [Official project website](https://mirofish.ai) - [Official static showcase](https://666ghj.github.io/mirofish-demo/) - [GitHub releases and version history](https://github.com/666ghj/MiroFish/releases) - [Maintainer-community technical FAQ and implementation caveats](https://github.com/666ghj/MiroFish/issues/726) - [OASIS social simulation engine](https://github.com/camel-ai/oasis) - [AGPL-3.0 license text](https://github.com/666ghj/MiroFish/blob/main/LICENSE) **Editorial note:** This independently written profile is based on the public repository, current configuration, documented README, package manifests and the detailed GitHub technical FAQ, checked October 19, 2026. Project metrics, dependencies and deployment behavior can change. The article is not affiliated with or endorsed by the MiroFish maintainers.