MiroFish Offline
Simulate document-driven public reaction and social dynamics entirely on local infrastructure.
- Source repo
- nikmcfly/MiroFish-Offline
- Stars
- ★ 2.5k
- Last updated
- 6mo ago
- License
- AGPL-3.0
- Primary language
- Python
- FA score
- 30/100 · Major gaps
At a glance
- Works with
- Universal · cross-platformOpenAI API · Claude API
- You'll need
- Typical use
- A PR team uploads a draft press release before publication to examine simulated public discussion, arguments, and sentiment movement.
- Main limitation
- The recommended qwen2.5:32b configuration calls for 24 GB of GPU VRAM; even the minimum documented setup calls for 16 GB RAM and 10 GB VRAM, and CPU-only inference is significantly slower.
- Source review
- 30/100 · Major gaps 7 safety controls not found
What does this agent do, and when should you use it?
MiroFish Offline is an English, fully local fork of MiroFish for document-driven multi-agent simulations. Its Flask API exposes graph, simulation, and reporting functions, while Neo4j Community Edition 5.15 stores graph and memory data and Ollama supplies local models and embeddings. The system creates hundreds of personas with individual traits, opinion bias, reaction speed, influence level, and memories, then has them interact on simulated social platforms. After a run, ReportAgent combines focus-group interviews with knowledge-graph evidence to produce a structured analysis, and users can continue chatting with simulated agents. It supports Docker Compose deployment as well as a manual Python, Node.js, Neo4j, and Ollama setup.
A user uploads a document such as a press release, policy draft, or financial report. Graph Build extracts people, companies, events, and relationships, then builds a Neo4j knowledge graph with individual and group memory. Env Setup generates hundreds of personas with personality, opinion bias, reaction speed, influence level, and past-event memory. Simulation has those personas post, reply, argue, and shift opinions on simulated social platforms while tracking sentiment evolution, topic propagation, and influence dynamics. ReportAgent then interviews a focus group, searches the graph for evidence, and generates a structured analysis; Interaction lets the user ask an agent why it posted. The backend injects GraphStorage through app.extensions['neo4j_storage']; Neo4jStorage includes EmbeddingService, NERExtractor, and SearchService, with hybrid search weighted 0.7 vector similarity and 0.3 BM25 keyword search.
- A PR team uploads a draft press release before publication to examine simulated public discussion, arguments, and sentiment movement.
- A market or trading researcher feeds in financial news to observe simulated market sentiment and topic propagation.
- A policy team uploads a proposed regulation to test how distinct simulated personas may react to it.
- A researcher needs document entities and relationships extracted into a searchable Neo4j knowledge graph before running a social simulation.
- A creative practitioner wants persistent, personality-driven characters to respond and interact around a supplied text.
How do you install or deploy this agent?
Recommended Docker setup:
git clone https://github.com/nikmcfly/MiroFish-Offline.git
cd MiroFish-Offline
cp .env.example .env
docker compose up -d
docker exec mirofish-ollama ollama pull qwen2.5:32b
docker exec mirofish-ollama ollama pull nomic-embed-textThen open http://localhost:3000. The documented local defaults are LLM_API_KEY=ollama, LLM_BASE_URL=http://localhost:11434/v1, LLM_MODEL_NAME=qwen2.5:32b, NEO4J_URI=bolt://localhost:7687, NEO4J_USER=neo4j, NEO4J_PASSWORD=mirofish, and EMBEDDING_MODEL=nomic-embed-text.
How do you use this agent?
Once the services are running, open http://localhost:3000 and upload the document to analyze. Use the Graph Build, Env Setup, and Simulation workflow: create the entity-and-relationship graph, generate the persona environment, and run the simulated social interactions. Review the structured analysis produced by ReportAgent, then use Interaction to continue a conversation with a simulated persona. On lighter hardware, set LLM_MODEL_NAME in .env to qwen2.5:14b or qwen2.5:7b; the documented embedding model remains nomic-embed-text.
What are this agent's strengths and limitations?
- It replaces Zep Cloud and cloud model APIs with Neo4j Community Edition 5.15 and Ollama, enabling a documented local deployment without cloud API keys.
- It covers the complete flow from document graph construction and persona generation through social simulation, reporting, and follow-up agent conversations.
- The documented GraphStorage abstraction separates the application service layer from the graph database, so another graph database can be substituted by implementing one class.
- Its SearchService uses an explicitly defined hybrid retrieval formula: 0.7 vector similarity plus 0.3 BM25 keyword search.
- The recommended qwen2.5:32b configuration calls for 24 GB of GPU VRAM; even the minimum documented setup calls for 16 GB RAM and 10 GB VRAM, and CPU-only inference is significantly slower.
- Operation depends on Neo4j, Ollama, and an embedding model; the recommended path additionally requires Docker and Docker Compose.
- The example configuration includes the Neo4j credentials neo4j/mirofish, so deployers need to assess and change local security settings themselves.
- Although the project says LLM_BASE_URL and LLM_API_KEY can be changed for other providers, it does not provide provider-specific configuration examples or compatibility test results.
How does this agent compare with similar options?
Compared with the original MiroFish, this fork provides an English UI and replaces Zep Cloud graph memory, DashScope/OpenAI APIs, and Zep embeddings with local Neo4j Community Edition 5.15, Ollama, and Ollama-hosted nomic-embed-text. The original is described as Chinese-market oriented, while this fork is positioned around zero cloud dependencies.
Key facts side by side with the most closely related agents.
| Agent | Source review | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|
| MiroFish Offline This agent | 30 · Major gaps | ★ 2.5k | 6mo ago | Python | OpenAI API · Claude API |
| Concordia: A Library for Generative Social Simulation | 39 · Major gaps | ★ 1.7k | 9d ago | Python | — |
| TradingAgents Financial Research Framework | 76 · Good | ★ 108k | 6d ago | Python | OpenAI API · Claude API |
| Yuxi – Self-Hosted Multi-Tenant Knowledge Agent Platform | 41 · Major gaps | ★ 7.2k | today | Python | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence: README clearly states it is a fork of MiroFish and lists modifications, but no upstream commit hash or detailed source verification is provided; no documentation or code evidence for least privilege, user confirmation, data flow transparency, sensitive data handling, dependency security, external effects, or rollback. Deductions: these aspects are entirely absent from the provided files.
Evidence: README describes workflow and architecture, but no error handling or failure message documentation; dependencies (Neo4j, Ollama, Python packages) are listed but without version pinning or integrity checks. Deductions: self-consistency only partially shown, dependency availability only names, failure messages no evidence.
Evidence: README lists multiple use cases (PR crisis testing, trading signals, policy analysis) and hardware requirements, but does not define capability boundaries or trigger conditions; environment fit provides Docker and manual install options. Deductions: capability boundaries and trigger precision not specified.
Evidence: README provides installation instructions, architecture diagram, configuration example, and license (AGPL-3.0), but lacks FAQ, known limitations, version history or changelog; naming stability not explicit. Deductions: information architecture and install notes are adequate, but other aspects insufficient.
Evidence: README describes outputs (reports, interaction) and marginal value (localization, multiple scenarios), but no performance benchmarks or cost-benefit analysis. Deductions: output usability only described, marginal value and cost-benefit have partial evidence.
Evidence: README claims to be a fork of MiroFish and lists modifications, but no upstream commit hash or verifiable test results; no separation of facts and inferences. Deductions: claim traceability weak, cross-source corroboration insufficient, fact-inference separation absent.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- No security audit or permission management documentation provided; review code before deployment.
- Dependencies are not version-pinned, posing supply chain risks.
- No error handling or failure recovery mechanisms documented; use with caution in production.