Introduction
You’ve seen it happen. A company announces a new policy. A celebrity makes a controversial statement. A news story breaks that nobody expected. Social media explodes, and the consequences ripple outward in ways nobody predicted.
What if you could see how a scenario plays out before it happens in the real world?
MiroFish is a multi-agent AI simulation platform that answers “what if” questions about social media. It creates a digital parallel world where hundreds of AI agents with distinct personalities, memories, and behavioral patterns interact freely. You upload seed material—a news article, a policy draft, a research paper—and MiroFish simulates how different audiences might react over time.
This explainer covers what MiroFish does, how multi-agent simulation works, and when you might use it.
What Problem Does MiroFish Solve?
The Prediction Gap
Social media moves fast and reacts in unpredictable ways. Traditional analysis tools look backward:
- Sentiment analysis tells you what people think now
- Trend monitoring shows you what’s popular today
- Engagement metrics measure what already happened
None of these help you see what might happen if you publish that announcement, release that report, or respond to that controversy.
The Alternative: Digital Parallel Worlds
MiroFish takes a different approach. Instead of analyzing real social media, it creates a simulated version:
- Build a knowledge graph from your source documents
- Extract entities (people, organizations, media outlets) and turn them into AI agents
- Assign personalities based on extracted information (activity levels, influence weights, stance positions)
- Run a simulation where agents post, comment, and react over simulated hours or days
- Analyze the outcome to see how narratives form, which voices dominate, and what counter-movements emerge
Think of it as a flight simulator for social media scenarios.
How MiroFish Works: The Five-Step Workflow
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Step 1 │ ──► │ Step 2 │ ──► │ Step 3 │ ──► │ Step 4 │ ──► │ Step 5 │
│ Ontology │ │ GraphRAG │ │ Env │ │ Simulation │ │ Report │
│ Generation │ │ Build │ │ Setup │ │ Run │ │ Generation │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
Step 1: Ontology Generation
The system analyzes your input documents and simulation requirements, then uses an LLM to generate a custom ontology. This defines:
- 10 entity types (e.g., Student, Professor, University, MediaOutlet, GovernmentAgency)
- 10 relationship types (e.g., WORKS_FOR, COMMENTS_ON, RESPONDS_TO)
- Attributes for each type
The ontology enforces a two-tier structure: 8 specific types based on your content, plus 2 fallback types (Person and Organization) to catch anything that doesn’t fit elsewhere.
Step 2: GraphRAG Construction
Your documents get chunked (500 characters with 50-character overlap) and sent to Zep Cloud in batches. The system:
- Creates a standalone graph with a unique ID
- Sets the custom ontology
- Sends text batches for entity and relationship extraction
- Waits for Zep to process each episode
- Retrieves the final graph with nodes and edges
The result: a knowledge graph with hundreds or thousands of entities connected by relationships.
Step 3: Environment Setup
The simulation config generator analyzes the knowledge graph and creates detailed agent parameters:
- Time configuration based on Chinese timezone patterns (peak hours 19-22, dead hours 0-5)
- Event configuration with initial posts and hot topics
- Agent activity configs (posts per hour, response delays, influence weights)
- Platform configs for Twitter and Reddit with different viral thresholds
Step 4: Simulation Run
Agents wake up according to their activity schedules and start posting, commenting, and reacting. The system runs parallel simulations on Twitter and Reddit, logging every action to JSONL files in real-time.
A typical 72-hour simulation generates thousands of actions across both platforms.
Step 5: Report Generation
The Report Agent uses three core retrieval tools to analyze what happened:
- InsightForge: Deep-dive search that decomposes questions into sub-queries
- PanoramaSearch: Full-scope view including expired/invalid historical facts
- InterviewAgents: Real-time interviews with active agents via IPC
The final report shows narrative evolution, key moments, influential voices, and counter-movements.
What Are AI Agents in MiroFish?
Each agent in MiroFish is an independent AI entity with:
| Attribute | Description | Example |
|---|---|---|
| Identity | Name, username, bio | “@ZhangWei_Student” |
| Persona | Personality and background | “Graduate student researching AI ethics” |
| Activity Level | How often they post (0.0-1.0) | 0.8 = very active |
| Active Hours | When they’re online | [8, 9, 10, 11, 18, 19, 20, 21, 22, 23] |
| Response Delay | How fast they react (minutes) | 5-30 min |
| Influence Weight | How likely others are to see their posts | 0.8 (low) to 3.0 (high) |
| Stance | Position on topics | Supportive, opposing, neutral, observer |
| Memory | Past actions and interactions | Stored in Zep Cloud graph |
Agents make decisions autonomously. They choose when to post, what to comment on, and how to respond based on their personality and the current state of the simulation.
What Can You Simulate?
News and Policy Announcements
Upload a policy draft or news article. See how different stakeholder groups react:
- Which voices amplify the message?
- What criticisms emerge?
- How do narratives evolve over 24-72 hours?
Academic Research
Upload a research paper. Simulate academic and public reception:
- Which findings get attention?
- What misunderstandings arise?
- How do expert and layperson responses differ?
Crisis Scenarios
Upload incident reports or background materials. Test response strategies:
- How does the narrative shift if you respond immediately vs. wait?
- What counter-narratives emerge?
- Which influencers drive the conversation?
Literary and Historical Analysis
Upload a novel or historical text. Explore “what if” scenarios:
- How might characters react to events beyond the original ending?
- What alternative outcomes are plausible?
- Which relationships drive key plot points?
What Makes MiroFish Different?
Swarm Intelligence, Not Single Agents
Many AI tools use a single agent to simulate “a user.” MiroFish uses hundreds of agents with distinct personalities. This creates emergent behavior—narratives and movements that arise from interactions, not pre-programmed scripts.
Dual-Platform Simulation
Twitter and Reddit run in parallel with different dynamics:
- Twitter: Fast viral spread, high influencer impact
- Reddit: Threaded discussions, community-driven narratives
Comparing both platforms shows how platform mechanics affect outcomes.
Temporal Knowledge Graph
Relationships in MiroFish have time metadata:
valid_at: When the relationship became validinvalid_at: When it became invalidexpired_at: When it was superseded
This lets you track how relationships evolve, not just the current state.
Live Agent Interviews
You can interview active agents during or after the simulation:
Question: “What do you think about the university’s response?”
Agent 12 (Student): [Twitter] “They waited too long. By the time they responded, the narrative had already solidified.” [Reddit] “I get why they hesitated—legal review takes time. But the delay cost them credibility.”
This provides qualitative insights beyond quantitative metrics.
Technical Architecture at a Glance
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Frontend │ │ Backend │ │ External │
│ (Vue.js) │ ◄─► │ (FastAPI) │ ◄─► │ Services │
│ │ │ │ │ │
│ - Graph builder │ │ - REST API │ │ - Zep Cloud │
│ - Simulation │ │ - Subprocess │ │ - LLM API │
│ monitor │ │ management │ │ - OASIS │
│ - Report viewer │ │ - JSONL stream │ │ Framework │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Backend Stack
- Python FastAPI for REST endpoints
- OASIS Framework for agent simulation
- Zep Cloud for knowledge graph storage and retrieval
- SQLite for simulation state databases
Frontend Stack
- Vue.js 3 for reactive UI
- WebSocket for real-time updates
- D3.js for graph visualization
API Design with Apidog
The MiroFish backend exposes 40+ endpoints across 5 major services:
| Service | Endpoints | Purpose |
|---|---|---|
| Graph Build | 8 | Ontology generation, batch upload, status polling |
| Entity Reader | 4 | Entity filtering, type selection, export |
| Config Generator | 6 | Time/event/agent/platform config generation |
| Simulation Runner | 12 | Start, stop, monitor, interview, state management |
| Report Generator | 5 | Retrieval, analysis, summary generation |
Apidog was used to design all endpoints, mock responses for frontend development, and generate API documentation. This caught schema mismatches early and kept the team aligned throughout development.
When Should You Use MiroFish?
Good Use Cases
- Scenario planning: “What if we announce X next week?”
- Stakeholder analysis: “How will different groups react to Y?”
- Narrative tracking: “What counter-arguments emerge against Z?”
- Research validation: “Do our hypotheses about audience behavior hold up?”
- Educational exploration: “How might these historical figures respond to modern events?”
Not Good Use Cases
- Precise prediction: MiroFish shows plausible outcomes, not guaranteed futures
- Real-time monitoring: It simulates hypothetical scenarios, doesn’t track live social media
- Small-scale analysis: The system shines with hundreds of agents; overkill for simple surveys
- Non-social phenomena: It models social media dynamics, not economic or physical systems
Getting Started with MiroFish
Requirements
- Python 3.10+
- Node.js 18+
- Zep Cloud API key
- LLM API access (OpenAI-compatible)
Quick Start
# Clone the repository
git clone https://github.com/666ghj/MiroFish.git
cd MiroFish
# Install dependencies
pip install -r requirements.txt
npm install
# Configure environment
cp .env.example .env
# Edit .env with your API keys
# Start the backend
python backend/app/main.py
# Start the frontend
npm run dev
First Simulation
- Upload documents: PDF, TXT, or MD files containing your source material
- Define simulation requirements: What question are you exploring?
- Generate ontology: Let the system analyze and propose entity types
- Build knowledge graph: Extract entities and relationships
- Configure and run: Set simulation duration and start
- Monitor and interview: Watch actions in real-time, interview agents
- Generate report: Get a summary of what happened
A typical first simulation takes 30-60 minutes end-to-end.
Frequently Asked Questions
How accurate are the simulations?
MiroFish generates plausible scenarios based on input data and behavioral models. Think of it as exploring possibility space, not predicting specific outcomes. The value lies in surfacing dynamics you might not have anticipated.
How many agents can MiroFish simulate?
The system handles 50-200 agents comfortably. Larger simulations (500+) are possible but require more compute and take longer to process.
Can I customize agent behavior?
Yes. You can modify activity patterns, influence weights, and stance distributions. Advanced users can edit agent configs directly before running simulations.
Does MiroFish support non-Chinese scenarios?
The default timezone config is optimized for Chinese social media behavior. You can customize activity patterns for other regions by modifying the time configuration.
Is my data private?
Documents are processed locally and sent to Zep Cloud for entity extraction. Zep retains data according to their terms of service. For sensitive materials, consider using a local graph database alternative.
Conclusion
MiroFish creates digital parallel worlds where you can test social media scenarios before they happen in the real world. By simulating hundreds of AI agents with distinct personalities and behavioral patterns, it reveals emergent narratives, counter-movements, and influential voices that traditional analysis tools miss.
Whether you’re planning a policy announcement, researching audience behavior, or exploring literary “what ifs,” MiroFish offers a new lens for understanding complex social dynamics.
