MiroFish-Offline
Fully local fork of MiroFish — no cloud APIs required. English UI.
A multi-agent swarm intelligence engine that simulates public opinion, market sentiment, and social dynamics. Entirely on your hardware.
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
- Graph Build — Extracts entities (people, companies, events) and relationships from your document. Builds a knowledge graph with individual and group memory via Neo4j.
- Env Setup — Generates hundreds of agent personas, each with unique personality, opinion bias, reaction speed, influence level, and memory of past events.
- 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.
- 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.
- 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:
GraphStorageis 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