MiroFish: multi-agent social simulation for exploring scenarios

Everything worth knowing about 666ghj/MiroFish: a “swarm intelligence” engine that takes real-world seed information, builds a simulated environment, and has agents with personas, memory, and rules interact to produce scenario reports.

What MiroFish is

MiroFish is an open-source project presented as a universal swarm-intelligence engine to “predict anything.” From news, policy drafts, financial signals, or other seed material, it aims to build a parallel digital world in which many agents with personality, memory, and behavioral logic interact and evolve.

The description should be read precisely: MiroFish is a simulation and scenario-generation tool, not a validated system for predicting the future. Its reports can be useful for exploring hypotheses, reactions, or risks; they aren’t causal evidence, reliable financial forecasting, or sufficient grounds for policy, medical, legal, or investment decisions.

The repository is published under the MIT license. Its README shows demo cases on public opinion, the supposed lost conclusion of Dream of the Red Chamber, and predicted financial/political scenarios, which are project demonstrations, not independent accuracy evaluations.

The origin: from a reality seed to a parallel world

The offering starts from a “reality seed”: documents, news, or contextual information that feed a knowledge and memory graph. It then extracts entities and relationships, generates personas, configures agents, and runs interactions to observe a simulated social evolution.

Dark-mode cyberpunk illustration of the "Seed to Parallel World" concept. A glowing, floating crystalline seed emits holographic beams of light that construct a neon-lit digital cityscape in the background. Neon magenta and cyan data streams flow from the seed into the ground, building the foundation of a simulated reality.

The flow the README lists has five phases: graph construction; environment configuration; simulation; report generation; and deep interaction. A third-party site analyzing the frontend components associates those phases with separate screens, but that mapping should be taken as secondary documentation and verified against the current code.

MiroFish relies on GraphRAG and a combination of individual/collective memory per the project’s own explanation. This explains why it requires context sources and models that process large volumes of text; it also implies output quality is conditioned by the input data, prompts, model, number of agents, and simulation rules.

Ultra-detailed cyberpunk visualization of a GraphRAG knowledge graph. Glowing interconnected nodes and edges float in a dark, infinite digital space. The nodes are labeled with abstract entities and relationships, pulsing with electric blue and neon green light. Swarms of tiny glowing particles navigate the complex network, representing memory retrieval and context extraction.

Philosophy and principles

Simulate, don’t claim certainty. The product generates possible dynamics from an initial reality; a plausible output doesn’t prove an event will occur.

Dark-mode cyberpunk illustration of "Simulation, not Certainty." A glowing, holographic crystal ball sits on a dark, reflective surface. Inside the ball, a chaotic but beautiful swirl of neon data streams and tiny AI agents interact, forming multiple branching paths and alternative futures. The words "Hypothesis" and "Exploration" are subtly integrated into the neon glow.

Heterogeneous agents. Personas and configurations aim to represent distinct perspectives and behaviors within the simulated environment.

Structured context. Graph and memory construction aims to prevent each agent from responding only from an isolated prompt.
Interactive exploration. After generating a report, the user can dig deeper through agents and a reporting agent.
Open source and self-run. The repository offers local deployment via Docker Compose; compute resources, keys, and data remain the operator’s responsibility.

How it works

Seed material → entity extraction / GraphRAG → environment and personas
                                              → agent interaction
                                              → scenario report
                                              → follow-up questions

The first stage ingests the source and generates the graph. The second configures entities, relationships, personas, and agents. The third runs the simulation; the fourth consolidates a report; and the fifth allows reviewing the result with additional interaction.

The repository includes backend and frontend, docker-compose.yml, CI workflows, and documentation in English and Chinese. The project’s FAQ specifies that the GitHub repository and mirofish.ai are the official channels, and that the static demo mentioned in the README is 666ghj.github.io/mirofish-demo.

Main components

Seed and graph: input information, entity and relationship extraction, GraphRAG, and memory.
Environment and personas: profile generation and interaction rules for the agents.
Simulation: rounds of social activity modeled by the configured LLM and prior information.
Report and interaction: scenario synthesis and the ability to query simulated agents or the ReportAgent.
Run persistence: the FAQ mentions run_state.json, logs, and SQLite databases for network integrations; a forced restart erases prior state.

The ecosystem

$Dark-mode cyberpunk illustration of the community ecosystem. A central, glowing neon core labeled "MiroFish" is surrounded by orbiting, smaller holographic modules representing community projects, cloud provisioning, and third-party frameworks. Glowing data streams connect the core to the orbiting elements, but some streams are fractured or red, indicating unauthorized or unaffiliated domains.$

The project receives support and strategic incubation from Shanda Group and relies on CAMEL-AI’s OASIS framework, per a secondary listing; the claim should be checked against the README and isn’t interpreted as a guarantee of maintenance or enterprise support.

There are community projects around installation. radishbuild/mirofish-cloud proposes provisioning a private instance on compute providers; it’s a third-party layer, not official project hosting.

The official FAQ specifically warns that domains like mirofish.my, mirofish.homes, and mirofish.co.in aren’t official or authorized services. That’s an important caution: no API keys, private documents, or payments should be sent to sites using the name without confirming the relationship to the repository.

Repo numbers

Measured: August 24, 2026, GitHub API. The source article for this repository didn’t include its own metrics table; these figures were verified directly against the public GitHub API at publication time.

Metric	Value
Stars	71,481
Forks	11,111
Real subscribers	439

watchers_count mirrors stars in GitHub’s general response; that’s why subscribers_count is reported as the real subscriber count.

Quick-start guide

Preparation and installation

Ultra-detailed cyberpunk illustration of an open-source deployment environment. A futuristic, dark-mode terminal interface displays glowing lines of code and a neon docker-compose.yml file. In the background, abstract representations of local servers and containerized environments glow with subtle blue and green lights, isolated within a secure, private digital vault.

The reference route is cloning the repository and reviewing the current README and docker-compose.yml. The project requires configuring an LLM provider and, on certain paths, auxiliary services for memory/graph. A community discussion shows that using a local model doesn’t necessarily remove keys required by components like Zep Cloud; it’s a user experience, not a definitive spec.

Before running a simulation, it’s worth preparing:

A bounded, attributable, up-to-date source package.
A concrete scenario question, identified actors, and an explicit time horizon.
A review criterion separating facts from hypotheses produced by the simulation.
A compute budget: more agents and more rounds increase cost, time, and thermal load.

Common workflows

Product or communications scenario: contribute user research and messaging; simulate reactions as qualitative exploration, then validate with real research.
Public opinion analysis: input dated, sourced material, define actors, and compare different seeds or assumptions.
Narrative research: use the environment to develop outcomes or hypothetical reactions, without confusing creativity with prediction.
Academic prototype: document models, prompts, sources, agent count, and run-to-run variability so the exercise stays interpretable.

Common pitfalls and fixes

Treating the agent’s score as truth. An external critic notes agents can produce plausible justifications without an independent verification mechanism. It’s a rival project’s critique, not an audit, but it flags a real limitation of LLM-based simulations.
Using results to trade markets. A community discussion raises use for volatility or trading and acknowledges the tension against statistical models; no recovered evidence shows MiroFish delivers valid financial predictions.
Not recording run conditions. Without model, prompt, seeds, date, agents, and report criteria, outputs can’t be compared or audited.
Underestimating technical requirements. Several conversations cite configuration, cost, and thermal/resource load as practical barriers; test with small scenarios first.
Trusting a domain by name alone. Only use the channels the FAQ confirms as official.

Security and trust model

Striking, ultra-detailed cyberpunk illustration of digital security and trust. A futuristic, neon-lit padlock and shield protect a glowing server rack in a dark environment. Warning signs in neon red and yellow holographic text flash around the perimeter, indicating unauthorized domains and exposed endpoints. The background features a secure, private network tunnel with electric blue light.

A submission accepted by VulDB notes that version 0.1.2 exposed more than 50 REST endpoints without authentication or authorization, including some destructive ones. The source links issue #487; this is vulnerability information that should be verified against the specific version and subsequent changes, but it’s enough reason not to expose legacy instances to an untrusted network.

At minimum, an instance should stay behind a private network, an authenticated proxy, and access controls; keys should go into secrets outside the repository, and uploaded sources should be treated as potentially sensitive data. Destructive functions shouldn’t be run, nor should private documents be uploaded, without knowing the deployment’s access policy.

The project is in an early stage — a secondary listing found v0.1.0 with Windows compatibility still under testing; this information may be outdated, but it reinforces the need to review issues, releases, and configuration before any shared use.

How the community received it

There’s an unofficial subreddit dedicated to sharing scenarios, installation, and experiments. Its moderators explicitly state it isn’t affiliated with the MiroFish team and suggest publishing objective, models, agent count, assumptions, cost, and failed results alongside any simulation.

Conversations show curiosity about uses in politics, product, public opinion, and trading, but also difficulties with configuration, keys, and quality evaluation. A Spanish-language post claims a political simulation of Bolivia anticipated later measures; that’s an individual after-the-fact testimony, not controlled proof of accuracy.

External reception includes criticism from a derivative project questioning whether LLM agents can justify scores without verifiable evidence. It should be read as an interested position from another tool’s author, though it’s a useful reminder not to turn a simulation into a source of truth.

MiroFish versus other approaches

Approach	Verifiable overlap	Verifiable difference
Traditional statistical simulation	Both explore scenarios and sensitivities.	MiroFish represents textual agents with personas and memory; it doesn’t thereby offer automatic statistical validation.
A research RAG agent	Both start from documents and retrieve context.	MiroFish uses that context to configure many simulated interactions and a social-dynamics report.
`brain-in-the-fish`	Inspired by MiroFish, working on prediction credibility.	It’s a third-party project proposing a different verification layer and critiquing the original approach.
`mirofish-cloud`	Makes deploying MiroFish easier.	It’s a community provisioner over external infrastructure, not the core project.

Use cases and who this repository can help

Product and research teams wanting to generate hypotheses about reactions, actors, and consequences before doing real research.
Scenario analysts who need to explore alternative narratives and document assumptions, not issue conclusive forecasts.
Authors and worldbuilders wanting to model interactions between characters or groups from a documentary base.
Agent researchers wanting to experiment with memory, graphs, and social simulation, carefully recording their conditions.

It shouldn’t be used as a decision engine for finance, policy, or security without external validation, human analysis, and domain-appropriate methods.

Resources

Repository: https://github.com/666ghj/MiroFish
Official FAQ: https://github.com/666ghj/MiroFish/issues/726
Static demo: https://666ghj.github.io/mirofish-demo
Unofficial community: https://www.reddit.com/r/MiroFish/
Community deployment: https://github.com/radishbuild/mirofish-cloud

Note: this article combines the repository, official FAQ, community sources, and a vulnerability reference retrieved on August 17, 2026. Simulation results are hypotheses conditioned by their data and configuration; they don’t equate to verified predictions.