MiroFish

In early March 2026, an open-source project built by a Chinese university student topped GitHub’s global trending list. Its name was MiroFish, and its tagline was “A Simple and Universal Swarm Intelligence Engine, Predicting Anything.”¹ In Korea too it was introduced as “Mirofishi” and drew attention.¹¹

But buzz and substance are different matters. Some articles write that it “simulates an entire society and gets the future right,” while others criticize it as “hype without scientific foundation.”⁷ This document aims to set out only what can be confirmed between those two poles.

It is organized as follows.

• Chapters 1–3 cover the concept, background and academic lineage. Newcomers can join the conversation after reading just these.
• Chapters 4–5 cover the internals: MiroFish’s five-step pipeline and the OASIS engine that actually moves the agents underneath.
• Chapter 6 covers the use cases and demos presented by the official site and repository.
• Chapter 7 covers limits and debate. It is the most important chapter in this document.
• Chapters 8–10 cover cost and license if you run it yourself, an interpretation from a content-production angle, and indicators to watch. The appendices contain a glossary, a staged reading list and the references.

A one-sentence definition

The official repository introduces MiroFish as “a next-generation AI prediction engine that extracts seed information from the real world — breaking news, policy drafts, financial signals — and automatically builds a high-fidelity parallel digital world in which thousands of intelligent agents with independent personalities, long-term memory and behavioral logic interact freely and evolve socially.”¹ The introduction site puts it as turning “real-world seeds such as news, policy drafts, analytical reports or fiction into a parallel world populated by agents with memory, motives and social behavior.”²

Three elements can be drawn from this definition. ① Seed: it starts from a real-world document. ② World: it builds a society in which agents react to one another and change over time. ③ Report: it summarizes what happened in that society in a form people can read.

Three analogies

① A “mock society” before a policy takes effect

Imagine watching the reaction first in a virtual city of thousands of people with similar dispositions before announcing a new policy. You would see in advance which groups push back first, which rumors spread and at what point opinion splits. The position MiroFish aims for is exactly this “mock society.” Korean media made the same point, introducing it as something that lets you “experiment in advance with various social reactions before introducing a policy.”¹¹

② A novelist’s character notes

A novelist writes down each character’s personality, desires and relationships, and when an event occurs follows “what would this character do?” while writing the story. MiroFish is close to a tool that automates this work with agents. The team’s demo of feeding it the first 80 chapters of Dream of the Red Chamber and having it simulate the lost ending is in the same vein.¹⁴

③ A “small Earth” inside social media

MiroFish’s agents write posts, comment, like and follow one another on two social platforms, one Twitter-like and one Reddit-like.² Think of it as a laboratory that shrinks social media into a single box.

Easily confused neighbors

The creator and background

According to the Chinese outlet 36Kr, Guo Hangjiang, who made MiroFish, is a senior undergraduate at Beijing University of Posts and Telecommunications, with the GitHub name BaiFu. After joining Shanda Group as an intern he reportedly finished the project in about ten days, and before that he had built another popular open-source project, BettaFish, during a ten-day holiday.¹² The official repository states that Shanda Group provided “strategic support and incubation.”¹

The investment size is described differently across reports. 36Kr says Shanda’s Chen Tianqiao invested 30 million yuan (also presented as roughly $4.1 million) within 24 hours of receiving the demo video, while Korean media reported that it “attracted investment worth billions of won.”¹²¹¹ All of this is as reported and is not a figure this document verified independently.

Popularity indicators

The indicators confirmed on the official repository page are about 77,000 GitHub stars and about 12,000 forks, under the AGPL-3.0 license (as viewed in October 2026).¹ Korean media reported that it took first place on GitHub’s popularity ranking right after release.¹¹ A Korean community fork (MiroFish-Ko) has appeared since.¹⁵

Why it became a topic

Three reasons overlapped. First, an intuitive and visual promise: “put in a document and a society is simulated.” Second, a sense of scale: thousands to hundreds of thousands of agents. The introduction site advertises “1M+ parallel agents per run.”² Third, the narrative of a student developer and big-company investment. None of these, however, is evidence that the predictions were right.

MiroFish is not a sudden idea. Attempts to “grow” a society inside a computer have a history of more than half a century, and MiroFish stands on the latest branch of it. The timeline below is the context this document has assembled.

Step 1 — Graph building: turning the seed into structure

It extracts entities and relationships from the input document with GraphRAG and builds a knowledge graph. The introduction site splits this stage into ontology generation and graph construction, producing “structured entities, motives and factual anchors” and “a living relationship graph that exposes the actors, tensions and memory structure.”² A developer-oriented write-up describes it as structuring “who the key players are, how they are connected and what pressures exist.”¹⁴

Step 2 — Environment setup and agent generation: giving characters personalities

For each entity in the graph it creates an agent persona with a background, perspective and disposition, and stores long-term memory in Zep Cloud. An “environment configuration agent” then sets the simulation’s rule parameters.¹⁴ At this stage the number of agents is sometimes decided automatically; one independent test reported that 100 were requested but 25 were created.⁶

Step 3 — Parallel simulation: where the society runs

Agents interact over several rounds on two platforms, one Twitter-like and one Reddit-like. Each agent’s memory is updated as events unfold.¹ The OASIS engine does the actual running (Chapter 5). The user can observe the progression from a “god’s-eye view” and inject variables midway.¹³

Step 4 — Report generation: turning logs into a story

A dedicated ReportAgent analyzes the simulation results with tools and compiles shifts in opinion, formation of coalitions and emergent patterns into a readable report. The introduction site says the report contains “key turning points, risks and confidence signals.”²

Step 5 — Deep interaction: asking the agents directly

Users can ask the ReportAgent follow-up questions or talk directly with (interview) individual agents to ask why they acted as they did. Injecting new variables and rerunning the scenario also happens at this step.²¹⁴ It should not be forgotten, though, that these “answers” are LLM-generated responses, not the real inner thoughts of real people.

The tech stack at a glance

Five modules

Modeled on the structure of real social media, OASIS consists of five modules.³

The agents’ actions

The paper defines 21 types of actions, including sign up, refresh, searching trends, posts and users, creating a post, reposting, following and unfollowing, muting, liking and disliking, writing comments and reacting to comments.³ The introduction site and some write-ups say “23 social actions,” so the figure differs between documents.¹⁴ This document takes the paper’s figure as the baseline while leaving open the possibility that actions were added in later versions.

Social phenomena the paper reports reproducing

• Information spreading: agreement with real Twitter data at about 30% normalized RMSE (198 cases).³ It is safer to read this not as “perfect agreement” but as “the trends are similar.” (This document’s interpretation)
• Group polarization: opinions growing more extreme as discussion proceeds. It was more pronounced in uncensored models.
• Herd effect: agents followed the majority more strongly than people did, especially on negative signals. The herd effect appeared when there were 10,000 or more agents.

Scale and cost

The paper tested scales from 196 to over 100,000 agents and demonstrated up to one million. That took about 18 hours per time step on 27 A100 GPUs.³ There was also an observation that larger groups produced more diverse and more helpful agent opinions.

Limits the paper acknowledges

The authors themselves list as limitations that the precision of the recommendation system affects propagation depth, that user-profile representation is simple, and that the emergence of social norms and complex behavior has not been explored enough.³

The introduction site presents six use cases.² The “maturity” in the table is this document’s judgment based on the publicly available evidence.

Demo 1 — The Wuhan University opinion simulation

The first demo the team released concerns public opinion about Wuhan University. It fed a public-opinion analysis report produced by its sister project BettaFish into MiroFish and had it simulate how sentiment would evolve.¹⁴

Demo 2 — The lost ending of Dream of the Red Chamber

The second demo is more unusual. It fed in the first 80 chapters of the 18th-century Chinese novel Dream of the Red Chamber and had the system simulate how the original’s lost ending might have continued.¹⁴ This is closer to “story development based on character logic” than to “prediction.” (This document’s interpretation)

Financial prediction is officially not supported

In a discussion thread on the repository, the maintainer stated plainly that MiroFish “is not a calibrated or backtested stock- or cryptocurrency-price predictor.” It has no real-time market-data integration, quantitative factor modeling or stable confidence metrics, and a calibrated price-prediction product is not planned for the core repository. Financial prediction is a planned feature marked “coming soon,” and the maintainer insisted that results must not be presented as investment advice or proven predictive accuracy.⁸

Issue 1 — The absence of validation

The biggest problem is simple. That a simulation produces plausible social dynamics does not mean those dynamics predict what real people will do. The team has not published a benchmark comparing predictions with past outcomes, and the demos are an introduction to the methodology, not evidence of accuracy.¹⁴ The introduction site itself says results are “exploratory outputs” that should be reviewed before operational, financial or policy decisions.²

Issue 2 — The academic critique: LLMs have not solved the problems of agent-based modeling

After reviewing LLM-based generative social-simulation research, Larooij and Törnberg of the University of Amsterdam argue that it does not solve the long-standing validation and calibration problems of agent-based modeling but rather worsens them.⁵ Their key points are as follows.

• Weak validation: many studies rely on the subjective judgment of whether results look “believable,” without rigorous empirical comparison.
• A different voice from people: in quantitative comparisons, LLM responses are “longer, more polite, articulate and respectful” than those of real people.
• Black boxes: “LLMs are ‘black-box’ models: their capacities are emergent, and it is virtually impossible to understand why a particular model gives a particular output.”
• Computational burden and reproducibility: they need far more computation, yet most studies run no sensitivity analysis or repeated runs.

Issue 3 — The “MiroFish Mirage” debate

Daniele Proverbio criticizes the “predicting anything” tagline as hype without a scientific foundation. His argument has three parts. First, AI multi-agent systems are still at the research stage, with failures, biases and epistemological problems being observed one after another. Second, AI behavior varies with which LLM is used and does not fully match human choices even in simple situations. Third, both the assumption that an individual LLM faithfully represents human decision-making and the assumption that an agent society mirrors human society remain unproven. He cites Google Flu Trends, once promising but ultimately not working properly, as a cautionary precedent.⁷

Issue 4 — Reports from hands-on use

WPP Research installed MiroFish itself on 14 May 2026 and tested prediction of the S&P 500’s direction and its top five stocks. The cost was about one dollar across all runs (using gemini-2.5-flash-lite).⁶

This test is a single case that tried finance, not MiroFish’s main area. This document does not read it as a verdict on MiroFish as a whole, but as a signal to “lower expectations and validate first.” The report judged the framework still “fragile.”⁶

Issue 5 — Herding bias

As the OASIS paper itself states, LLM agents are more susceptible to herding than people.³ A simulated crowd may therefore polarize faster than a real one, and because this is a systematic bias stemming from the underlying model and structure, it could tilt results consistently toward more extreme outcomes. (This document’s interpretation)

What AGPL-3.0 means

AGPL-3.0 is a strong copyleft license that requires you to make the modified source available to users even when you offer modified software as a network service. It is a small burden if you use it only as an internal tool, but if you plan to offer an external service built on it, legal review is needed. (This is a general explanation of the license, not legal advice.)

Data and privacy

Because input documents are sent to an external LLM API and to Zep Cloud, it is safer not to upload confidential documents or material containing personal information as is. Some forks advertise a local mode, but that is not a feature of the official project and needs separate review. (This document’s suggestion)

This chapter is this document’s interpretation and suggestion based on public material. That MiroFish accepts fiction as input and lists launch reaction as a scenario are interesting points at the content-planning stage.

Uses that could fit well

• Checking a world and its character relationships: feeding in a synopsis and setting materials as the seed and watching how characters react to events to find gaps in the narrative. The same way as the Dream of the Red Chamber demo.
• Forming reaction hypotheses before release: quickly producing several hypotheses of the form “in which communities could what reactions arise?” for choices such as a trailer, a twist or a release cadence.
• Rehearsing crisis scenarios: using how a rumor spreads when a controversy erupts as material for discussion.

What not to expect

• Direct prediction of box-office figures: it is not calibrated to hit numbers such as audience size, ratings or revenue. The reason is the same as why financial prediction is officially unsupported.⁸
• A replacement for real audience reaction: LLM agents are more polite, more consistent and herd more easily than people.⁵³ It is hard to believe they reproduce unstructured reactions such as fandom emotion as they are.
• Immediate use in a Korean-language setting: the official project centers on Chinese and English, and how well it reflects the speech and culture of Korean communities has not been validated.

This chapter is this document’s overall judgment, based on the material above. Please use it not as a prediction but as a checklist of what to look at when reading related news.

In closing

MiroFish is significant for turning the powerful imagination of “growing a society from a single document” into a tool anyone can download and run. At the same time, today’s evidence stays at demonstrations that “such simulation is possible,” and there is not yet proof that “this simulation is right.”

So the best stance toward this tool is neither enthusiasm nor cynicism. It is to read the results not as prophecy but as hypotheses for discussion, and to check the same question once more against real data. For swarm-intelligence simulation to become a trusted tool, that validation has to accumulate first.

Stage 1 — Introduction (getting a grasp)

• The official repository README for MiroFish¹
• Asia Economy, “Mirofishi” AI agent draws popularity — Korean coverage¹¹
• The MiroFish introduction site — the five steps and use cases²

Stage 2 — Roots (underlying technology)

• Park et al., Generative Agents: Interactive Simulacra of Human Behavior (2023)⁹
• The OASIS paper (2024)³
• Park et al., Generative Agent Simulations of 1,000 People (2024)¹⁰

Stage 3 — Critique and validation

• Larooij & Törnberg, Do Large Language Models Solve the Problems of Agent-Based Modeling?⁵
• House of Ethics, The MiroFish Mirage?⁷ · WPP, MiroFish: Is swarm intelligence worth the cloud bill?⁶
• Repository discussion #280, Stock & Crypto Market Prediction Capability⁸

Stage 4 — Hands-on practice

• Two developer write-ups¹³¹⁴ · the Korean fork¹⁵