README.md

June 22, 2026 · View on GitHub

MiroShark

MiroShark Demo

Simulate anything, for $1 & less than 10 min. Drop in anything — a press release, a news headline, a policy draft, a question you can't answer, a historical what-if — and MiroShark spawns hundreds of agents that react to it hour by hour. Posting, arguing, trading, changing their minds.

$Simulate anything — \$1 per simulation, 10 min first result, 100 agents: input → build world → swarm → report$

What it does

You bring a scenario. MiroShark builds the world around it.
Hundreds of grounded agents. Twitter, Reddit, and a prediction market. Hour by hour.
Chat with any of them. Drop breaking news mid-run. Fork the timeline.
Get a report on what happened, citing actual posts and trades.

MiroShark pipeline: Phase 1 Ontology Generation → Phase 2 Graph Building → Phase 3 Agent Setup → Phase 4 Simulation Execution → Phase 5 Report & Interaction

Quick start

The recommended path: one OpenRouter key + the ./miroshark launcher. First simulation in ~10 min, ~$1.

Prereqs — Python 3.11+, Node 18+, Neo4j, and an OpenRouter key.

Install Neo4j — the launcher starts it for you:

macOS — brew install neo4j
Linux — sudo apt install neo4j (or your distro's equivalent)
Windows — install Neo4j Desktop (native, GUI — start the DB there, then run the launcher from WSL2 or Git Bash), or run the whole stack inside WSL2 and follow the Linux steps
Zero-install — create a free Neo4j Aura cloud instance and point NEO4J_URI / NEO4J_PASSWORD at it in .env

Then:

git clone https://github.com/aaronjmars/MiroShark.git && cd MiroShark
cp .env.example .env
# Paste your OpenRouter key into the LLM_API_KEY / SMART_API_KEY /
# NER_API_KEY / OPENAI_API_KEY / EMBEDDING_API_KEY slots (same key,
# 5 places). Default lineup is Mimo V2.5 + Gemini 3 Flash.
./miroshark

The launcher checks dependencies, starts Neo4j, installs frontend + backend, and serves :3000 + :5001. Ctrl+C stops everything. Open http://localhost:3000 and drop in a document.

Other paths — one-click Railway / Render deploy, Docker + Ollama, manual Ollama, Claude Code CLI — all in docs/INSTALL.md.

MiroShark Overview

After launching, use the language selector in the top-right of the navbar to switch between English, 中文 (Chinese), DE (German), and FR (French). Your choice is persisted in the browser, and the public gallery card titles + descriptions follow the active locale.

Use cases

PR crisis testing — simulate public reaction to a press release before publishing
Market reaction — feed financial news and observe simulated trader + investor sentiment
Advertisement — test a campaign, headline, or pitch against a simulated audience before spending
Policy analysis — test draft regulations against a simulated public
Life decision — frame a personal decision (job move, relocation, launch timing) as a scenario and watch diverse personas argue it out
What-if history — rewrite a historical event and see how a population of personas re-narrates the aftermath
Creative experiments — feed a novel with a lost ending; agents write a narratively consistent conclusion

Five layers of grounding per agent: demographic seed, web enrichment, semantic search, relationships, graph attributes

Features

A few of the highlights:

Feature	What it does
Smart Setup	Drop in a doc → three auto-generated Bull / Bear / Neutral scenarios in ~2s
Just Ask	Type a question with no document — MiroShark researches and writes the seed briefing
Counterfactual Branching	Fork a running simulation with an injected event ("CEO resigns in round 24?")
Director Mode	Inject breaking news into the current timeline without forking
Per-Agent MCP Tools	Personas invoke real MCP tools (web search, APIs) during simulation
Article Generation	Substack-style write-up of what happened, grounded in actual posts and trades
Public Gallery & Verified Predictions	Browse and fork every published sim at `/explore`; track the calls that landed at `/verified`
Share everywhere	Social cards, replay GIFs, tweet threads, RSS / Atom, embeds, and Slack / Discord / Telegram / webhook notifications

…and 40+ more — share surfaces, exports, integrations, observability, and on-chain citation. See the full feature list and deep dives in docs/FEATURES.md.

Graph memory pipeline: ingestion (NER, embed, entity resolution, contradiction check, temporal edges) and retrieval (vector + BM25 + BFS, fused, reranked)

Documentation


Install	Every deployment path: cloud, Docker, Ollama, Claude Code
Configuration	Env vars, model routing, feature flags
Models	Cloud preset, local Ollama models, benchmark findings
Architecture	Simulation engine, memory pipeline, graph retrieval
Features	Deep dive on every feature in the table above
HTTP API	Every endpoint, grouped by concern — plus interactive Swagger UI at `/api/docs` and a spec at `/api/openapi.yaml`
CLI	`miroshark-cli` reference
MCP	Claude Desktop / Cursor / Windsurf / Continue integration + report agent tools (auto-generated snippets in Settings → AI Integration)
Webhooks	Completion webhook payload, headers, delivery semantics, Slack/Discord/Zapier/n8n recipes
DKG citation	OriginTrail DKG anchoring — UAL + Merkle root + on-chain citation key for any finished sim
WaybackClaw archive	WaybackClaw submission — snapshot id + IPFS CID + Nostr event id for any finished sim
Observability	Debug panel, event stream, logging
Ecosystem	Projects, agents, and products built on top of MiroShark
Contributing	Local setup, tests, PR conventions, and how to add an API endpoint

License

AGPL-3.0. See LICENSE.

Support the project: 0xd7bc6a05a56655fb2052f742b012d1dfd66e1ba3