What if you could see how the internet would react to your press release before you published it? Or stress-test a policy draft against a simulated public? Or feed financial news to hundreds of AI agents and watch sentiment evolve in real time?
That's what MiroShark does. It's a swarm intelligence engine — upload a document, get hundreds of AI personas arguing about it on a simulated social network, hour by hour.
What's Actually Happening Under the Hood
The pipeline has four stages:
1. Graph Build — Your document gets parsed into a Neo4j knowledge graph. Entities, relationships, key claims — all extracted and stored with per-agent memory attached.
2. Agent Setup — The system generates hundreds of personas. Each one gets a unique personality, opinion bias, reaction speed, and influence level. Not clones — a distribution of archetypes that mirrors how real populations fragment around a topic.
3. Simulation — Agents post, reply, argue, and shift opinions across simulated social platforms. Sentiment evolves. Influence dynamics play out. You can watch it run, pause it, restart it.
4. Report — A ReportAgent analyzes the full simulation, interviews a focus group of agents, and generates a structured analysis. Cached, so you're not re-running expensive inference every time you pull it up.
There's also a persona chat feature — click any agent, see their full profile and simulation history, and ask them questions directly.
The Stack
- Neo4j — knowledge graph and agent memory
- Any OpenAI-compatible API — inference. OpenRouter, OpenAI, Anthropic, or local Ollama. The engine doesn't care.
- Python 3.11+ backend, Vue frontend
The local-first design is the key architectural choice here. You don't need cloud anything — the Docker compose setup spins up Neo4j, Ollama, and the app together. If you have the VRAM, the whole thing runs on your machine.
Getting Started
Cloud API path (no GPU needed):
# Start Neo4j
docker run -d --name neo4j \
-p 7474:7474 -p 7687:7687 \
-e NEO4J_AUTH=neo4j/miroshark \
neo4j:5.15-community
cp .env.example .env
# Edit .env with your API key
npm run setup:all && npm run dev
A .env using OpenRouter looks like:
LLM_API_KEY=sk-or-v1-your-key
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_MODEL_NAME=qwen/qwen3-235b-a22b-2507
EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=openai/text-embedding-3-small
EMBEDDING_BASE_URL=https://openrouter.ai/api
EMBEDDING_API_KEY=sk-or-v1-your-key
EMBEDDING_DIMENSIONS=768
Full local path (Docker):
git clone https://github.com/aaronjmars/MiroShark.git
cd MiroShark
docker compose up -d
docker exec miroshark-ollama ollama pull qwen3.5:27b
docker exec miroshark-ollama ollama pull nomic-embed-text
Open http://localhost:3000. That's it.
Picking a Model
A typical simulation runs ~40 turns across 100+ agents. Model choice is a real decision here because you're paying it per agent per turn.
Cloud (via OpenRouter):
| Model | Cost/sim | Notes |
|---|---|---|
| Qwen3 235B A22B ⭐ | ~$0.30 | Best overall |
| GPT-5 Nano | ~$0.41 | Budget option |
| Gemini 2.5 Flash Lite | ~$0.58 | Good alt |
| DeepSeek V3.2 | ~$1.11 | Stronger reasoning |
$0.30 for a full 100-agent simulation is genuinely cheap for what you're getting.
Local (Ollama):
One important gotcha: Ollama defaults to 4096 token context, but MiroShark prompts need 10–30k. You need a custom Modelfile:
printf 'FROM qwen3:14b\nPARAMETER num_ctx 32768' > Modelfile
ollama create mirosharkai -f Modelfile
Hardware quick-pick:
| Setup | Model |
|---|---|
| RTX 3090/4090 or M2 Pro 32GB+ | qwen3.5:27b |
| RTX 4080 / M2 Pro 16GB | qwen3.5:35b-a3b (MoE, fastest) |
| RTX 4070 / M1 Pro | qwen3:14b |
| 8GB VRAM / laptop | qwen3:8b |
The hybrid approach the docs recommend is smart: run local for simulation rounds (high-volume, lower stakes), route to a cloud model only for final report generation. That's where quality matters most and the call count is low.
What You Can Actually Use This For
PR crisis testing — draft a press release, run the simulation, see where it catches fire before it's live. The agent distribution will surface objections you didn't anticipate.
Policy analysis — feed a regulatory draft to the engine. Watch how different demographic archetypes react, where opposition coalesces, what framing lands.
Trading signals — feed financial news and observe simulated market sentiment evolution. Not a trading bot, but a structured way to pressure-test a thesis against a synthetic crowd.
Creative experiments — the one the README buries in the list but is maybe the most interesting: feed a novel with a lost ending and let agents write a narratively consistent conclusion. The social simulation framing makes it weirder and more interesting than a straight "complete this story" prompt.
The Architecture Decision Worth Noting
MiroShark uses Neo4j for agent memory, not a vector database. This is a deliberate choice — graph structure lets you model relationships between agents, not just retrieve relevant context per agent. Who influenced whom. How opinion clusters formed. Which agents are high-influence nodes.
The ReportAgent at the end leans on this. It's not just summarizing sentiment — it's analyzing the graph of how influence propagated through the simulation.
Hardware Requirements
| Minimum | Recommended | |
|---|---|---|
| RAM | 16 GB | 32 GB |
| VRAM (local) | 10 GB | 24 GB |
| Disk | 20 GB | 50 GB |
Cloud mode: no GPU. Neo4j plus an API key on any 4 GB RAM machine.
Credits
MiroShark is built on MiroFish by 666ghj (Shanda Group), with a local Neo4j + Ollama storage layer adapted from MiroFish-Offline by nikmcfly. The simulation engine is powered by OASIS from CAMEL-AI.
Bottom Line
The interesting thing about MiroShark isn't that it simulates public opinion — it's that it simulates how opinion moves. The graph layer lets you see influence dynamics, not just a sentiment score. A tool that outputs "60% negative" is less useful than one that shows you which agent archetypes went negative first and who they pulled with them.
For anyone doing comms, policy, research, or market analysis, the $0.30/simulation price point on cloud makes this worth running on basically anything before it goes public.
Top comments (0)