MiroShark Builds a Digital Twin of Public Panic
A document goes in. Hundreds of agents, social platforms, and a prediction market come alive. Then the human operator can fork the timeline and test what happens when the story changes.
- MiroShark is most interesting as a counterfactual engine, not as an AI summarizer, because it lets a user change the story and rerun the world.
- The project’s backbone is a structured knowledge graph that turns raw text into roles, relationships, and action spaces before agents ever speak.
- Its simulation is richer than chat because social platforms and prediction markets are coupled, so discourse and stakes evolve together.
- Director Mode turns the system from a passive forecast into an instrument for crisis rehearsal, interview-style inspection, and timeline branching.
The part that matters is the rewind button
MiroShark’s most striking move is not that it simulates agents. It is that it lets you rewind a scenario, add a new event, and rerun the consequences. That makes it feel less like a chatbot and more like a crisis rehearsal engine.
That matters because the value is not in predicting a single answer. It is in watching a public system recompose itself when the facts change. The timeline fork is the product’s real thesis.
From a document to a living world
The repository’s architecture reflects that sequence. A text processor chunks the source material, named entity recognition extracts actors, and an ontology generator defines entity and edge types before simulation begins. In other words, the system builds structure first, then behavior.
# Conceptual pipeline used by the backend
chunks = TextProcessor().chunk(document)
entities = NERExtractor().extract(chunks)
ontology = OntologyGenerator().build(entities)
world_graph = Neo4jGraphBuilder().assemble(chunks, entities, ontology)
agents = SimulationManager().spawn_agents(world_graph)
results = SimulationRunner().run(agents)Why Neo4j is not just storage here
Neo4j is doing editorial work. It is not a passive database sitting behind the app. It defines who influences whom, which actors exist, which kinds of actions they can take, and how the simulation should branch when the world state changes.
| Layer | What it stores | What it enables |
|---|---|---|
| Document | Original scenario text | Source material for extraction |
| Graph | Entities, roles, relations, ontologies | World structure and influence paths |
| Simulation state | Round, platform status, agent actions | Reproducible runs and reruns |
| Director Mode | Injected events and interventions | Counterfactual branching |
Social media is only one layer
The simulation surfaces are separated on purpose. Twitter, Reddit, and Polymarket are not one blended feed. They are different channels with different incentives, different tempos, and different signals.
That distinction is the project’s real sophistication. Public chatter describes the world. Market pricing assigns stakes to it. MiroShark couples both, so the same event can produce outrage in one lane and repricing in another.
| Surface | Primary signal | Why it matters |
|---|---|---|
| Rapid reaction and amplification | Captures velocity and contagion | |
| Longer deliberation and thread structure | Shows argument formation | |
| Polymarket | Price discovery under uncertainty | Turns belief into stake |
| Director Mode | Injected counterfactuals | Tests how each surface rebalances |
MiroShark is a platform for exploring and implementing swarm intelligence algorithms. It provides tools for simulating and controlling swarms of agents, allowing them to collaborate and solve complex problems. The project aims to be a universal engine, adaptable to various domains.
Director Mode makes the operator part of the machine
The simulation manager and IPC client make room for mid-run intervention. That means the human is not just observing the model. The human can inject news, ask why an agent acted, and force the system to answer a different version of the same question.
That is a strong pattern for strategic work. It is also the point where MiroShark stops being a passive simulator and starts behaving like an instrument. The operator can conduct the scenario instead of merely watching it unfold.
How it compares to other swarm projects
MiroShark is not trying to be a robotics stack, a narrow swarm library, or a generic text agent wrapper. It is trying to be a universal engine for simulated discourse, social structure, and market feedback.
| Project | Primary focus | Counterfactual reruns | Social graph | Market layer |
|---|---|---|---|---|
| MiroShark | Simulated public reality | Yes | Yes | Yes |
| SwarmJS | Web-based swarm simulations | Limited | Partial | No |
| MASH | General multi-agent simulation | Possible | Partial | No |
| OpenSwarm | Robot swarm control | No | No | No |
What MiroShark is really selling
The commercial idea is not “AI agents.” It is a workflow for testing narratives before they break in public, stress-testing PR, and exploring how a rumor, a policy change, or a market shock propagates through a modeled crowd.
That is why the project feels bigger than its parts. Neo4j gives it structure. The simulation engine gives it motion. Director Mode gives it judgment. Together, they form a scenario engine for public reality.