🔥 03. MiroFish: 예측형 swarm intelligence 엔진

MiroFish는 뉴스, 정책, 금융 신호 같은 씨앗 데이터를 넣으면 다수의 에이전트가 상호작용하는 디지털 세계를 만들어 미래 전개를 시뮬레이션하겠다는 프로젝트다. 한마디로 “예측용 에이전트 샌드박스”에 가깝다.

이 레포는 3위 · ⭐ +17.6K로 회자된 프로젝트다. 별 숫자만 보면 유행처럼 보일 수 있지만, 실제로는 개발자들이 지금 어디에 시간을 쓰고 있는지를 꽤 솔직하게 드러낸다. 에이전트 붐 속에서도 MiroFish가 유난히 눈에 띈 이유는 단순 챗봇이 아니라 “무수한 개체가 움직이는 사회 시뮬레이션”을 내세웠기 때문이다. 개발자 입장에서는 구조가 크고 과감해서 궁금해지고, 일반 사용자 입장에서는 정치·여론·소설 결말까지 시뮬레이션한다는 그림이 강하게 먹힌다.

flowchart LR
A[문제] --> B[mirofish]
B --> C[설치]
C --> D[최소 실험]
D --> E[업무 적용 판단]

칠판 판서형 치트시트

• 이 레포의 한 줄 키워드는 mirofish다.
• 이번 보강에서는 설치와 사용 순서를 공식 README 기준으로 더 촘촘하게 정리했다.
• 읽을 때는 전제 조건 → 설치 → 첫 실행 → 검증 순서로 보면 된다.
• “대단해 보인다”보다 “내 업무에서 반복 비용을 줄이는가”를 먼저 본다.

이 레포를 한 줄로 보면

MiroFish는 뉴스, 정책, 금융 신호 같은 씨앗 데이터를 넣으면 다수의 에이전트가 상호작용하는 디지털 세계를 만들어 미래 전개를 시뮬레이션하겠다는 프로젝트다. 한마디로 “예측용 에이전트 샌드박스”에 가깝다.

왜 지금 이 레포가 뜨는가

에이전트 붐 속에서도 MiroFish가 유난히 눈에 띈 이유는 단순 챗봇이 아니라 “무수한 개체가 움직이는 사회 시뮬레이션”을 내세웠기 때문이다. 개발자 입장에서는 구조가 크고 과감해서 궁금해지고, 일반 사용자 입장에서는 정치·여론·소설 결말까지 시뮬레이션한다는 그림이 강하게 먹힌다.

레포 안에서 먼저 볼 것

• GraphRAG 기반 그래프 구축과 개체 기억 주입 단계
• 환경 구성 후 다수 에이전트가 병렬 시뮬레이션을 수행하는 흐름
• 보고서 생성과 시뮬레이션 세계 내부 캐릭터와의 심화 대화 기능

설치 전에 확인할 것

• Node.js 18+
• Python 3.11 이상 3.12 이하
• uv 최신 버전
• LLM API Key와 ZEP API Key

설치 방법

공식 확인 링크

• GitHub README: https://github.com/666ghj/MiroFish
• 라이브 데모: https://666ghj.github.io/mirofish-demo/

소스코드로 설치(권장)

git clone https://github.com/666ghj/MiroFish.git
cd MiroFish
cp .env.example .env

그다음 .env에 최소 아래 값은 채워야 한다.

LLM_API_KEY=your_api_key
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus
ZEP_API_KEY=your_zep_api_key

의존성은 한 번에 설치할 수 있다.

npm run setup:all

단계별로 나누고 싶다면 아래처럼 한다.

npm run setup
npm run setup:backend

실행은 프로젝트 루트에서 한다.

npm run dev

정상이라면 프론트엔드는 http://localhost:3000, 백엔드 API는 http://localhost:5001에서 열린다.

Docker로 빠르게 띄우기

cp .env.example .env
docker compose up -d

README 기준으로 Docker는 루트의 .env를 읽고, 기본 포트는 3000(프론트엔드) / 5001(백엔드)다. 로컬 의존성 설치가 번거로우면 이 경로가 더 편하다.

설치 확인

• http://localhost:3000이 열리는지 본다.
• 백엔드가 5001 포트에서 살아 있는지 확인한다.
• 초기 실험에서는 시뮬레이션 라운드를 너무 크게 잡지 말고 README 권장대로 40라운드 미만으로 시작한다.

사용 방법

1. UI에 seed material을 넣는다. README 설명대로 데이터 분석 리포트나 소설 텍스트처럼 출발 재료가 필요하다.
2. 예측 요구사항을 자연어로 적는다. 질문이 넓으면 결과도 흐려지니 한 문장으로 좁히는 편이 좋다.
3. Graph Building → Environment Setup → Simulation → Report Generation 순서로 진행되는 결과를 본다.
4. 결과 보고서가 나오면 그걸 정답처럼 믿기보다, 어떤 변수에 민감한지 추가 질문을 다시 던져본다.

처음에는 “정치/금융 대예측”보다 좁은 질문이 좋다. 예를 들어 이 정책 초안이 공개됐을 때 이해관계자 반응이 어떻게 갈릴까처럼 묻고, 소규모 라운드로 먼저 돌리는 편이 안정적이다. 공식 README도 비용을 이유로 적은 라운드부터 시작하라고 안내한다.

어디에 바로 써먹을 수 있나

사례 A. 여론 변화 가설 점검

어떤 이슈가 커질 때 이해관계자별 반응을 가정해보고 싶다면 seed 자료와 시나리오를 넣어 반응 구조를 탐색하는 데 쓸 수 있다. 실전에서는 정답 기계라기보다 의사결정 전에 질문 목록을 넓혀주는 도구에 가깝다.

사례 B. 스토리/콘텐츠 실험

소설 결말이나 세계관 전개처럼 정량 데이터가 약한 주제에서도 아이디어 샌드박스로 쓸 수 있다. 이 경우 정확도보다 “가능한 전개를 풍부하게 만들어 주는가”가 더 중요하다.

처음 해볼 최소 실험

1. 라이브 데모를 먼저 열어 결과물 감을 잡는다.
2. 로컬에서는 .env를 채운 뒤 npm run dev로 UI를 띄운다.
3. 짧은 seed 자료와 명확한 질문 1개만 넣어 첫 시뮬레이션을 수행한다.
4. 보고서에서 흥미로운 가설 2~3개를 다시 확인 질문으로 재실행한다.

검증 포인트는 간단하다. 좋은 실험은 “맞췄다”보다 “결정 전에 어떤 질문을 새로 알게 됐는가”로 평가하는 편이 낫다. 결과가 지나치게 단정적이면 오히려 경계해야 한다.

볼 때 주의할 점

• 시뮬레이션 결과를 예언처럼 받아들이면 위험하다.
• LLM API와 Zep 같은 외부 의존성이 있어 비용과 설정 부담이 있다.
• 초반 데모는 인상적이지만, 실제 업무에 쓰려면 데이터 입력 품질 관리가 필수다.

다음 읽기

• 🔥 04. OpenViking
• 🔥 09. Deep Agents
• 🔥 Git Trend 허브

이 글은 AI를 활용해 초안을 정리했고, GitHub README와 공식 링크를 다시 확인해 실무 적용 관점으로 풀어썼다.