MiroFish: Rehearsing the Future in an AI Social Sandbox

Predicting the future has always been a game of statistics - until now. MiroFish introduces a paradigm shift by moving from “predictive modeling” to “social simulation.”

Part 1: Foundations (The Mental Model)

To understand MiroFish, you must stop thinking of AI as a calculator and start thinking of it as a Digital Sandbox.

In the real world, events aren’t just data points; they are the result of thousands of individual interactions. MiroFish acts as a Swarm Intelligence Mirror. It takes seed information (like a news report or a policy draft) and creates a “Mirror World” populated by intelligent agents.

The mental model is simple: Don’t just calculate the outcome; simulate the players.

Part 2: The Investigation

MiroFish isn’t just a single model; it’s a sophisticated engine that bridges the gap between raw information and social evolution. It stands on two primary pillars:

1. High-Fidelity Parallel Worlds: By extracting entities and relationships from seed materials, it builds a specialized GraphRAG (powered by Zep) that serves as the collective memory of the simulation.
2. Autonomous Social Interaction: Using the OASIS (Open Agent Social Interaction Simulations) engine, MiroFish populates its digital sandbox with thousands of agents, each with independent personalities, long-term memory, and behavioral logic.

These agents don’t just exist; they interact, form opinions, and undergo social evolution in real-time.

Part 3: The Diagnosis

For developers and decision-makers, MiroFish solves the “What If” problem by providing a God’s-eye view of potential futures.

Deep Dive: How it works for Python Developers

The backend is built with Python, leveraging modern tools like uv for lightning-fast dependency management. The workflow is automated:

• Graph Building: Extracts seed info and injects collective memory into a GraphRAG.
• Environment Setup: Generates personas and agent configurations based on the seed data.
• Simulation: Runs dual-platform parallel simulations (e.g., mimicking Twitter or Reddit interactions) using the OASIS engine.
• Report Generation: A dedicated ReportAgent analyzes the simulation’s results to provide a detailed prediction report.

Real Use-Cases

• Public Opinion Simulation: “How will the public react to this new policy?”
• Creative Sandbox: “What would happen if the characters in ‘Dream of the Red Chamber’ made different choices?”
• Financial/Political Signals: Testing the ripple effects of macro-economic signals in a controlled environment.

# A glimpse into how MiroFish manages simulations (simplified)
class SimulationRunner:
    def start_simulation(self, simulation_id: str, platform: str = "parallel"):
        # Initializes the OASIS engine and starts the social sandbox
        process = subprocess.Popen(
            [sys.executable, "run_parallel_simulation.py", "--config", config_path],
            cwd=sim_dir,
            env=env
        )
        # Monitor real-time agent actions...

Part 4: The Resolution

Getting started with MiroFish is straightforward, provided you have the right keys (OpenAI-compatible API and Zep).

1. Clone the Repo: git clone https://github.com/666ghj/MiroFish.
2. Setup Environment: Configure your .env with LLM_API_KEY and ZEP_API_KEY.
3. One-Click Install: Run npm run setup:all to install frontend and backend dependencies.
4. Launch the World: Use npm run dev to start both services and access the dashboard at localhost:3000.

Final Mental Model

MiroFish = Seed Materials + Multi-Agent Personas + Social Evolution.

It is a rehearsal laboratory where policies, public relations, and creative ideas can be tested at zero risk. By letting every “what if” see its outcome in a digital mirror, MiroFish makes it possible to predict anything by simply watching it happen.