MiroFish: Simulate a World, Predict the Future

By Prahlad Menon 4 min read

Most forecasting tools are statistical. They look at historical patterns, fit a curve, and extrapolate. They’re good at predicting what will probably happen if nothing unusual occurs.

They’re useless for predicting what happens when people interact.

Markets crash because traders panic, not because of fundamentals. Policies fail because communities resist, not because the math was wrong. Novels end the way they do because of character dynamics, not plot logic.

MiroFish takes a different approach. Instead of modeling trends, it models agents — thousands of them, each with distinct personalities, memories, and behavioral logic — and lets them interact inside a simulated world seeded with real data.

The prediction emerges from the simulation, not from a formula.

How It Works

The pipeline has four stages:

1. Seed extraction You provide a “seed” — a news article, a policy document, a financial report, even a novel. MiroFish extracts the key entities, relationships, and context using GraphRAG, building a knowledge graph of the world you want to simulate.

2. World construction From the graph, the system generates agent personas — people, institutions, factions, characters — each with individual personality traits, roles, and memories injected from the seed material. A geopolitical simulation might generate politicians, journalists, market actors, and citizens. A novel simulation generates its cast.

3. Simulation The agents interact freely across two parallel simulation platforms, with time-series memory updating as events unfold. You can watch from a “god view” — observing the emergent dynamics — and inject new variables mid-simulation to test scenarios.

4. Report generation A dedicated ReportAgent with deep tool access queries the post-simulation environment and produces a structured prediction report. You can also directly converse with any agent in the simulated world, or continue the dialogue with ReportAgent.

The Demos

The two flagship demos are worth knowing about — they make the concept tangible.

The Dream of the Red Chamber ending Dream of the Red Chamber is one of China’s four great classical novels. The original author died before completing it, and the final 40 chapters were written by a different author — considered by many scholars to be inferior and inconsistent with the first 80. MiroFish was fed the first 80 chapters (hundreds of thousands of Chinese characters) and asked to predict the lost ending. The result is a full narrative projection grounded in the established character dynamics and relationships. Watch the demo on Bilibili.

Public opinion simulation MiroFish’s sister product BettaFish generated a public opinion report on a real trending event, modeling how different demographic groups would react, how the narrative would spread, and what the downstream social dynamics would look like. Watch the demo on Bilibili.

The live demo is available on GitHub Pages.

Technical Stack

  • Simulation engine: OASIS by CAMEL-AI — a multi-agent social simulation framework
  • Memory: Zep Cloud for long-term agent memory (free tier covers basic usage)
  • Knowledge graph: GraphRAG for world-building from seed material
  • LLM: Any OpenAI-compatible API — the team recommends Alibaba’s qwen-plus via Dashscope, which keeps costs reasonable
  • Frontend: Node.js 18+ / React
  • Backend: Python 3.11–3.12

Backed by Shanda Group — the Chinese gaming and tech conglomerate — it’s not a hobby project.

Running It Locally

Prerequisites: Node.js 18+, Python 3.11–3.12, uv for package management.

git clone https://github.com/666ghj/MiroFish
cd MiroFish
cp .env.example .env
# Fill in LLM_API_KEY, LLM_BASE_URL, LLM_MODEL_NAME, ZEP_API_KEY
npm run setup:all
npm run dev

Frontend runs at http://localhost:3000, backend at http://localhost:5001.

Docker is also supported:

cp .env.example .env
docker compose up -d

Cost note: Simulations are token-intensive. The team recommends starting with fewer than 40 simulation rounds to get a feel for costs before scaling up. Using a cheaper model like qwen-plus or a local Ollama instance will reduce costs significantly.

The Bigger Idea

We’ve covered multi-agent financial systems and browser-based conflict simulations before. MiroFish sits in the same territory but with a different ambition — general-purpose social simulation rather than a domain-specific tool.

The insight it’s built on is real: complex social outcomes emerge from individual interactions in ways that aggregate statistics can’t capture. Epidemiologists figured this out with agent-based disease models. Economists use agent-based models for market dynamics. MiroFish applies the same logic to anything you can describe in natural language.

That’s the audacious part of “predicting anything” — not that it’s literally true, but that the simulation approach generalizes in a way that curve-fitting doesn’t.

What it’s good at: scenarios where individual behavior and social dynamics drive outcomes — public opinion, narrative evolution, policy adoption, character-driven storytelling.

What it’s not: a replacement for quantitative models in domains where the physics are well-understood. It’s a complement, not a substitute.

Try It

The live demo requires no setup. The GitHub repo has English documentation in README-EN.md. The team is active on Discord and X.