MiroFish Deep Dive (Part 5): Full Technical Architecture and Lessons Learned

Forum topic · 小凯 · 2026-04-05

Summary

This concluding installment of the MiroFish series presents a five-layer architectural blueprint of the open-source MiroFish system, which combines GraphRAG with Zep temporal knowledge graphs, OASIS social media simulation, and ReACT-based report generation. The architecture spans an External Services Layer (OpenAI, Zep Cloud API, OASIS), a Data Layer (graph data, JSONL simulation logs, Markdown reports), an Engine Layer (Zep, OASIS, and LLM client wrappers), a Service Layer (Graph Builder, Simulation Runner, Report Agent), and a Vue.js 3 Presentation Layer supporting a five-step user workflow. The article analyzes key design choices such as using managed Zep Cloud over self-hosted Neo4j, adopting OASIS over custom simulation, and choosing ReACT over end-to-end generation for traceability. It also catalogs technical debt including fragmented configuration, weak error handling, low test coverage, and hardcoded time zones, and concludes with broader lessons: combinatorial innovation outperforms from-scratch invention, constraints drive better design, and the product evolves from a single tool to a workflow system with future platform potential.

Key points

Five-layer architecture: External Services (OpenAI, Zep API, OASIS), Data (Zep graph, JSONL logs, reports, uploads), Engine (Zep, OASIS, LLM Client), Service (Graph Builder, Simulation Runner, Report Agent), and Presentation (Vue.js 3 + Element Plus + ECharts).
Five-step user workflow: Upload documents → build knowledge graph → generate Agent profiles → run simulation → generate report.
Key technical decisions:
Zep Cloud chosen over self-hosted Neo4j for native temporal graph support and low operational overhead.
OASIS adopted (from CAMEL-AI) over a custom engine; MiroFish adds Profile generation and Interview Agents.
ReACT selected over end-to-end generation to ensure traceability, verifiability, and reduced hallucination (3–5 tool calls per section).
Data and logging: Knowledge graphs live in Zep; simulation logs use JSONL with timestamp, round, agent_id, action, content, platform, sentiment, and engagement metrics; reports stored as Markdown + JSON.
Engine abstractions: ZepGraphMemoryManager exposes add_entity, add_relationship, search_facts, get_temporal_facts; OASISSimulationManager exposes create_environment, run_simulation, interview_agent; LLMClient exposes chat, chat_json, generate_profile.
Service-layer pipelines: Graph Builder (ontology → entities → relationships → Zep write), Simulation Runner (read graph → generate profiles → config → dual-platform run → logging), Report Agent (outline → ReACT sections → reflection → integrate).
Known limitations and debt: hard dependency on external APIs, high simulation cost, non-deterministic Agent behavior, hardcoded time zone, scattered configuration, weak error handling, low test coverage, and missing API/deployment documentation.
Comparative landscape: MiroFish differs from traditional sentiment tools (which mine historical data) and from general multi-agent frameworks (AutoGen, CAMEL, MetaGPT, ChatDev) by focusing on social-media simulation driven by user-supplied documents.
Broader lessons: combinatorial integration > invention; constraints catalyze better designs (e.g., the 10-entity-type cap shaped auto-ontology generation); evolution path from single tool → toolchain → system → platform.

Reference resources

Project: 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 paper: "ReAct: Synergizing Reasoning and Acting in Language Models"

MiroFish Deep Dive (Part 5): Full Technical Architecture and Lessons Learned

Summary

Key points

Reference resources

Tags