What is this?

MiroFish is a multi-agent simulation engine: upload any document (press release, policy draft, financial report), and it generates hundreds of AI agents with unique personalities that simulate the public reaction on social media. Posts, arguments, opinion shifts — hour by hour.

The original MiroFish was built for the Chinese market (Chinese UI, Zep Cloud for knowledge graphs, DashScope API). This fork makes it fully local and fully English:

Original MiroFish	MiroFish-Offline
Chinese UI	English UI (1,000+ strings translated)
Zep Cloud (graph memory)	Neo4j Community Edition 5.15
DashScope / OpenAI API (LLM)	Ollama (qwen2.5, llama3, etc.)
Zep Cloud embeddings	nomic-embed-text via Ollama
Cloud API keys required	Zero cloud dependencies

Workflow

1. Graph Build — Extracts entities (people, companies, events) and relationships from your document. Builds a knowledge graph with individual and group memory via Neo4j.
2. Env Setup — Generates hundreds of agent personas, each with unique personality, opinion bias, reaction speed, influence level, and memory of past events.
3. Simulation — Agents interact on simulated social platforms: posting, replying, arguing, shifting opinions. The system tracks sentiment evolution, topic propagation, and influence dynamics in real time.
4. Report — A ReportAgent analyzes the post-simulation environment, interviews a focus group of agents, searches the knowledge graph for evidence, and generates a structured analysis.
5. Interaction — Chat with any agent from the simulated world. Ask them why they posted what they posted. Full memory and personality persists.

Screenshot

Quick Start

Prerequisites

• Docker & Docker Compose (recommended), or
• Python 3.11+, Node.js 18+, Neo4j 5.15+, Ollama

Option A: Docker (easiest)

git clone https://github.com/nikmcfly/MiroFish-Offline.git
cd MiroFish-Offline
cp .env.example .env

# Start all services (Neo4j, Ollama, MiroFish)
docker compose up -d

# Pull the required models into Ollama
docker exec mirofish-ollama ollama pull qwen2.5:32b
docker exec mirofish-ollama ollama pull nomic-embed-text

Open http://localhost:3000 — that's it.

Option B: Manual

1. Start Neo4j

docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/mirofish \
  neo4j:5.15-community

2. Start Ollama & pull models

ollama serve &
ollama pull qwen2.5:32b      # LLM (or qwen2.5:14b for less VRAM)
ollama pull nomic-embed-text  # Embeddings (768d)

3. Configure & run backend

cp .env.example .env
# Edit .env if your Neo4j/Ollama are on non-default ports

cd backend
pip install -r requirements.txt
python run.py

4. Run frontend

cd frontend
npm install
npm run dev

Open http://localhost:3000.

Configuration

All settings are in .env (copy from .env.example):

# LLM — points to local Ollama (OpenAI-compatible API)
LLM_API_KEY=ollama
LLM_BASE_URL=http://localhost:11434/v1
LLM_MODEL_NAME=qwen2.5:32b

# Neo4j
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=mirofish

# Embeddings
EMBEDDING_MODEL=nomic-embed-text
EMBEDDING_BASE_URL=http://localhost:11434

Works with any OpenAI-compatible API — swap Ollama for Claude, GPT, or any other provider by changing LLM_BASE_URL and LLM_API_KEY.

Architecture

This fork introduces a clean abstraction layer between the application and the graph database:

┌─────────────────────────────────────────┐
│              Flask API                   │
│  graph.py  simulation.py  report.py     │
└──────────────┬──────────────────────────┘
               │ app.extensions['neo4j_storage']
┌──────────────▼──────────────────────────┐
│           Service Layer                  │
│  EntityReader  GraphToolsService         │
│  GraphMemoryUpdater  ReportAgent         │
└──────────────┬──────────────────────────┘
               │ storage: GraphStorage
┌──────────────▼──────────────────────────┐
│         GraphStorage (abstract)          │
│              │                            │
│    ┌─────────▼─────────┐                │
│    │   Neo4jStorage     │                │
│    │  ┌───────────────┐ │                │
│    │  │ EmbeddingService│ ← Ollama       │
│    │  │ NERExtractor   │ ← Ollama LLM   │
│    │  │ SearchService  │ ← Hybrid search │
│    │  └───────────────┘ │                │
│    └───────────────────┘                │
└─────────────────────────────────────────┘
               │
        ┌──────▼──────┐
        │  Neo4j CE   │
        │  5.15       │
        └─────────────┘

Key design decisions:

• GraphStorage is an abstract interface — swap Neo4j for any other graph DB by implementing one class
• Dependency injection via Flask app.extensions — no global singletons
• Hybrid search: 0.7 × vector similarity + 0.3 × BM25 keyword search
• Synchronous NER/RE extraction via local LLM (replaces Zep's async episodes)
• All original dataclasses and LLM tools (InsightForge, Panorama, Agent Interviews) preserved

Hardware Requirements

Component	Minimum	Recommended
RAM	16 GB	32 GB
VRAM (GPU)	10 GB (14b model)	24 GB (32b model)
Disk	20 GB	50 GB
CPU	4 cores	8+ cores

CPU-only mode works but is significantly slower for LLM inference. For lighter setups, use qwen2.5:14b or qwen2.5:7b.

Use Cases

• PR crisis testing — simulate the public reaction to a press release before publishing
• Trading signal generation — feed financial news and observe simulated market sentiment
• Policy impact analysis — test draft regulations against simulated public response
• Creative experiments — someone fed it a classical Chinese novel with a lost ending; the agents wrote a narratively consistent conclusion

License

AGPL-3.0 — same as the original MiroFish project. See LICENSE.

Credits & Attribution

This is a modified fork of MiroFish by 666ghj, originally supported by Shanda Group. The simulation engine is powered by OASIS from the CAMEL-AI team.

Modifications in this fork:

• Backend migrated from Zep Cloud to local Neo4j CE 5.15 + Ollama
• Entire frontend translated from Chinese to English (20 files, 1,000+ strings)
• All Zep references replaced with Neo4j across the UI
• Rebranded to MiroFish Offline