Introduction
This is the fifth and final part of a deep-dive series on MiroFish, an open-source system combining knowledge graphs with multi-agent social media simulation. Previous parts covered GraphRAG + Zep for knowledge graph construction, OASIS for social media simulation, and ReACT for report generation. This installment reviews the overall architecture and lessons learned.
The Five-Layer Architecture
MiroFish is organized into five layers:
1. External Services (Layer 1) – OpenAI / other LLM APIs, Zep Cloud API, and the OASIS simulation environment. 2. Data (Layer 2) – Zep graph data, OASIS simulation logs (JSONL), reports (Markdown + JSON), and uploaded documents (PDF/DOCX/TXT). 3. Engine (Layer 3) – Zep Cloud (temporal knowledge graph), OASIS (social simulation), and a unified LLM client. 4. Service (Layer 4) – Report Agent (ReACT report generation), Simulation Runner, and Graph Builder. 5. Application (Layer 5) – Vue.js frontend with a five-step workflow: upload → build → generate → run → report, with ECharts visualizations.
Layer highlights
- External services: all calls wrapped in client classes with unified error handling, retries, and configurable LLM providers.
- Data: simulation logs are structured JSONL records containing timestamp, round, agent ID, action, content, platform, sentiment, and engagement metrics.
- Engine: wrapper classes such as
ZepGraphMemoryManager(add entities/relationships, semantic fact search, temporal fact lookup),OASISSimulationManager(create environments, run simulations, interview agents), andLLMClient(chat, JSON mode, profile generation). - Services:
GraphBuilder(ontology generation → entity extraction → relationship extraction → write to Zep),SimulationRunner(read entities → generate profiles → configure → run dual-platform simulation → log),ReportAgent(outline planning → per-chapter ReACT generation → reflection → merge). - Frontend: Vue.js 3, TypeScript, Element Plus, ECharts; users can inspect and edit entities, relationships, agent profiles, and monitor simulations in real time.
- MiroFish GitHub: https://github.com/666ghj/MiroFish
- Zep Cloud: https://www.getzep.com/
- OASIS (CAMEL-AI): https://github.com/camel-ai/oasis
- GraphRAG: https://microsoft.github.io/graphrag/
- ReAct: "ReAct: Synergizing Reasoning and Acting in Language Models"
- Joshua M. Epstein, "Generative Social Science"; Donella Meadows, "Thinking in Systems"
Key Technical Decisions
1. Zep Cloud vs. self-hosting: Zep Cloud was chosen because temporal knowledge graphs are a core requirement natively supported by Zep, and the small team (1–2 people) could not absorb the cost of self-built alternatives. 2. OASIS vs. custom simulator: OASIS (from CAMEL-AI) offers a solid theoretical foundation, Twitter + Reddit dual-platform support, and active maintenance. MiroFish adds API wrappers, an Interview Agents feature, and business-flow integration. 3. ReACT vs. end-to-end generation: MiroFish prioritizes quality over speed and cost, using ReACT with roughly 3–5 tool calls per chapter for traceable, verifiable reports that reduce hallucination.
Technical Debt and Limitations
| Limitation | Impact | Possible fix | |---|---|---| | External API dependency | Any Zep/OASIS/LLM outage breaks the system | Degradation plans; open-source alternatives | | High simulation cost | Large-scale runs require many LLM calls | Prompt optimization; smaller models | | Non-deterministic agents | Same input may yield different outputs | Random seeds; averaging multiple runs | | Hardcoded time zones | Only Chinese schedules supported | Configurable time zones |
Other debt: scattered configuration, incomplete error handling and retry logic, low test coverage, and missing API/deployment documentation.
Insights
1. Combination beats invention: MiroFish invents no new technology—it integrates Zep (auto ontology generation, temporal reasoning), OASIS (profile generation, Interview Agents), OpenAI (ReACT reports), and Vue.js (five-step workflow). Integration capability matters more than invention capability in the AI era. 2. Constraints drive innovation: limits like a 10-entity-type cap led to automatic ontology generation with fallback types; the requirement that agents be able to post publicly excluded abstract concepts; dual-platform simulation revealed Twitter/Reddit behavioral differences. 3. From tool to system: the evolution path runs from a GraphRAG tool → tool chain (document → graph → simulation → report) → complete system (MiroFish) → future platform (skill marketplace, community sharing, open APIs).
Comparisons
Compared to traditional public-opinion analysis tools, MiroFish uses user-uploaded documents plus agent simulation rather than historical social data, offering traceable relationship chains and multi-scenario rehearsal at the cost of high compute. Compared to AutoGen (general multi-agent framework), CAMEL (research platform, the foundation MiroFish builds upon), MetaGPT and ChatDev (software-engineering multi-agent systems), MiroFish is distinct in its focus on social simulation.
Conclusion
The author argues MiroFish's real value is demonstrating a new possibility: using computational simulation to understand complex social systems—not to predict the future, but to create and rehearse possible futures for better decisions.