MiroFish(미로피시)는 뉴스·정책 초안·금융 신호·소설 같은 자료와 예측 질문을 받아, 여러 성격과 기억을 가진 AI 에이전트가 상호작용하는 디지털 평행 세계를 만들고 시뮬레이션하는 오픈소스 군집 지능 예측 엔진입니다. 2025년 11월 공개된 GitHub 프로젝트로, 2026년 9월 30일 확인 기준 별 약 7만 5천 개를 받았고 AGPL-3.0 라이선스로 배포됩니다.
README의 표현을 빌리면 “디지털 샌드박스에서 미래를 리허설하고, 수많은 시뮬레이션 끝에 결정에서 이긴다”는 구상입니다. 씨앗 자료와 자연어 요구를 넣어 보고서뿐 아니라 결과 세계 안에서 대화할 수 있는 환경까지 만드는 것이 MiroFish의 목표입니다.
MiroFish란: 씨앗 자료 하나로 디지털 평행 세계를 만든다
사용자는 분석 보고서나 소설 등 씨앗 자료를 올리고, 무엇을 예측할지 자연어로 적습니다. MiroFish는 자료에서 인물·기관·관계와 기억을 추출해 에이전트 세계를 구성합니다. 각 에이전트는 저마다의 성격, 장기 기억, 행동 논리를 갖도록 설정되며, 이들이 환경 안에서 상호작용한 결과를 예측 보고서로 정리합니다.
사용자는 결과를 읽는 데서 그치지 않고, “신의 시점”에서 조건과 변수를 바꿔 세계의 흐름을 다시 살펴볼 수 있습니다. 프로젝트 첫 화면은 보고서를 올리면 바로 미래를 추론한다고 소개하고, 한 단락의 글로도 최대 백만 단위 에이전트의 평행 세계를 만들 수 있다고 내세웁니다. 업로드 형식은 PDF·MD·TXT입니다. 화면에는 일반 시뮬레이션 1회 평균 비용을 약 5달러로 안내합니다.
의사결정 리허설부터 소설 결말까지
MiroFish가 제시하는 거시적 활용은 정책이나 홍보 전략을 실제로 시행하기 전에 여러 상황을 시험하는 의사결정자용 리허설 실험실입니다. 미시적으로는 소설의 사라진 결말을 추론하거나, 상상 속 조건을 바꿔 보는 개인 창작 샌드박스를 지향합니다.
진지한 예측부터 가벼운 시뮬레이션까지, 모든 “만약에”의 결과를 볼 수 있게 해 무엇이든 예측할 수 있게 한다는 것이 MiroFish의 목표입니다.
데모: 우한대 여론과 홍루몽의 잃어버린 결말
MiroFish 라이브 데모에서는 우한대 사례의 그래프 구축, 환경 설정, 시뮬레이션 화면을 따라갈 수 있습니다. 사전 구성된 정적 데모이며 에이전트와의 깊은 대화는 실제 LLM에 연결되지 않습니다. 데모에는 입력 자료인 우한대 브랜드 평판 분석 PDF도 제공됩니다.
첫 번째 영상은 같은 개발자의 여론 분석 프로젝트 BettaFish가 만든 우한대 여론 보고서를 MiroFish에 넣어 시뮬레이션하는 과정을 보여 줍니다. 우한대 여론 시뮬레이션 소개 영상(Bilibili, 17분)은 2025년 12월 22일(한국 시간) 게시됐습니다.
두 번째 사례는 홍루몽 앞 80회 분량을 바탕으로 사라진 결말을 추론하는 실험입니다. 홍루몽 잃어버린 결말 시뮬레이션(Bilibili, 14분)은 2026년 1월 20일(한국 시간) 게시됐습니다.
README는 금융 예측과 정치 뉴스 예측 사례도 이어서 소개할 예정이라고 적었습니다.
작동 방식: 씨앗 자료에서 보고서까지 5단계
- 그래프 구축. 자료에서 정보를 뽑고 개인·집단 기억을 더해 GraphRAG 지식 그래프를 만듭니다. 코드에서는 Zep Cloud에 그래프와 엔티티, 관계, 에피소드 기억을 구성합니다.
- 환경 설정. 엔티티와 관계를 바탕으로 시뮬레이션의 온톨로지를 만들고, 각 엔티티의 페르소나와 OASIS 에이전트 프로필, 세계 설정을 생성합니다.
- 시뮬레이션. 자연어 예측 요구를 설정과 라운드에 반영하고, 에이전트의 활동과 시간에 따른 기억을 갱신합니다. “이중 플랫폼 병렬 시뮬레이션”은 Twitter형과 Reddit형 OASIS 환경을 각각 구성해 함께 실행하는 구조입니다.
- 보고서 생성. ReportAgent가 검색, 인사이트 분석, 에이전트 인터뷰 도구로 시뮬레이션 결과를 살펴보고 보고서를 작성합니다.
- 깊은 상호작용. 결과 세계의 개별 에이전트나 ReportAgent와 대화해 보고서에 담긴 흐름을 더 탐색합니다.
설정 화면 예시에는 에이전트 39개, 시뮬레이션 120시간, 라운드당 60분, 총 120라운드가 표시됩니다.
MiroFish 설치법: 소스 코드와 Docker
소스 설치에는 Node.js 18 이상과 npm, Python 3.11~3.12, 최신 uv 패키지 관리자, LLM API 키와 Zep Cloud API 키가 필요합니다. 먼저 예제 환경 파일을 복사합니다.
cp .env.example .env.env에 LLM과 Zep Cloud 설정을 넣습니다. README 예시는 Alibaba Bailian의 Qwen-plus를 사용합니다.
# LLM API Configuration (supports any LLM API with OpenAI SDK format)
LLM_API_KEY=your_api_key
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus
# Zep Cloud Configuration
ZEP_API_KEY=your_zep_api_key전체 의존성을 설치하고 개발 서버를 실행합니다.
npm run setup:all
npm run dev단계별 설치는 npm run setup(Node.js 의존성), npm run setup:backend(Python 백엔드 의존성)로 나눌 수 있습니다. 프런트엔드와 백엔드는 각각 npm run frontend, npm run backend로 실행합니다. 기본 주소는 프런트엔드 http://localhost:3000, 백엔드 API http://localhost:5001입니다.
Docker를 쓰려면 같은 환경 파일을 만든 다음 Compose를 올립니다.
cp .env.example .env
docker compose up -d비용과 준비할 API 키
MiroFish README는 OpenAI SDK 형식과 호환되는 LLM API를 사용할 수 있다고 안내합니다. 권장 모델은 Alibaba Bailian의 Qwen-plus입니다. 모델 호출과 에이전트 상호작용에 토큰이 많이 들 수 있으므로, README는 처음에는 40라운드 미만으로 실행해 보라고 권합니다. Zep Cloud 무료 월 한도는 간단한 사용에 충분할 수 있다고 설명합니다.
첫 화면에는 일반 시뮬레이션 한 번의 평균 비용이 약 5달러라고 표시됩니다. 실제 지출은 모델, 입력 자료, 에이전트 수와 라운드 구성에 따라 달라질 수 있으니 작은 설정으로 먼저 확인하는 편이 좋습니다.
누가 만들었나: BettaFish 개발자와 샨다 그룹
GitHub 계정 666ghj(BaiFu)는 MiroFish와 BettaFish를 만든 개발자입니다. BettaFish는 여론 분석 프로젝트로, 우한대 사례의 입력 보고서도 이 프로젝트가 만들었습니다. 시뮬레이션 엔진으로는 CAMEL-AI의 OASIS를 사용합니다.
MiroFish README는 샨다 그룹의 전략적 지원과 인큐베이션을 받았다고 밝힙니다. 샨다 창업자 천톈차오(Tianqiao Chen)도 MiroFish를 인큐베이팅 프로젝트로 소개했습니다. 저장소 생성일은 2025년 11월 26일(한국 시간)이며, 릴리스는 v0.1.0(2025년 12월 22일), v0.1.1(2026년 1월 22일), v0.1.2(2026년 3월 7일) 순입니다.
라이선스는 AGPL-3.0입니다. 소프트웨어를 수정해 네트워크 서비스로 제공하는 경우에도 라이선스 조건에 따른 소스 공개 의무가 적용될 수 있으므로, 상용 배포 전에는 라이선스 전문과 적용 범위를 확인해야 합니다.
출처: X @mirofish_ai
출처: X @tianqiao_chen
출처: X @whoisbaifu
