MiroFish: Agent-Based Social Simulation Explained

‍

MiroFish is a GitHub repository that went viral in early 2026, hitting number one on GitHub's global trending list and accumulating over 33,000 stars. In this edition of Passion Academy, Nadine from Passion Labs breaks down what it actually is, how it works, and where to be cautious with it.

‍

What Is MiroFish?

‍

MiroFish calls itself a swarm intelligence engine. But more precisely, it is an agent-based social simulation. Rather than following simple collective rules, it simulates thousands of individual synthetic personas inside a custom-built virtual world, and observes what emerges from their interactions.

‍

It has already been used for:

‍

• Public opinion forecasting on policy drafts
• Simulating financial market reactions across analysts and investors
• Narrative extrapolation- . predicting how a story would end based on existing content

‍

‍

How It Works

‍

At the core of every simulation is seed material, a detailed description of the world you want to simulate. This needs to include:

‍

• All entities: people, organisations, roles and relationships
• Current trends and external influences acting on the world
• The specific question you want the simulation to answer

‍

The system will not invent new entities on its own. Everything that matters needs to be defined upfront.

‍

‍

‍Building the Knowledge Graph

‍

Once the seed is ready, MiroFish uses GraphRAG to construct a knowledge graph. This does more than store facts, it encodes relationships between entities. The system knows not just what a company is, but how it connects to people, products and other organisations.

‍

Memory is managed using Zep, which handles both:

‍

• Collective memories shared across all agents in the simulation
• Individual memories unique to each specific agent

‍

‍

The Agent Layer

‍

Each agent is given a full profile:

‍

• Personality and demographic background
• A backstory and initial stance on the topic
• A social network position — who follows them, how credible they are, who they can reach

‍

The social simulation itself runs on Oasis, an open-source social network simulator. Two environments are available — a short-form platform similar to X, and a threaded discussion platform similar to Reddit.

‍

‍

Running the Simulation

‍

The simulation runs in cycles. In each cycle, every agent:

‍

• Receives a simulated feed of posts
• Deliberates based on their memory, backstory and GraphRAG context
• Acts: posting, sharing, following and unfollowing

‍

Each action updates their beliefs and memory. This repeats across many cycles, essentially fast-forwarding through a social network over simulated time.

‍

‍

What the Report Agent Analyses

‍

Once the cycles are complete, a specialised report agent processes everything and looks at:

‍

• How opinion distributions shifted across cycles
• What coalitions or opinion groups formed
• Whether any tipping points occurred
• Which narratives spread and which fragmented
• What counterfactual conditions might have changed the outcome

‍

You can also interact directly with individual agents, inject new assumptions mid-simulation, or rerun with different parameters.

‍

‍

Words of Caution

‍

MiroFish is an impressive and genuinely fun tool. But two things are worth keeping in mind.

‍

First, there is no published benchmark. Oasis, the underlying social simulator, has been used in controlled academic studies and has real scientific grounding. MiroFish as a general-purpose prediction engine has not been formally evaluated. It is an interesting exploration tool, not a proven forecasting system.

‍

Second, token costs are significant. Running hundreds of agents across many cycles generates enormous context. Starting with lighter, cheaper model variants is strongly recommended before scaling up.

‍

‍

The Bigger Picture

‍

What makes MiroFish interesting is not just the tool itself but what it represents. Agent-based modelling has a long history in social science and economics. What MiroFish does is dramatically lower the barrier to running these simulations, by combining existing open-source tools (GraphRAG, Oasis and Zep) into something fast and accessible to set up.

‍

The potential applications across policy, finance, product research and communications are real. It will be great to see how the benchmarking and scientific grounding catches up with the hype.

‍

‍

References

https://github.com/666ghj/MiroFishhttps://mirofish.ink/