666ghj

MiroFish: Simulate Agent Societies to Explore Possible Futures

MiroFish uses LLM-powered agents and a knowledge graph to simulate social scenarios from source material. It is aimed at teams and individuals exploring public opinion, policy, financial signals, or creative what-if scenarios before making decisions.

View on GitHub Compare
Stars
75.7k
Forks
11.6k
Stars, last 30 days
+5,244

Our take

Health score

56/100

How it is scored
Activity
56
Community
39
Issues
63
Pull requests
67

+5,244 stars in the last 30 days

Project history

Daily GitHub snapshots since Oct 7, 2026. History covers stars and forks; health signals are not tracked historically.

Selected snapshot

Stars

85,919

Forks

13,031

Change since Nov 18, 2026: +69 stars·+9 forks

Overview

MiroFish turns source material and a natural-language prediction question into a simulated social world. Its agents have distinct personas, memory, and behavioral logic, and interact to explore possible outcomes. The project is intended to help users examine how events or interventions might unfold, rather than treating a prediction as a guaranteed forecast.

It may suit analysts, decision-makers, and creative users who want to rehearse scenarios through multi-agent simulation. The repository describes a workflow that builds a knowledge graph, configures agents, runs simulations, and generates a report with tools for further interaction.

Key Features

  • Extracts seed information from materials such as news, policy drafts, and financial signals.
  • Builds a GraphRAG knowledge graph and uses it to support agent memory and simulation setup.
  • Generates agents with individual personas and behavioral logic.
  • Runs parallel simulations across two platforms, with dynamic memory updates over time.
  • Accepts prediction requirements in natural language and supports injecting variables during a simulation.
  • Produces prediction reports and allows users to interact with simulated agents and a report agent.

Use Cases

  • Public-opinion analysts can explore possible reactions to a news event or public issue using relevant source reports.
  • Policy and communications teams can rehearse potential responses to a draft policy or public-relations scenario before acting.
  • Financial analysts can explore scenarios based on financial signals, while treating results as simulation outputs rather than assured forecasts.
  • Writers and readers can investigate alternate story outcomes by using a novel or other narrative as seed material.

Getting Started

The README recommends source deployment. Copy .env.example to .env, configure the required LLM and Zep Cloud API keys, then run:

npm run setup:all
npm run dev

See the README for prerequisites, configuration details, and Docker deployment instructions.

Considerations

  • The described results are generated by simulations and should be treated as exploratory scenarios, not reliable guarantees about future events.
  • Setup requires external LLM and Zep Cloud API credentials. The README notes that simulation usage can be high and suggests starting with fewer than 40 rounds.
  • The documented source setup requires Node.js 18 or later, Python 3.11 or 3.12, and uv.
  • The AGPL-3.0 license should be reviewed when adopting or modifying the project, especially for distribution or network deployment.
  • The repository lists 124 open issues, so review current project activity and issues before relying on it for critical workflows.

Found this useful?

Share it with someone who would like MiroFish.