MiroShark: The Swarm Engine That Forks Public Reality

A Scenario Engine for Public Reality

MiroShark is not trying to be a chatty demo of synthetic people. Its real trick is that a seed, like a press release or policy draft, becomes a living social world with memory, incentives, and a timeline you can split. That makes it feel less like a chatbot swarm and more like a playtest engine for public reaction.

That framing matters because it changes the question. Instead of asking whether an LLM can imitate a person, MiroShark asks whether a scenario can be rehearsed before it escapes into the real world. For PR, policy, and market narrative work, that is the more useful test.

Why the Fork Matters

The most interesting mechanic in the repo is the fork. A simulation can run forward, absorb a breaking event, then split into alternate futures. That is a counterfactual machine, not just a feed generator.

That is why the project is more interesting than a single-run sentiment simulator. It can show how the same seed reacts under a new shock, then preserve both branches for comparison. In practice, that makes the timeline itself part of the product.

Grounded Agents, Not Free-Form Personas

The repo leans on a graph-first memory model. Source text is chunked, entities are extracted, and a Neo4j-backed world model holds the relationships. Agents then inherit that structure, which keeps them anchored to the seed instead of drifting into generic roleplay.

The important distinction is not that agents get prompts. It is that they get a world model. That world model is what lets a reaction feel informed, inconsistent, or sudden for a reason instead of because the model was improvising.

How a Simulation Run Actually Works

At a high level, the flow is straightforward: ingest the seed, build the graph, generate personas, run rounds, track actions, and emit a report. The repo’s services make that sequence explicit, especially around SimulationState, the runner, and tracked AgentAction events.

# Simplified lifecycle
state = SimulationState(seed=doc)
graph = GraphBuilderService.build(doc)
personas = SimulationManager.generate_profiles(graph)
run = SimulationRunner.start(personas)

while run.active:
    actions = run.step()
    state.record(actions)
    if breaking_news:
        run.fork(new_event)

report = run.finalize()

1. Seed text is normalized and turned into a graph of entities and claims.
2. Persona generation uses that graph to create grounded agents with distinct viewpoints.
3. The runner advances the simulation in rounds across Twitter, Reddit, and Polymarket.
4. Each action is recorded so the run can be inspected, replayed, or forked.

That structure is what makes the system legible. You can see where a run begins, where it changes, and what each agent did in between. For a simulation product, that audit trail is half the value.

Why Polymarket Changes the Story

Prediction markets turn the simulation into something more than social theater. Agents are not only expressing beliefs. They are also responding to price, implied conviction, and uncertainty.

That market layer is the difference between a simulation of opinions and a simulation of incentives. Prices make certainty visible. They also give the agents something to react to when the narrative starts to move.

Trace Interviews Turn the Swarm Into an Investigable System

The trace interview feature is the observability layer that keeps this from becoming mystical. You can ask why an agent acted, what it believed, and how that belief changed over time. In other words, the swarm is not only generative. It is inspectable.

That matters for trust. If a simulation is going to inform a decision, you need a way to examine its internal story, not just its output. Trace interviews make the system useful as evidence, not just as entertainment.

What MiroShark Is Really Replacing

MiroShark is not a survey tool with a new coat of paint. It is closer to a dynamic rehearsal space for narratives, with memory, incentives, and reversible history. That puts it in a different category from focus groups, single-platform sentiment tracking, or naive persona prompts.

That is the real thesis. MiroShark does not promise truth. It gives you a faster, more structured way to ask how truth might travel once people, feeds, and markets start responding to it. In some domains, that is the question that matters.