MiroFish: The AI That Simulates Entire Societies to Predict the Future (36K Stars in Days)
Feed it a news article, a policy draft, or market data. It creates a parallel digital world populated by thousands of AI agents — each with their own personality, memory, and behavior. They interact. They argue. They form opinions. Then you watch what happens next. This is MiroFish, and it just exploded to 36,500 GitHub stars.
It builds a miniature society of AI agents, gives them information, and watches how they behave. The prediction doesn't come from a statistical model — it emerges from simulated human behavior at scale. Think of it as a wind tunnel for decisions, except instead of testing aerodynamics, you're testing how people react.
What MiroFish Actually Does
MiroFish calls itself a "swarm intelligence engine, predicting anything." That sounds like marketing. But what it actually does is genuinely remarkable.
Here's the process in plain language:
- You provide seed material. This can be anything: news articles, financial data, policy drafts, market research, customer surveys, even novels. Plus a natural language question — "What happens to public sentiment if this policy passes?" or "How will the crypto market react to this regulation?"
- MiroFish creates thousands of AI agents. Each agent gets an individual personality profile, long-term memory, behavior patterns, and decision-making logic. They're not identical copies. They have different backgrounds, different opinions, different risk tolerances — modeled on the diversity of real human populations.
- The agents are placed in a simulated world. They interact with each other and with the seed data. They form opinions. They influence each other. They change their minds. Group dynamics emerge naturally — factions, consensus, contrarian positions, viral ideas.
- MiroFish observes what happens. The output is two things: a prediction report summarizing the emergent behavior and likely outcomes, and an interactive digital world you can explore — watching individual agents, tracking how opinions spread, seeing which groups formed and why.
The prediction doesn't come from a formula. It comes from emergent behavior — thousands of simulated individuals reacting to information the way real people would, and the aggregate of those reactions producing a forecast.
How the Simulation Works
Under the hood, MiroFish uses a multi-agent simulation architecture. Each agent is a lightweight LLM-powered entity with three key properties:
Individual Personality
Each agent has a unique personality profile — optimistic or pessimistic, risk-seeking or risk-averse, leader or follower, early adopter or skeptic. These aren't random assignments. MiroFish generates personality distributions that mirror real population demographics based on the context you provide. A simulation about financial markets gets agents that think like traders, retail investors, institutional managers, and regulators. A simulation about public policy gets agents that think like citizens, activists, politicians, and bureaucrats.
Long-Term Memory
Agents remember what happened earlier in the simulation. If Agent 47 read a bearish news article in round 1 and then heard Agent 200 express optimism in round 3, those memories accumulate and influence Agent 47's decisions in round 5. This is powered by Zep memory — a persistent memory layer that gives each agent a coherent history rather than treating each interaction as isolated.
Behavior Logic
Agents don't just form opinions — they act. They share information. They try to persuade others. They change their behavior based on what they see the group doing. Some agents are contrarians who push back against consensus. Some are followers who amplify popular views. The behavior logic creates realistic social dynamics where ideas spread, factions form, and consensus either builds or fractures — just like in real groups.
The simulation runs in discrete rounds. Each round, agents process new information, interact with nearby agents, update their beliefs, and take actions. MiroFish uses the OASIS simulation engine (built on CAMEL-AI) to orchestrate these interactions at scale — managing thousands of concurrent agent processes, their memory states, and their social graphs.
The result is emergent intelligence. No single agent knows the "answer." The answer emerges from the collective behavior of thousands of agents, each making individual decisions based on their unique personality, memory, and social context.
God View: Injecting Variables Into the Simulation
This is where MiroFish goes from interesting to powerful.
"God view" lets you intervene in a running simulation. You can inject new variables — a breaking news event, a policy change, a competitor's announcement — and watch the entire simulated world react in real time.
Imagine you're simulating how customers react to a price increase. The initial simulation shows moderate pushback. Now you inject a variable: a competitor drops their price by 20%. You watch the simulation evolve. Agents who were tolerating your price increase suddenly start considering alternatives. The sentiment shifts. New factions form around switching costs vs. brand loyalty.
You can run this scenario dozens of times with different variables. What if the competitor's price drop is 10% instead of 20%? What if you counter with a loyalty discount? What if you bundle a new feature? Each variable injection produces a different simulation trajectory — and the aggregate of those trajectories gives you a map of possible futures, not just one prediction.
Real Use Cases (From Financial Markets to Fiction)
MiroFish's versatility is part of what's driving its explosive GitHub growth. Here are documented use cases from the community:
Financial Markets
A popular fork (BTC Fear and Greed Index simulator) feeds MiroFish crypto market data and social media sentiment. Thousands of simulated traders — with different risk profiles, time horizons, and information sources — buy, sell, and hold. The emergent market behavior produces fear/greed predictions that account for crowd psychology, not just price charts. Multiple community members are tracking its accuracy against real market movements.
Public Sentiment Analysis
Feed MiroFish a proposed government policy and demographic data. Watch how different population segments react. See which groups support it, which oppose it, and — critically — see how those positions evolve as agents discuss and debate with each other. The prediction isn't just "60% approve." It's a dynamic map of how approval forms, where resistance clusters, and what arguments gain traction.
Geopolitical Scenario Planning
Specialized forks use MiroFish to simulate international relations. Agents represent nations, factions, and interest groups. Feed it a geopolitical event and watch alliance structures shift, economic responses cascade, and diplomatic positions harden or soften. Multiple research groups are using this for conflict analysis and trade policy modeling.
Fiction and Narrative Prediction
In one of the more surprising applications, MiroFish was used to predict the lost ending of "Dream of the Red Chamber" — one of China's Four Great Classical Novels. The simulation populated a world with characters from the novel, gave them their known personalities and motivations, and let the story play out. The predicted ending reportedly aligned with scholarly theories about the author's intentions. It's a fascinating demonstration of what happens when you treat narrative as emergent behavior rather than authored plot.
How Business Owners Can Use This
MiroFish is built by researchers, but the applications for business owners are immediate and practical.
Product Launch Scenario Testing
Before you launch a new product or feature, feed MiroFish your product description, target market demographics, competitor landscape, and pricing. Watch how thousands of simulated customers react. Do they adopt it? At what price point does adoption drop? Which segments convert first? Which objections come up most often? This is focus group testing at scale — thousands of participants, instant results, and the ability to test variations without the cost and time of real research.
Pricing Strategy Simulation
Pricing is one of the highest-leverage decisions a business makes, and one of the hardest to test. MiroFish lets you simulate price changes against a population of agents modeled on your customer base. Test a 10% increase, a 20% increase, tiered pricing, freemium models — and see not just whether agents buy, but how they talk about the change, whether they churn, and how long it takes the market to stabilize.
Competitive Response Modeling
You're about to enter a new market. How will incumbents respond? Feed MiroFish the competitive landscape — existing players, their market positions, their known strategies — and announce your entry. Watch how simulated competitors react. Do they cut prices? Do they launch counter-products? Do they ignore you? The simulation surfaces responses you might not have anticipated, giving you time to prepare before you're in the market for real.
Crisis Communication Testing
Your company faces a PR crisis. You have three possible response strategies. Feed each one to MiroFish along with your customer base profile, media landscape, and social media dynamics. Watch how each response plays out in the simulated public sphere. Does the apology satisfy people or does it backfire? Does silence let the story die or does it fester? You can test crisis responses in a simulation before you test them in reality — where mistakes are permanent.
The common thread across all of these: MiroFish lets you test decisions in a simulated world before committing to them in the real one. The simulation isn't perfect — no model is — but it surfaces dynamics, reactions, and second-order effects that spreadsheet analysis and gut instinct miss.
The Tech Stack (Simplified)
For the technically curious — or for the conversation with your technical team — here's what MiroFish is built on:
- Core simulation: OASIS engine (built on CAMEL-AI) — manages thousands of concurrent agent processes, their interactions, and the simulation world
- Memory: Zep — persistent memory layer that gives each agent coherent long-term recall across simulation rounds
- Knowledge retrieval: Graph RAG — lets agents retrieve and reason over complex, interconnected information from the seed data
- Backend: Python — the simulation engine, agent logic, and data processing
- Frontend: Node.js — the interactive visualization layer where you explore the simulated world
- LLM integration: Any OpenAI-compatible API — use GPT-4, Claude, Nemotron, or local models via Ollama
The project is open source at github.com/666ghj/MiroFish with 36,500+ stars. It's backed by Shanda Group and originated from a Chinese research team, though the codebase and documentation include English, and the fork ecosystem spans Korean, German, and English-language projects.
The Fork Ecosystem
One of the best indicators that an open source project has real substance: the fork ecosystem. MiroFish has spawned a remarkable number of specialized variants:
- BTC Fear and Greed simulator — optimized for crypto market prediction with financial agent archetypes
- Geopolitical analysis tools — specialized for international relations and conflict simulation
- Offline versions — configured to run entirely on local hardware with Ollama, no API costs
- Korean, German, and English language forks — localized interfaces and agent personality models
- Industry-specific variants — healthcare policy, education reform, urban planning
The fork ecosystem tells you something important: developers and researchers see MiroFish as a platform, not just a tool. They're building on it because the core simulation engine is flexible enough to support radically different applications — from predicting Bitcoin prices to predicting how a novel ends.
The Honest Limitations
MiroFish is impressive. It's also not magic. Here's what you should know before you stake business decisions on it:
Frequently Asked Questions
Q: What is MiroFish and how does it work?
MiroFish is an open source multi-agent prediction engine. You feed it seed data — news articles, policy drafts, market data, or any text — along with a natural language prediction request. It creates thousands of AI agents, each with individual personalities, long-term memory, and behavior logic, and places them in a simulated digital world. The agents interact freely, and the emergent group behavior produces predictions. MiroFish returns both a prediction report and an interactive digital world you can explore.
Q: Is MiroFish free to use?
MiroFish is open source and free to download. Running it requires LLM inference — you need an OpenAI-compatible API key (OpenAI, Anthropic, or a local model via Ollama). The cost depends on simulation size. A small run with a few hundred agents using a budget model might cost a few dollars. A large simulation with thousands of agents using frontier models could cost significantly more. Offline forks exist that run entirely on local hardware.
Q: What can MiroFish predict?
Documented use cases include public sentiment shifts, financial market behavior (there's a BTC Fear and Greed Index fork), geopolitical outcomes, and even fictional narratives — it famously predicted a lost ending of Dream of the Red Chamber. The key insight is that predictions emerge from simulated human behavior, not statistical extrapolation. Any scenario involving how groups of people respond to information is a potential use case.
Q: How can businesses use MiroFish for scenario planning?
Feed it your scenario and relevant context — a pricing change, a product launch, a competitive move — along with data about your market and customer base. Watch how thousands of simulated stakeholders react. The "God view" feature lets you inject variables dynamically — change one assumption and watch the entire simulation evolve. Use it for product launch testing, pricing strategy, competitive response modeling, and crisis communication planning.
Free: The AI Growth Breakdown
See how one business went from 0 to 100+ daily visitors in 14 days using AI agents. The exact tools and results.
Get the Free Breakdown →