MiroFish | leeyc blog

단순 예측 모델이 아니라, 여러 에이전트가 상호작용하는 디지털 세계를 먼저 만들고 그 안에서 미래를 시뮬레이션하자는 발상이 핵심인 프로젝트입니다.

MiroFish란?

MiroFish는 다중 에이전트 기반 AI 예측 엔진입니다.

프로젝트 설명에 따르면 현실 세계의 시드 정보, 예를 들어

돌발 뉴스,
정책 초안,
금융 신호,
데이터 분석 리포트,
심지어 소설 같은 서사 자료 를 입력으로 받아, 그 위에 고충실도 병렬 디지털 세계를 구축합니다.

그 안에서 수많은 에이전트가

개별 성격,
장기 기억,
행동 로직 을 갖고 상호작용하며 사회적 변화를 만들어내고, 사용자는 이를 통해 미래 시나리오를 관찰하거나 개입할 수 있습니다.

즉 MiroFish는 단순한 “다음 수치 예측 모델”이 아니라, 상호작용 기반 시뮬레이션으로 결과를 도출하는 multi-agent forecasting system에 가깝습니다.

GitHub: https://github.com/666ghj/MiroFish
포지션: swarm intelligence / multi-agent simulation / forecasting engine
주 언어: Python 중심, 프런트엔드와 Node 도구 체인 포함

왜 주목할 만한가?

1. 예측을 ‘계산’이 아니라 ‘시뮬레이션’으로 본다

일반적인 예측 시스템은 과거 데이터를 넣고 수치나 분류 결과를 뽑는 흐름이 많습니다. 반면 MiroFish는 현실 정보를 바탕으로 디지털 사회를 구성한 뒤 그 안에서 미래를 전개시킵니다.

이 차이는 꽤 큽니다. 왜냐하면 정책, 여론, 금융, 이야기 구조처럼 상호작용과 맥락이 중요한 문제는 단순 회귀/분류보다 행위자 간 상호작용을 모델링하는 방식이 더 설득력 있을 때가 많기 때문입니다.

2. 다중 에이전트 기술을 예측 엔진으로 밀어붙임

README가 내세우는 방향은 선명합니다. MiroFish는 multi-agent 기술을 단순 역할놀이 챗봇이 아니라, 현실 의사결정과 시나리오 검토를 위한 엔진으로 쓰려 합니다.

거시적으로는

정책 실험,
PR 시뮬레이션,
여론 흐름 예측,
금융 방향 추론 같은 use case를 겨냥하고, 미시적으로는
소설 결말 추론,
창작 샌드박스,
상상 실험 같은 재미있는 개인용 시나리오까지 포괄합니다.

3. ‘예측 보고서 + 상호작용 가능한 세계’라는 출력 형태가 독특함

MiroFish의 출력은 단순 점수 하나가 아닙니다. 설명에 따르면 사용자는

상세 예측 리포트와
깊게 상호작용 가능한 디지털 세계 를 함께 받습니다.

즉 분석 결과를 읽는 것에 그치지 않고, 그 예측이 어떤 맥락과 상호작용으로 형성되는지 더 파고들 수 있게 설계된 점이 흥미롭습니다.

핵심 동작 흐름

README를 바탕으로 요약하면 대략 이런 파이프라인입니다.

시드 자료 업로드
- 뉴스, 정책 초안, 분석 자료, 스토리 등 입력
예측 요구를 자연어로 기술
- 무엇을 예측하고 싶은지 서술
그래프/기억/환경 구축
- 현실 시드 추출
- 개체·집단 메모리 주입
- GraphRAG 구성
- 환경 파라미터 주입
다중 에이전트 시뮬레이션 수행
- 여러 에이전트가 병렬적으로 상호작용
- 시간 흐름에 따라 기억과 상태 갱신
리포트 및 상호작용 결과 제공
- ReportAgent가 결과를 정리
- 사용자가 특정 개체/에이전트와 대화 가능

즉 이 프로젝트는 예측을 위해 Agent memory + simulation + GraphRAG + report generation을 한 묶음으로 엮고 있습니다.

에이전트 하네스 아키텍처 관점에서 보면

전하께서 중히 보시는 포인트로 풀어 보면, MiroFish는 단순 LLM 앱이 아니라 시뮬레이션 중심 에이전트 하네스라고 볼 수 있습니다.

구조를 단순화하면 다음과 같습니다.

사용자 입력 / 현실 시드 자료
          ↓
오케스트레이션 계층
(planner / scenario builder / simulation controller)
          ↓
다중 에이전트 집합
(persona / memory / interaction loop)
          ↓
GraphRAG / memory / environment state
          ↓
ReportAgent / interactive world / final output

이 구조에서 보이는 핵심 계층

Scenario Builder
- 입력 자료를 해석해 어떤 세계를 만들지 결정
- 어떤 개체와 변수, 환경 규칙이 필요한지 설정
Agent Swarm
- 다수의 에이전트가 독립 성격과 기억을 바탕으로 상호작용
- 집단 수준의 emergent behavior를 발생시킴
Memory / GraphRAG Layer
- 개체·집단 메모리와 관계 구조를 저장
- 시뮬레이션 중 문맥 일관성을 유지
ReportAgent / Interaction Layer
- 결과를 사람이 읽을 수 있는 리포트로 변환
- 시뮬레이션된 세계를 더 파고들 수 있게 인터페이스 제공

왜 ‘하네스’ 관점이 중요한가?

MiroFish의 본질은 단일 프롬프트 최적화가 아닙니다. 핵심은

에이전트를 다수 띄우고,
메모리를 유지하고,
관계 구조를 보존하고,
시간 흐름을 따라 상태를 업데이트하고,
마지막에 보고 체계로 정리하는 오케스트레이션 구조 전체에 있습니다.

즉 이것은 “에이전트를 쓰는 앱”이 아니라, 예측 목적에 맞게 설계된 agent harness + simulation stack이라고 보는 편이 맞습니다.

블로그 자동화/에이전트 자동화와 섞여 보이는 이유

이 프로젝트가 흥미로운 이유 중 하나는, 일반적인 업무 자동화 에이전트와 결은 다르지만 근본적으로는 같은 구성 요소를 공유하기 때문입니다.

예를 들어 둘 다 다음을 필요로 합니다.

planner
tool 호출 계층
memory
world/model state
보고서 생성기

차이는 블로그 자동화는 “작업 완료”를 목표로 하고, MiroFish는 “시뮬레이션을 통한 미래 추론”을 목표로 한다는 점입니다. 즉 도구와 하네스 개념은 닮았지만, 문제 설정과 출력 형식이 훨씬 더 simulation-native입니다.

기술 및 실행 환경

README 기준 요구사항은 다음과 같습니다.

Node.js 18+
Python 3.11~3.12
uv 최신 버전
LLM API (OpenAI SDK 호환 형식)
Zep Cloud API

환경 변수 예시는 다음 축을 포함합니다.

LLM_API_KEY
LLM_BASE_URL
LLM_MODEL_NAME
ZEP_API_KEY

즉 실행 구조상, 프런트엔드/백엔드/UI가 있는 응용 시스템이면서, 백엔드 쪽에서 LLM과 메모리 계층을 붙여 작동하는 형태로 보입니다.

설치와 실행

README를 따르면 대략 다음 순서입니다.

cp .env.example .env

그 뒤 필요한 API 키를 채우고,

npm run setup:all

또는 단계별로,

npm run setup
npm run setup:backend
npm run dev

기본 서비스 주소는 다음과 같습니다.

프런트엔드: http://localhost:3000
백엔드 API: http://localhost:5001

Docker로도 실행 가능합니다.

docker compose up -d

즉 단순 라이브러리라기보다, 사용자 인터페이스와 백엔드 시뮬레이션 엔진을 함께 갖춘 애플리케이션형 프로젝트입니다.

어떤 사람에게 맞는가?

잘 맞는 경우

multi-agent 시뮬레이션 자체를 연구하거나 실험하는 사람
정책/여론/시장/서사 전개처럼 상호작용 기반 예측에 관심 있는 팀
GraphRAG + memory + simulation을 결합한 구조를 보고 싶은 사람
단순 툴 호출형 에이전트를 넘어 집단 행위 기반 시스템을 탐구하는 사람

덜 맞는 경우

단순 RAG 챗봇만 필요할 때
빠른 CRUD 자동화나 브라우저 자동화가 목표일 때
예측보다는 즉시 실행형 task automation이 필요한 경우

즉 MiroFish는 범용 업무 자동화보다는, 시뮬레이션 중심 AI 시스템에 관심 있는 사람에게 더 강하게 꽂히는 프로젝트입니다.

한 줄 총평

MiroFish는 “에이전트를 여러 개 붙였다” 수준의 프로젝트가 아닙니다.

이 프로젝트의 핵심은, 현실 정보를 받아 다중 에이전트 사회를 먼저 만들고 그 안에서 미래를 예측하는 디지털 샌드박스를 지향한다는 점입니다.

에이전트 하네스를 단순 자동화가 아니라 시뮬레이션과 집단 지능 엔진으로 확장하고 싶은 사람이라면, 한 번쯤 자세히 뜯어볼 만한 프로젝트입니다.

참고 링크

GitHub 저장소: https://github.com/666ghj/MiroFish
온라인 데모: https://666ghj.github.io/mirofish-demo/
DeepWiki: https://deepwiki.com/666ghj/MiroFish