MiroFish AI — Predict anything
with swarm intelligence

What is MiroFish AI?

MiroFish is an open-source swarm intelligence simulation engine that predicts future outcomes by simulating how thousands of AI agents interact with each other. Instead of asking a single AI model to guess what happens next, MiroFish builds a miniature digital society and watches what emerges.

It was built in just ten days by Guo Hangjiang, a 20-year-old undergraduate student at Beijing University of Posts and Telecommunications. After hitting #1 on GitHub's global trending list in March 2026 — surpassing repositories from OpenAI, Google, and Microsoft — it secured $4.1 million in funding within 24 hours.

The project is fully open-source under the AGPL 3.0 license and available on GitHub at github.com/666ghj/MiroFish. The simulation engine is powered by OASIS, a peer-reviewed framework from the CAMEL-AI research community capable of scaling to one million agents.

How does MiroFish work?

MiroFish operates through a five-stage pipeline that transforms any document into a full predictive simulation.

Stage 1 — Upload seed material

You provide a "seed document" — this can be a news article, financial report, policy draft, or even a novel. MiroFish accepts PDFs, text files, and markdown.

Stage 2 — Knowledge graph construction

Using GraphRAG (Graph-based Retrieval Augmented Generation), MiroFish extracts entities, relationships, and pressures from your document and builds a structured knowledge graph. This becomes the "reality" the simulation is built on.

Stage 3 — Agent generation

From the knowledge graph, MiroFish automatically generates thousands of AI agent personas. Each agent receives a unique personality, background, initial stance, and social relationships with other agents. Their long-term memory is managed by Zep Cloud.

Stage 4 — Dual-platform simulation

The simulation runs simultaneously on two platforms: a Twitter-like environment (fast, viral, short-form) and a Reddit-like environment (threaded, deep debate). Agents post, comment, argue, form opinions, and influence each other across both platforms.

Stage 5 — Prediction report

A dedicated ReportAgent analyzes the emergent outcomes and produces a structured, human-readable forecast. You can also directly query individual agents or inject new variables mid-simulation from a "god's-eye view."

How to use MiroFish

There are three ways to use MiroFish, depending on your technical comfort level.

Option A — Use it in your browser (no installation)

The easiest way. Platforms like ThousandMinds host MiroFish for you — you just sign up, add your API keys, and start simulating immediately. No terminal, no Docker, no configuration files.

Option B — Install locally (Mac / Linux / Windows)

For developers who want to run MiroFish on their own machine:

1. Install Node.js 18+, Python 3.11+, and uv (Python package manager)
2. Clone the repository: git clone https://github.com/666ghj/MiroFish.git
3. Copy the example config: cp .env.example .env
4. Add your API keys to the .env file (see API key setup below)
5. Run: npm run setup:all then npm run dev
6. Open http://localhost:3000 in your browser

Option C — Docker deployment

For server deployment or if you prefer containerized environments:

MiroFish API key setup

MiroFish requires two external API services to function: an LLM provider and Zep Cloud for agent memory.

1. LLM API key (OpenAI or compatible)

MiroFish works with any OpenAI-compatible API. The recommended options are:

• OpenAI (gpt-4o-mini) — easiest for Western users. Get your key at platform.openai.com. A typical simulation costs $0.50–2.00.
• Alibaba Qwen-plus — recommended by the original developers, cheaper but requires a Chinese platform account.
• Any other OpenAI-compatible API — OpenRouter, Together AI, etc.

In your .env file, set these three variables:

2. Zep Cloud API key

Zep Cloud manages the long-term memory of each agent — allowing them to remember previous simulation rounds and evolve their behavior over time. The free tier at app.getzep.com is sufficient for basic simulations.

Run MiroFish in your browser — no installation

One of the most common questions about MiroFish is how to use it without installing Python, Node.js, Docker, or configuring anything on your computer.

The answer: use a hosted version. ThousandMinds provides MiroFish as a browser-based service — you bring your own API keys (OpenAI + Zep), and we handle all the infrastructure.

MiroFish offline — can you run it without internet?

MiroFish itself can run locally on your machine, but it requires an active internet connection during simulations because it calls external LLM APIs (OpenAI or similar) and the Zep Cloud memory service for each agent interaction.

A fully offline version would require:

• A locally hosted LLM (e.g. Ollama with Llama 3 or similar) configured as the LLM_BASE_URL
• A self-hosted Zep instance (possible but complex)

Some community forks have added support for local LLMs. For most users, running it locally via npm or Docker while connected to the internet is the practical "offline" experience — no cloud hosting dependency, but API calls still go out.

How much does MiroFish cost?

MiroFish itself is completely free and open-source. The costs come from the external APIs it uses.

LLM API costs (your OpenAI bill)

• Small simulation (50 agents, 20 rounds): ~$0.30–0.80
• Medium simulation (200 agents, 30 rounds): ~$1.50–4.00
• Large simulation (1,000 agents, 40 rounds): ~$8–20

gpt-4o-mini is the most cost-efficient option. Avoid gpt-4o for large simulations unless budget is not a concern.

Zep Cloud costs

The free tier at Zep Cloud includes a monthly episode quota that covers simple simulations. For heavy usage, paid plans start at around $20/month.

Hosted access (ThousandMinds)

Using ThousandMinds to run MiroFish in your browser costs €10/month — you bring your own API keys so there are no hidden LLM charges on top. Your API costs go directly to OpenAI/your chosen provider.

What can you use MiroFish for?

MiroFish is described as a tool that can "predict anything" — here are the most practical applications:

Public opinion simulation

Upload a news article or press release. Simulate how different population segments will react, which narratives will gain traction, and where polarization might emerge — before publishing.

Market sentiment analysis

Feed in a financial signal (earnings report, Fed announcement, regulatory change). Watch simulated traders, analysts, and retail investors react and predict how sentiment evolves.

PR crisis management

Test how your brand handles a crisis scenario in simulation before it happens. Adjust messaging strategies and see which responses de-escalate fastest.

Policy testing

Governments, think tanks, and researchers can simulate how a proposed policy change ripples through a population before implementation.

Marketing strategy

Upload a campaign brief and simulate how your target audience reacts before spending any budget.

Creative exploration

The MiroFish team famously fed the first 80 chapters of Dream of the Red Chamber (an 18th-century Chinese novel with a lost ending) and simulated how the story would conclude based on character behavior.

Frequently asked questions