Open Source Project #184: MiroFish — Shanda's Swarm Intelligence Prediction Engine That Builds Entire Digital Worlds to Forecast the Future

Open-source multi-agent simulation prediction platform backed by Shanda Group. Upload seed materials (news, reports, stories), describe a prediction goal, and MiroFish uses GraphRAG to build a knowledge graph, generates thousands of AI agents with independent personalities and long-term memory, simulates social interaction in a parallel digital world, and outputs a structured prediction report. Verified use cases: public opinion simulation, literary ending inference, and upcoming financial/political forecasting. Released December 2025, topped GitHub Global Trending in March 2026. 69.8k Stars, AGPL-3.0.

·7 min read·AI Research
open-sourcemulti-agentswarm-intelligencesimulationpredictionGraphRAGsocial-simulationLLMPythonShandaCAMEL-AIOASIS

Introduction

"Traditional forecasting tools fail not because they lack data, but because they ignore the emergent behavior that arises from individual interactions at scale."

This is article #184 in the "One Open Source Project a Day" series. Today's project is MiroFish — an open-source multi-agent simulation prediction engine backed by Shanda Group, released in December 2025, which topped GitHub's Global Trending list in March 2026. 69,800 Stars.

The use case MiroFish targets is specific: given a news article or a policy document, you want to predict what happens next — not a statistical regression, but "how will this actually evolve in a real society." Its approach: build a digital twin world. Thousands of AI agents, each with a distinct personality, memory, and social relationships, interact in a parallel simulation. You watch what emerges, then receive a structured prediction report with deep analysis — and you can chat directly with any agent that participated in the simulation.

"A Simple and Universal Swarm Intelligence Engine, Predicting Anything" — that's the tagline.

69,800 Stars. 10,900 Forks. AGPL-3.0.

What You'll Learn

  • The core logic of swarm intelligence prediction: why simulate individual interactions
  • MiroFish's four-step workflow: graph building → environment setup → simulation → report generation
  • GraphRAG + Zep long-term memory: the "cognitive infrastructure" for agents
  • Three verified use cases: public opinion simulation, literary continuation, future prediction
  • ReportAgent + deep interaction: "talking to" the simulation results
  • Installation and configuration: Docker or source deployment

Prerequisites

  • Basic understanding of LLMs and AI agents
  • Familiarity with Docker basics
  • General awareness of knowledge graphs (knowing what nodes and edges are)

Background: Why Prediction Is Hard

Weather forecasting breaks not from lack of compute, but from the butterfly effect — tiny differences in initial conditions cascade into completely different outcomes. Social prediction faces the same fundamental difficulty:

  • A policy announcement triggers different reactions across industries, those reactions influence each other, and a macroscopic outcome emerges that nobody individually "designed"
  • A news story travels completely different paths through different communities — emotional evolution, information distortion, group polarization — none of which linear statistical prediction captures

Traditional forecasting tools (statistical models, expert systems) describe "average behavior." Real outcomes are often extreme tails and emergent phenomena.

MiroFish's approach: don't predict the average, simulate the individuals. Put thousands of differentiated agents into a digital world, let them interact, and observe what emerges at the collective level.

Core Workflow: Four Steps + Deep Interaction

Step 1: Graph Building

Input seed materials: news articles, research reports, novel chapters — any text works.

The engine uses GraphRAG to extract a knowledge graph from seed materials:

  • Identifies entities (people, organizations, locations, events)
  • Extracts relationships between entities
  • Injects individual and collective memory
Seed material (Wuhan University news coverage)
    → GraphRAG entity extraction
    → Social relationship network construction
    → Historical background memory injection
    → Output: knowledge graph + memory foundation

Step 2: Environment Setup

Generates simulation environment components from the knowledge graph:

  • Entity relationship extraction: determines who connects to whom in the graph
  • Persona generation: each agent gets an independent personality, stance, and values
  • Agent configuration: personality, memory, and social relationships written into each agent's initial state

Each agent is a genuinely independent individual — not a copy of a shared template. A conservative middle-aged professor and an active university student react to the same news item with completely different responses and information-spreading behaviors.

Step 3: Simulation

Dual-platform parallel simulation, built on CAMEL-AI's OASIS framework:

  • Auto-parsed prediction requirements: extracts simulation parameters from your goal description
  • Dynamic temporal memory updates: agent memories evolve as simulation time progresses; early events shape later decisions
  • God's-eye variable injection: inject new events mid-simulation to observe how the system responds to perturbation

Thousands of agents interact across parallel timelines, generating large volumes of conversations, decisions, and behavioral records.

Step 4: Report Generation

After the simulation, ReportAgent takes over:

  • Analyzes data from the entire simulation run
  • Identifies key turning points and driving factors
  • Uses a ReACT toolset for deep reasoning — including a web_search tool that cross-references simulation predictions against real-world current data
  • Outputs a structured prediction report: trend analysis, risk points, probability assessments

Step 5: Deep Interaction

The report isn't the end. You can chat directly with any agent that participated in the simulation:

User: Why did you choose to repost that message during the event?
Agent (Professor Zhang): When I saw the message I was in a meeting,
  and my first reaction was that this resembled a case I
  researched last year...

You can also query the ReportAgent directly — ask for deeper analysis on any part of the report, or request reanalysis from a different angle.

Technical Architecture

Frontend (Node.js 18+)
    ↕
Backend (Python 3.11–3.12)
    ├── GraphRAG module       ← Knowledge graph construction
    ├── OASIS simulation engine ← CAMEL-AI open-source framework
    ├── Zep Cloud             ← Agent long-term memory storage
    ├── LLM interface         ← OpenAI-compatible API
    └── ReportAgent           ← ReACT toolset reasoning

Key components:

OASIS (CAMEL-AI): Open-source large-scale multi-agent social simulation framework designed for thousands of concurrent interacting agents. MiroFish's simulation engine foundation.

Zep Cloud: Long-term memory service built for AI agents. Keeps agent memory consistent across many simulation time steps. Free tier covers basic use.

GraphRAG: Microsoft's open-source knowledge graph-based RAG system. In MiroFish it handles structured knowledge extraction from seed materials, providing background memory for agents.

Recommended LLM: Official recommendation is Alibaba Qwen-plus. Any OpenAI-compatible endpoint works (GPT-4o, Claude, local Ollama, etc.).

Three Verified Use Cases

Use Case 1: Public Opinion Evolution Simulation

Seed: News coverage of an event at Wuhan University
Goal: Predict social media opinion trajectory

MiroFish generated agents representing different groups (students, faculty, media, administration) and simulated how information spreads, distorts, and amplifies across different communities, producing a predicted opinion evolution path.

Use Case 2: Literary Ending Inference

Seed: The first 80 chapters of Dream of the Red Chamber
Goal: Infer the probable ending for the missing final 40 chapters (Cao Xueqin's lost manuscript)

This is a genuinely interesting case: MiroFish treats the novel's characters as agents, initializes them with the personality settings and relationship dynamics established in the first 80 chapters, and lets them continue "living" and interacting. The story's natural evolution path emerges.

Use Case 3: Financial and Political Prediction

Listed as "coming soon." Existing demos show market sentiment evolution simulation from financial news.

Installation and Quick Start

Environment Variables

cp .env.example .env

Edit .env:

LLM_API_KEY=your_api_key
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus
 
ZEP_API_KEY=your_zep_cloud_key  # register at zep.us, free tier sufficient

Docker Deployment (Recommended)

docker compose up -d
# Frontend: http://localhost:3000
# Backend: http://localhost:5001

Source Deployment

npm run setup:all   # Install all frontend and backend dependencies
npm run dev         # Start development mode

Resources

Summary

MiroFish represents a shift in prediction paradigm: from "extrapolate trends from historical statistics" to "simulate individual social interactions and observe emergence."

Both approaches have their place. Statistical models are accurate and efficient when trends continue. But when you face a highly nonlinear social system — a policy shock, a viral event spreading through networks, complex multi-party dynamics — linear extrapolation fails at the critical moment, because it can't capture the heterogeneity of individuals or the emergent behavior their interactions produce.

MiroFish's roadmap reflects this judgment: public opinion and literary continuation are demonstrations, but financial and political prediction are the applications where the technology faces real-world accountability.

Released December 2025, topped GitHub Global Trending by March 2026. The speed says something about how many people want "simulatable prediction" as a category that exists.

Explore PrimeSkills — A marketplace for handpicked AI Agents and skills. Each is validated in real enterprise workflows, stripping away hype and keeping only what truly works.

Welcome to my Homepage for more useful insights and interesting products.

← Back to Blog