A Simple and Universal Swarm Intelligence Engine, Predicting Anything

English | 中文文档

⚡ Overview

MiroFish is a next-generation AI prediction engine powered by multi-agent technology. By extracting seed information from the real world (such as breaking news, policy drafts, or financial signals), it automatically constructs a high-fidelity parallel digital world. Within this space, thousands of intelligent agents with independent personalities, long-term memory, and behavioral logic freely interact and undergo social evolution. You can inject variables dynamically from a "God's-eye view" to precisely deduce future trajectories — rehearse the future in a digital sandbox, and win decisions after countless simulations.

You only need to: Upload seed materials (data analysis reports or interesting novel stories) and describe your prediction requirements in natural language
MiroFish will return: A detailed prediction report and a deeply interactive high-fidelity digital world

Our Vision

MiroFish is dedicated to creating a swarm intelligence mirror that maps reality. By capturing the collective emergence triggered by individual interactions, we break through the limitations of traditional prediction:

• At the Macro Level: We are a rehearsal laboratory for decision-makers, allowing policies and public relations to be tested at zero risk
• At the Micro Level: We are a creative sandbox for individual users — whether deducing novel endings or exploring imaginative scenarios, everything can be fun, playful, and accessible

From serious predictions to playful simulations, we let every "what if" see its outcome, making it possible to predict anything.

🌐 Live Demo

Welcome to visit our online demo environment and experience a prediction simulation on trending public opinion events we've prepared for you: mirofish-live-demo

📸 Screenshots

🎬 Demo Videos

1. Wuhan University Public Opinion Simulation + MiroFish Project Introduction

Click the image to watch the complete demo video for prediction using BettaFish-generated "Wuhan University Public Opinion Report"

2. Dream of the Red Chamber Lost Ending Simulation

Click the image to watch MiroFish's deep prediction of the lost ending based on hundreds of thousands of words from the first 80 chapters of "Dream of the Red Chamber"

Financial Prediction, Political News Prediction and more examples coming soon...

🔄 Workflow

1. Graph Building: Seed extraction & Individual/collective memory injection & GraphRAG construction
2. Environment Setup: Entity relationship extraction & Persona generation & Agent configuration injection
3. Simulation: Dual-platform parallel simulation & Auto-parse prediction requirements & Dynamic temporal memory updates
4. Report Generation: ReportAgent with rich toolset for deep interaction with post-simulation environment
5. Deep Interaction: Chat with any agent in the simulated world & Interact with ReportAgent

🚀 Quick Start

Option 1: Docker Deployment (Recommended)

The Docker setup brings up the full stack — frontend, backend, and Neo4j — with a single command.

# 1. Copy and configure environment variables
cp .env.example .env
# Edit .env and fill in LLM_API_KEY (and Neo4j password if you want to override the default)

# 2. Pull images and start
docker compose up -d

Reads .env from the project root, exposes ports 3000 (frontend) and 5001 (backend).

A faster mirror address is provided as a comment inside docker-compose.yml; uncomment to use it.

Option 2: Source Code Deployment

Prerequisites

Tool	Version	Description	Check Installation
Node.js	18+	Frontend runtime, includes npm	node -v
Python	≥3.11, ≤3.12	Backend runtime	python --version
uv	Latest	Python package manager	uv --version
Neo4j	5.x Community	Local knowledge graph database	neo4j --version
Ollama	Latest	Local embedder host (default mxbai-embed-large)	ollama --version

Install Neo4j (choose one):

# macOS
brew install neo4j

# Linux (Debian/Ubuntu)
# See official docs: https://neo4j.com/docs/operations-manual/current/installation/linux/

# Windows / All platforms
# Download Neo4j Desktop: https://neo4j.com/download/

# Set password before first start, then launch
neo4j-admin dbms set-initial-password your_neo4j_password
neo4j start

Install Ollama and pull the default models:

# macOS / Linux: https://ollama.com/download
ollama pull mxbai-embed-large   # embedder for the knowledge graph
ollama pull qwen2.5:3b          # reranker for Graphiti search results
# Ollama serves the OpenAI-compatible /v1 endpoint on http://localhost:11434
# by default — no further configuration required.

If you prefer to run a remote embedder (OpenAI / Gemini), see the commented fallback block below; Ollama is the default but is not mandatory.

1. Configure Environment Variables

# Copy the example configuration file
cp .env.example .env

# Edit the .env file and fill in the required API keys

Required Environment Variables:

# LLM API Configuration (supports any LLM API with OpenAI SDK format)
# Recommended: Alibaba Qwen-plus model via Bailian Platform: https://bailian.console.aliyun.com/
# High consumption, try simulations with fewer than 40 rounds first
LLM_API_KEY=your_api_key
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus

# Knowledge Graph — local Neo4j + Graphiti (free, no rate limits)
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_neo4j_password

# Embeddings — default: local Ollama, free, no API key, OpenAI-compatible endpoint.
# Pre-requisite: `ollama pull mxbai-embed-large` (1024-dim, matches Graphiti).
# In Docker, host.docker.internal:11434 reaches the host daemon; in host mode
# (`npm run dev`) keep http://localhost:11434/v1 as below.
EMBEDDING_BASE_URL=http://localhost:11434/v1
EMBEDDING_API_KEY=ollama
EMBEDDING_MODEL=mxbai-embed-large

# Reranker — reorders Graphiti search results before the report tools see them.
# Default targets the same local Ollama host used for embeddings.
# Pre-requisite for the default: `ollama pull qwen2.5:3b`.
# Set RERANKER_PROVIDER=none to keep the legacy passthrough (useful for CI /
# slim containers that cannot pull a reranker model).
RERANKER_PROVIDER=ollama
RERANKER_MODEL=qwen2.5:3b
# Optional — both default to the EMBEDDING_* equivalents when unset.
# RERANKER_BASE_URL=http://localhost:11434/v1
# RERANKER_API_KEY=ollama

# Embeddings — remote fallback (uncomment ONE block if you prefer not to run
# Ollama locally). Note: any override must produce 1024-dim vectors to match
# Graphiti's vector index — 768-dim models (e.g. nomic-embed-text) are NOT
# supported.
#
# OpenAI:
# EMBEDDING_BASE_URL=https://api.openai.com/v1
# EMBEDDING_API_KEY=your_openai_api_key
# EMBEDDING_MODEL=text-embedding-3-small
#
# Gemini (set GRAPHITI_LLM_PROVIDER=gemini in this case):
# EMBEDDING_MODEL=gemini-embedding-001

Embedder smoke test (recommended before the first graph build):

curl -s "$EMBEDDING_BASE_URL/embeddings" \
  -H "Authorization: Bearer $EMBEDDING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"'"$EMBEDDING_MODEL"'","input":"ping"}' \
  | jq '.data[0].embedding | length'
# Expected output: 1024

Optional — Accelerated LLM Configuration:

If you have a faster/cheaper provider, you can route auxiliary calls through it. Omit these entirely if not used (do not leave placeholder values).

LLM_BOOST_API_KEY=your_api_key_here
LLM_BOOST_BASE_URL=your_base_url_here
LLM_BOOST_MODEL_NAME=your_model_name_here

Note: MiroFish has migrated from Zep Cloud to local Graphiti + Neo4j. No third-party knowledge-graph account is required — completely free with no rate limits.

2. Install Dependencies

# One-click installation of all dependencies (root + frontend + backend)
npm run setup:all

Or install step by step:

# Install Node dependencies (root + frontend)
npm run setup

# Install Python dependencies (backend, auto-creates virtual environment)
npm run setup:backend

3. Start Services

# Start both frontend and backend (run from project root)
npm run dev

Service URLs:

• Frontend: http://localhost:3000
• Backend API: http://localhost:5001

Start Individually:

npm run backend   # Start backend only
npm run frontend  # Start frontend only

📬 Join the Conversation

 

The MiroFish team is recruiting full-time/internship positions. If you're interested in multi-agent simulation and LLM applications, feel free to send your resume to: mirofish@shanda.com

📄 Acknowledgments

MiroFish has received strategic support and incubation from Shanda Group!

MiroFish's simulation engine is powered by OASIS (Open Agent Social Interaction Simulations), We sincerely thank the CAMEL-AI team for their open-source contributions!

📈 Project Statistics