{ "markdown": "
\n\n\"DeepMiro\"\n\n
\n\n**A swarm intelligence engine that rehearses the future.**\n\nFeed it a document. Describe a scenario. Watch hundreds of AI agents with distinct personalities, memories, and social instincts interact — and return with a prediction.\n\n[![License](https://img.shields.io/badge/License-AGPL--3.0-blue?style=flat-square)](./LICENSE)\n[![npm](https://img.shields.io/npm/v/deepmiro-mcp?style=flat-square&label=npm&color=22d3ee)](https://www.npmjs.com/package/deepmiro-mcp)\n[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=flat-square&logo=docker&logoColor=white)](#rehearse-the-future-in-60-seconds)\n[![Website](https://img.shields.io/badge/deepmiro.org-live-22d3ee?style=flat-square)](https://deepmiro.org)\n\n
\n\n[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/98AO1I?referralCode=pYCUQd&utm_medium=integration&utm_source=template&utm_campaign=generic)\n\nOne-click self-host — four services, one API key, ~60 seconds. Full walkthrough ↓\n\n
\n\n---\n\n## Contents\n\n- [What It Does](#what-it-does)\n- [How It Works](#how-it-works)\n- [Quick Start](#quick-start) — get an API key, install in 2 min\n- [Self-Host (Docker / Railway)](#rehearse-the-future-in-60-seconds)\n- [MCP Server](#mcp-server) — tools available\n- [What's Different](#whats-different) — vs the original MiroFish\n- [Persona Fidelity](#persona-fidelity-how-deepmiro-keeps-agents-in-character) — the drift problem and how we fix it\n- [Monorepo Structure](#monorepo-structure)\n- [Use Cases](#use-cases)\n- [Acknowledgments](#acknowledgments)\n- [License](#license)\n\n---\n\n## What It Does\n\nDeepMiro extracts entities and relationships from any document — a policy draft, a market report, a chapter of a novel — and constructs a parallel digital world. Inside it, hundreds of autonomous agents form opinions, argue on simulated social platforms, shift allegiances, and produce emergent behavior that no single prompt could predict.\n\nYou get back a structured prediction report and a living world you can interrogate, agent by agent.\n\n> **Input:** A PDF and a question in plain language.\n> **Output:** A detailed prediction report + an interactive simulation you can explore.\n\n## How It Works\n\n```\nDocument ──► Entity Extraction ──► Agent Generation ──► Dual-Platform Simulation ──► Prediction Report\n (NER + GraphRAG) (personas, memory, (Twitter-like + Reddit-like (ReportAgent with\n social networks) parallel interaction) deep analysis tools)\n```\n\n| Phase | What happens |\n|-------|-------------|\n| **Graph Build** | Extracts entities, relationships, and context from your documents. Builds a knowledge graph via GraphRAG. |\n| **Environment Setup** | Generates agent personas with distinct personalities, beliefs, and social connections. |\n| **Simulation** | Agents interact across dual platforms (Twitter-like and Reddit-like) in parallel. Dynamic memory updates each round. |\n| **Report Generation** | A ReportAgent analyzes the post-simulation environment — sentiment shifts, faction formation, viral dynamics, outcome trajectories. |\n| **Deep Interaction** | Chat with any agent to understand their reasoning. Query the ReportAgent for follow-up analysis. |\n\n## Quick Start\n\n### 1. Get an API key\n\nSign up at [deepmiro.org](https://deepmiro.org) → Dashboard → API Keys. Your key looks like `dm_xxxxxxxxx`.\n\n### 2. Install\n\nPick the install path for your client. **Don't install the `.mcpb` desktop extension if you're using Claude Code or Claude Cowork** — those need the plugin to get the `/predict` skill, background polling, and live narration.\n\n#### Claude Desktop → use `.mcpb`\n\n1. Download `deepmiro.mcpb` from the [latest release](https://github.com/kakarot-dev/deepmiro/releases/latest)\n2. Claude Desktop → Settings → Extensions → Advanced settings → Install Extension → pick the file\n3. Paste your API key when prompted\n\n#### Claude Code & Claude Cowork → use the plugin\n\nThe plugin ships the `/predict` skill — the MCP alone is missing the orchestration logic (background polling via cron, live agent narration, the setup wizard).\n\n```bash\nclaude plugin marketplace add kakarot-dev/deepmiro\nclaude plugin install deepmiro@deepmiro-marketplace\nexport DEEPMIRO_API_KEY=dm_your_key # or set in ~/.claude/settings.json\n```\n\nRestart Claude Code, then say `/predict` or `predict how people will react to [scenario]`.\n\n#### Everywhere else → npm package\n\nGeneric MCP install for clients that aren't Claude Desktop, Claude Code, or Claude Cowork:\n\n| Client | Install |\n|--------|---------|\n| **OpenAI Codex (CLI)** | Add to `~/.codex/config.toml` under `[mcp_servers.deepmiro]`: `command = \"npx\"`, `args = [\"-y\", \"deepmiro-mcp\"]`, `env = { DEEPMIRO_API_KEY = \"dm_xxx\" }` |\n| **ChatGPT Desktop** | Settings → MCP Servers → Add → `npx deepmiro-mcp` with env `DEEPMIRO_API_KEY` |\n| **Cursor / Windsurf** | Settings → MCP → Add → `npx deepmiro-mcp` with env `DEEPMIRO_API_KEY` |\n| **VS Code (Copilot)** | Add to `.vscode/mcp.json`: `\"deepmiro\": {\"command\": \"npx\", \"args\": [\"-y\", \"deepmiro-mcp\"], \"env\": {\"DEEPMIRO_API_KEY\": \"dm_xxx\"}}` |\n\n## Rehearse the Future in 60 Seconds\n\nFour services, one compose file, one API key.\n\n
\n\n### What gets deployed\n\n| Service | Role |\n|---|---|\n| **backend** | Flask engine that runs the OASIS multi-agent simulations |\n| **mcp** | Public entry point for AI tools (Claude, Cursor, VS Code) |\n| **twhin-sidecar** | Shared TWHIN-BERT embedding service (loads once per pod) |\n| **surrealdb** | Graph + vector + document store for agents and reports |\n\n
\n\n### What you need\n\n- A **Fireworks AI** key ([fireworks.ai](https://fireworks.ai), ~$5 free credit) — covers primary LLM, boost, and embeddings in one key. Any OpenAI-compatible API also works.\n- `openssl rand -hex 32` for your SurrealDB root password.\n- ~$5–10/month of Railway credit if you're using the template.\n\n
\n\n### Option A — Railway one-click\n\n[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/98AO1I?referralCode=pYCUQd&utm_medium=integration&utm_source=template&utm_campaign=generic)\n\nRailway reads `docker-compose.yml` from the repo root and prompts for `LLM_API_KEY` + `SURREAL_PASSWORD`. The MCP service gets a public `*.up.railway.app` URL — hand that to your AI tools.\n\n> **Note — LLM provider on Railway.** The template ships with **Fireworks** as the default (primary: `minimax-m2p5`, boost: `gpt-oss-120b`, embeddings: `nomic-embed-text-v1.5` — one key covers all three). Any OpenAI-compatible API works — to swap to OpenAI, Together, Groq, Ollama, vLLM, or anything else, change `LLM_BASE_URL` and `LLM_MODEL_NAME` on the backend service's Variables tab after deploy. Same for `LLM_BOOST_*` if you want a separate reasoning model, and `EMBEDDING_*` if you want a different embedding provider.\n\n
\n\n### Option B — Docker (self-hosted)\n\n```bash\ngit clone https://github.com/kakarot-dev/deepmiro.git\ncd deepmiro && cp .env.example .env\n```\n\nEdit `.env` — two required variables:\n\n```bash\nLLM_API_KEY=your-fireworks-or-openai-key\nSURREAL_PASS=$(openssl rand -hex 32)\n```\n\nStart everything:\n\n```bash\ndocker compose up -d\n```\n\nThis pulls pre-built images from GHCR and starts four services:\n\n| Service | Port | Description |\n|---|---|---|\n| `mcp` | 3001 (public) | MCP server — the only exposed port |\n| `backend` | 5001 (internal) | Flask simulation engine |\n| `surrealdb` | 8000 (internal) | Graph + vector store |\n| `twhin-sidecar` | 7001 (internal) | Shared TWHIN-BERT embeddings |\n\nFirst startup takes ~2 minutes (TWHIN-BERT model warm-up). Check readiness:\n\n```bash\ndocker compose logs -f twhin-sidecar # wait for \"TWHIN-BERT ready\"\ndocker compose logs backend # wait for \"DeepMiro Backend ready\"\n```\n\nTo build from source instead of pulling images:\n\n```bash\ndocker compose -f docker-compose.yml \\\n --build \\\n -f docker/Dockerfile.backend \\\n up -d\n```\n\nOr uncomment the `build:` blocks in `docker-compose.yml` and comment out the `image:` lines.\n\nMCP lives on `http://localhost:3001`. Backend and SurrealDB stay internal to the compose network unless you explicitly publish them (see `docker-compose.yml` comments for how).\n\n
\n\n### Wire it into Claude Desktop\n\nAdd DeepMiro to your Claude Desktop config file:\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nFor a local Docker deployment:\n\n```json\n{\n \"mcpServers\": {\n \"deepmiro\": { \"url\": \"http://localhost:3001/mcp\" }\n }\n}\n```\n\nFor Railway or any public deployment:\n\n```json\n{\n \"mcpServers\": {\n \"deepmiro\": { \"url\": \"https://your-app.up.railway.app/mcp\" }\n }\n}\n```\n\nRestart Claude Desktop after editing. Then ask: *\"Use DeepMiro to simulate how 100 senior engineers would react to a return-to-office mandate\"* — and paste the memo.\n\n
\n\n### What it costs\n\n- **Railway:** ~$5–10/month (four services, ~4 GB resident)\n- **LLM:** ~$0.10–0.20 per quick-preset simulation on Fireworks\n- **TWHIN-BERT:** zero — runs locally in the sidecar\n\n
\n\n### Security\n\nMCP ships with no auth by default — set `MCP_API_KEY` in `.env` before exposing it to the internet. The backend REST API is internal-only out of the box.\n\n> **Skip the deploy entirely?** Use the hosted version at **[deepmiro.org](https://deepmiro.org)** — same engine, same models, no Docker.\n\n## MCP Server\n\nDeepMiro is an [MCP](https://modelcontextprotocol.io) server. MCP is natively supported by Claude (Desktop, Code, Cowork) and Cursor, with growing support across ChatGPT Desktop, VS Code (Copilot), Windsurf, and OpenAI Codex CLI — one server, works in every MCP-enabled client.\n\n```bash\nnpx deepmiro-mcp\n```\n\nAvailable tools: `create_simulation`, `simulation_status`, `get_report`, `interview_agent`, `upload_document`, `list_simulations`, `search_simulations`, `simulation_data`, `cancel_simulation`.\n\n## What's Different\n\nDeepMiro is a performance-focused fork of the original [MiroFish](https://github.com/666ghj/MiroFish) engine. Same OASIS simulation core, rebuilt infrastructure:\n\n| Component | MiroFish (original) | DeepMiro |\n|-----------|-------------------|----------|\n| **Recommendation engine** | Full LLM call every round (~200s/round) | Cached [TWHIN-BERT](https://huggingface.co/Twitter/twhin-bert-base) embeddings (~15ms/round) |\n| **Entity extraction** | Sequential NER | 5-worker parallel NER via ThreadPoolExecutor |\n| **Graph build time** | ~5 minutes | ~56 seconds |\n| **Graph database** | Zep Cloud (proprietary) | SurrealDB (self-hosted, open-source) |\n| **Vector search** | Cloud-dependent | Hybrid HNSW + BM25 (local, 768-dim cosine) |\n| **Embedding model** | Tied to Zep | `nomic-embed-text-v1.5` via Fireworks (swappable) |\n| **Document ingestion** | Manual text input | Upload endpoint with magic-byte validation (PDF, MD, TXT) |\n| **LLM provider** | Alibaba Qwen (hardcoded) | Any OpenAI-compatible API |\n| **Deployment** | Docker only | Docker + Helm chart + k3s-ready |\n\n## Persona Fidelity: How DeepMiro Keeps Agents In Character\n\nMulti-agent LLM simulations have a dirty secret: **personas drift**. By round 20, Tucker Carlson starts quoting the ACLU. By round 45, Marco Rubio sounds like Bernie Sanders. Every distinct voice collapses into the same bland \"helpful assistant\" register.\n\nThis isn't a prompting problem — it's an attention decay problem. [Kim et al. (COLM 2024)](https://arxiv.org/abs/2402.10962) proved that LLM attention to system-prompt tokens decays geometrically over turns. LLaMA2-70B drifts significantly within **8 turns**. Larger models drift more, not less. A 2KB persona cannot compete with 50KB of accumulated conversation history.\n\nEvery naive multi-agent simulation hits this wall. DeepMiro doesn't, because we copied what [Stanford's Generative Agents (Park et al. 2023)](https://arxiv.org/abs/2304.03442) did for their 25-agent Smallville simulation — with some practical shortcuts.\n\n### What we do\n\n**1. Structured personas with explicit negative examples.**\nEvery agent gets a structured profile alongside the prose bio:\n- `ideology_anchor` — a 2-5 word partisan tag (\"conservative populist\", \"progressive labor\")\n- `core_beliefs` — 3-5 first-person declarative statements, no hedging\n- `verbal_tics` — 3-5 literal phrases the person actually uses\n- `never_say` — 3-5 sentences the person would refuse to utter\n- `speaking_style` — register + rhetorical habits\n\nThe `never_say` block is the drift killer. Models drift toward the centroid of what they say. Explicit negative examples (*\"Tucker Carlson would never say 'I stand with the ACLU'\"*) anchor the LLM against that collapse.\n\n**2. Dynamic persona regeneration per round.**\nInstead of locking the persona in at the system-prompt level and watching attention decay from round 1, we rebuild `system_message.content` before every agent acts. Each round, the agent sees a fresh **third-person** character brief:\n\n```\n# Character Brief: Tucker Carlson\n\nThe agent in this conversation is Tucker Carlson.\nYou are simulating how Tucker Carlson would respond.\n\n## What Tucker Carlson Would NEVER Say\n- \"I stand with the ACLU\"\n- \"We need to find common ground with progressives\"\n...\n\n## What Tucker Carlson Has Said Recently\n- \"Permanent Washington wants you to believe...\"\n- \"Let's pause for a moment — they're not even hiding it\"\n...\n\n## Task\nWhat would Tucker Carlson actually do? React in his authentic voice.\nDo not become a neutral assistant. Do not seek balance.\n```\n\nThe persona never gets stale because it's built fresh from the same structured fields every turn.\n\n**3. Third-person framing.**\n\"You are Tucker Carlson\" triggers RLHF helpful-assistant sycophancy — the model tries to be polite and balanced because that's how it was trained to respond to \"you are X\" instructions. Third-person framing (\"the agent is Tucker Carlson\", \"what would Tucker Carlson do?\") bypasses that trigger entirely. This single change is load-bearing.\n\n**4. Self-consistency anchor.**\nEach round injects the agent's **own** 3 most recent posts as reference material. Tucker Carlson sees what he just said, which makes him more likely to say something consistent with it. This is cheap drift resistance — no extra LLM calls, just reading from the action log.\n\n**5. No accumulated chat history.**\nUnlike naive multi-agent setups, DeepMiro does NOT feed each agent the rolling conversation history from previous rounds. Agents get their fresh persona + the current feed observations. Attention stays focused on character + present context, not on 50KB of stale noise.\n\n### What we don't do\n\n- **We don't script reactions.** Agents aren't told \"mock liberal content\" or \"support conservative content\" — that would script the outcome and destroy the simulation's predictive value. The emergent behavior is the whole point.\n- **We don't filter feeds by ideology.** Tucker Carlson sees AOC's posts. That's how he has something to push back against. Echo chambers are not simulations.\n- **We don't fork OASIS.** The entire fix is a runtime wrapper around CAMEL's agent pager. No upstream drift, no fork maintenance.\n\n### Research foundations\n\n| Technique | Source |\n|---|---|\n| Attention decay over system prompts | [Kim et al. — Measuring and Controlling Persona Drift (COLM 2024)](https://arxiv.org/abs/2402.10962) |\n| Third-person framing bypasses RLHF sycophancy | [Park et al. — Generative Agents (Stanford 2023)](https://arxiv.org/abs/2304.03442) |\n| Negative examples > positive instruction | [Examining Identity Drift in LLM Agents (arXiv 2412.00804)](https://arxiv.org/abs/2412.00804) |\n| Dynamic persona summary per action | [Park et al. — Generative Agents (Stanford 2023)](https://arxiv.org/abs/2304.03442) |\n| JSON personas collapse to neutral register | [Persona-Aware Contrastive Learning (ACL 2025)](https://aclanthology.org/2025.findings-acl.1344.pdf) |\n\n### Benchmarks\n\n15-agent quick simulation, enriched prompt, measured end-to-end:\n\n| Stage | Time |\n|-------|------|\n| Graph build | ~10s |\n| Agent generation | ~3 min |\n| Simulation (110 Twitter + 26 Reddit actions) | ~4 min |\n| **Total pipeline** | **~7 min (quick) / ~12 min (standard, 80 agents)** |\n\nThe biggest win is the recommendation system: TWHIN-BERT embeddings are computed once per user at setup, then only new posts are embedded incrementally each round. Cosine similarity via numpy replaces what was previously a full LLM inference call — orders of magnitude faster per round.\n\n## Monorepo Structure\n\n```\ndeepmiro/\n├── engine/ # Python Flask simulation backend\n│ ├── app/\n│ │ ├── api/ # REST endpoints (simulation, graph, documents, report)\n│ │ ├── services/ # Graph builder, simulation runner, report agent\n│ │ ├── storage/ # SurrealDB adapter, embedding service, NER\n│ │ └── utils/ # LLM client, retry logic, logging\n│ └── pyproject.toml\n├── mcp-server/ # TypeScript MCP server (npm: deepmiro-mcp)\n│ └── src/\n├── .claude-plugin/ # Claude Code plugin + marketplace manifests\n├── .codex-plugin/ # OpenAI Codex plugin manifest\n├── .agents/ # Codex marketplace catalog\n├── .mcp.json # MCP config (auto-loaded when running `claude` here)\n├── skills/predict/ # /predict skill (auto-setup, narration, interviews)\n├── helm-chart/ # Kubernetes (k3s) deployment\n├── docker/ # Dockerfiles + compose\n├── docs/ # Landing page\n└── locales/ # English translation strings\n```\n\n## Use Cases\n\n| Domain | Example |\n|--------|---------|\n| **Market analysis** | Upload an earnings report. *\"How will retail investors react to this guidance revision?\"* |\n| **Policy testing** | Upload a draft regulation. *\"What public backlash should we expect, and from which demographics?\"* |\n| **PR & comms** | Upload a press release. *\"How will this announcement play on social media over 48 hours?\"* |\n| **Competitive analysis** | Upload competitor product specs. *\"How will our user base respond to this feature gap?\"* |\n| **Creative exploration** | Upload a novel's first 80 chapters. *\"What ending would emerge from these character dynamics?\"* |\n| **Crisis simulation** | Upload an incident report. *\"How does public opinion evolve if we respond with X vs Y?\"* |\n\n## Acknowledgments\n\nDeepMiro is a fork of [MiroFish](https://github.com/666ghj/MiroFish), originally created by Guo Hangjiang and supported by Shanda Group. The simulation layer is powered by [OASIS](https://github.com/camel-ai/oasis) from the CAMEL-AI team.\n\n## License\n\nDeepMiro is licensed under [AGPL-3.0](./LICENSE), inherited from its\nupstream [MiroFish](https://github.com/666ghj/MiroFish). AGPL is a\nstrong copyleft license — read it before adopting at scale.\n\n### What AGPL-3.0 means for you\n\n| You are... | Your obligation |\n|---|---|\n| **A user of [deepmiro.org](https://deepmiro.org)** (hosted SaaS) | None. You're a client of the service; AGPL does not apply to you. |\n| **Self-hosting for internal use** (no external users) | None. Run, fork, and modify freely. |\n| **Self-hosting and exposing DeepMiro to external users over a network** (your own SaaS, customer-facing tool, public API) | You must offer the complete corresponding source code of any modified version to those users, under AGPL-3.0. |\n| **Embedding DeepMiro in a commercial product you distribute** | The combined work must also be licensed under AGPL-3.0. |\n\nIf your use case requires a license without the network-distribution\nshare-back requirement (typical for embedding in a closed-source product\nor running a competing hosted offering), reach out at\n**kakarot.joel@gmail.com** to discuss a commercial license. The hosted\ndeepmiro.org service is also explicitly designed for commercial users\nwho want the engine without the AGPL obligation — use the API keys, skip\nthe legal work.\n\n---\n\n
\n\n**[deepmiro.org](https://deepmiro.org)** · Built by [Joel Libni](https://github.com/kakarot-dev)\n\n
\n", "bytes": 20108, "sha": "7c96fa53a0e7176c724f217a4601e551ab3dcb8181c2b6fbae8c512f0a43b935", "repo_slug": "kakarot-dev/deepmiro", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_kakarot_dev_deepmiro_deepmiro_f2e74e47/readme" }