MiroFish: Building Parallel Digital Worlds with Swarm Intelligence for Prediction
Hook
What if you could spawn thousands of AI agents with distinct personalities and memories, drop them into a digital world, and watch them predict election outcomes, market crashes, or how a lost Hemingway novel might have ended—all before running expensive real-world experiments?
Context
Traditional prediction models follow a reductionist approach: identify variables, establish relationships, run regressions, output forecasts. This works brilliantly for physics and reasonably well for economics, but falls apart when predicting complex social phenomena where emergent behavior dominates. How do you model a financial panic when it depends on thousands of traders’ evolving psychology? How do you forecast public opinion when individual beliefs shift through unpredictable social influence?
MiroFish tackles this by inverting the prediction paradigm. Instead of modeling the system mathematically, it recreates the system itself—spawning thousands of AI agents with distinct personalities, injecting them with relevant knowledge, and letting them interact in simulated time. The prediction emerges from the bottom up, just as real-world outcomes emerge from individual actions. Built on CAMEL-AI’s OASIS simulation engine and leveraging GraphRAG for knowledge modeling, MiroFish transforms any LLM into a swarm intelligence engine capable of simulating scenarios from policy impacts to creative storytelling outcomes.
Technical Insight
MiroFish’s architecture operates through five distinct stages that transform raw information into interactive predictions. The pipeline begins with knowledge graph construction using GraphRAG, which ingests seed data—documents, articles, historical records—and extracts a structured web of entities and relationships. This isn’t simple keyword extraction; GraphRAG creates multi-level abstractions that capture both explicit facts and implicit context.
Once the knowledge graph exists, MiroFish generates agent personas through entity analysis. If your seed data discusses a corporate merger, the system identifies stakeholders—executives, shareholders, regulators—and instantiates agents representing each. Each agent receives a personality profile and crucially, memory injection from the knowledge graph. This is where Zep Cloud enters: it provides persistent, queryable memory storage that agents can retrieve contextually during simulation. An agent representing a skeptical investor doesn’t just know facts; it remembers previous market crashes and maintains emotional continuity across simulation rounds.
The simulation core runs on OASIS, which handles parallel agent execution. Here’s a simplified example of how you might configure a basic simulation:
from mirofish import Simulation, Agent, KnowledgeGraph
# Build knowledge graph from seed data
kg = KnowledgeGraph.from_documents([
"company_merger_announcement.pdf",
"market_history_2020_2024.txt",
"stakeholder_interviews.json"
])
# Generate agents from entities
agents = kg.generate_agents(
num_agents=100,
diversity_factor=0.8, # Higher = more varied personalities
memory_depth="full" # Inject complete graph context
)
# Configure simulation parameters
sim = Simulation(
agents=agents,
environment="financial_market",
time_steps=50,
interaction_radius=0.3, # How broadly agents influence each other
memory_update_strategy="temporal" # Agents remember chronologically
)
# Run with cost controls
results = sim.run(
max_llm_calls=5000,
parallel_workers=8,
checkpoint_interval=10 # Save state every 10 rounds
)During simulation rounds, agents make decisions, communicate, and update their internal states. The temporal memory system is particularly clever: agents don’t just accumulate facts; they form narratives. An agent that “experiences” three rounds of declining stock prices develops a bearish sentiment that influences future decisions differently than an agent simply told “prices declined.” This emotional continuity creates realistic inertia and momentum effects absent in traditional models.
The fourth stage generates analysis through a specialized ReportAgent that observes the simulation with omniscient access. Unlike simulation agents constrained by their perspective, the ReportAgent sees all interactions, tracks emergent patterns, and synthesizes predictions. It can identify when agent clusters form opinion bubbles, detect cascade effects before they propagate, and highlight counterfactual branches where small changes yield divergent outcomes.
Finally, MiroFish offers post-simulation interaction through a Node.js frontend. You can query individual agents about their reasoning, inject new variables mid-simulation to test “what if” scenarios, or rewind and branch simulations from checkpoints. This “god view” transforms predictions from static outputs into interactive explorations. Want to know how the merger prediction changes if a key executive resigns? Inject that event at round 15 and compare trajectories.
The system’s power lies in emergent complexity from simple rules. Individual agents follow straightforward logic—retrieve relevant memories, assess situation, make decision, update memories. But thousands of agents interacting across dozens of rounds produce sophisticated collective behavior: herding, contrarian movements, information cascades, and consensus formation. These patterns aren’t programmed; they emerge organically from the swarm architecture.
Gotcha
The most immediate limitation is cost. MiroFish documentation explicitly warns users about LLM API consumption, recommending starting with fewer than 40 simulation rounds. With 100 agents and 50 time steps, you’re looking at thousands of LLM calls. At $0.002 per 1K tokens for GPT-4o-mini input (a conservative choice), a modest simulation easily burns through $20-50. Complex scenarios with hundreds of agents and detailed reasoning can cost orders of magnitude more. The system includes checkpoint saves and cost monitoring, but there’s no getting around the fundamental economics: simulating intelligence at scale requires compute at scale.
Dependency on external services creates operational fragility. Zep Cloud handles memory management, which is essential for agent continuity, but you’re locked into their infrastructure and pricing. The free tier supports basic experimentation, but production use requires paid plans. Similarly, the system assumes OpenAI-compatible LLM APIs, and while many providers offer this interface, performance varies dramatically. Cheaper models produce less coherent agent behavior; premium models multiply costs. There’s limited guidance on model selection trade-offs, leaving users to discover through expensive trial and error that GPT-3.5 creates shallow simulations while GPT-4 makes them prohibitively expensive.
Validation remains an open question. How do you know your simulation accurately predicts reality? MiroFish provides no built-in calibration tools or validation metrics. You can run historical scenarios and compare outcomes, but cherry-picking successful predictions while ignoring failures is easy. The Chinese-first documentation makes evaluation harder for English speakers, as many examples and case studies lack translation. This limits critical assessment of when the tool genuinely outperforms traditional forecasting versus when it simply provides expensive confirmation bias.
Verdict
Use MiroFish if you’re modeling scenarios where collective behavior and emergent dynamics matter more than individual precision—public opinion shifts, market sentiment contagion, organizational culture changes, or policy impacts with multiple stakeholders. The tool excels when traditional models fail because the system itself is the insight, not just the output. It’s particularly valuable for decision-makers who can afford exploration costs and need to test high-stakes strategies in risk-free environments before committing resources. Skip it if you need deterministic predictions with confidence intervals, have limited LLM budgets (under $100/month for experimentation), require only single-agent or simple cause-effect analysis, or work in regulated industries demanding explainable, auditable forecasts. The complexity and cost are justified only when emergent swarm intelligence reveals patterns that reductionist models cannot capture—and when you can tolerate the occasional expensive hallucination in exchange for potentially breakthrough insights.
