# AgentSim

> Multi-agent social simulation engine powered by Claude AI. Drop AI agents into a world and watch what happens.

AgentSim is an open-source (Apache 2.0) runtime system that creates AI-powered social simulations with emergent behavior. Agents are defined with Big Five personality traits (Openness, Conscientiousness, Extraversion, Agreeableness, Neuroticism), memories, goals, values, and fears. They interact autonomously — forming alliances, building or breaking trust, and generating unscripted narratives.

## Key Information

- **Product**: AgentSim
- **Type**: Multi-agent social simulation engine
- **AI Model**: Powered by Anthropic Claude
- **License**: Apache 2.0 — Free and open source forever
- **Source Code**: https://github.com/vinimartinson/agent-sim
- **Website**: https://www.agentsim.io
- **Author**: Vinicius Martinson

## Core Capabilities

### Big Five Personality Engine
Agents are shaped by O/C/E/A/N personality scores (0–100), combined with personal values, fears, and goals. Each agent has a unique behavioral fingerprint that drives decision-making.

### Emergent Social Dynamics
Trust and tension evolve through directional agent-to-agent relationships. Alliances form, conflicts arise, and social hierarchies emerge — all without scripted logic or predefined outcomes.

### God Mode
Inject events mid-simulation, send secret messages to specific agents, and observe private reasoning and memory state in real time. Full control over the simulation environment.

### Compressed Memory System
Each agent maintains a private memory store (jsonb array, capped at 40 entries). When the memory threshold is reached, older memories are auto-compressed via Claude summarization, preserving key context while staying within limits.

### Real-Time Streaming
ActionCable broadcasts tick events over WebSocket. Watch agents process decisions in parallel with a live dashboard and D3 network visualization of relationships.

### Presets and Custom Worlds
Four built-in scenarios plus a custom world builder. Define environments, add agents with custom personality traits, and configure simulation parameters.

## Built-In Scenarios

1. **The Cabin** (Survival) — Four strangers trapped in a remote Norwegian cabin during a snowstorm. Agents: Nora (analyst), Dayo (charmer), Ingrid (survivor), Felix (wildcard).
2. **The Office** (Workplace) — Dunder Mifflin-inspired office crisis. Agents: Michael Scott, Dwight Schrute, Jim Halpert, Pam Beesly.
3. **Hospital** (High-Stakes) — Night shift ER under pressure with limited resources. Agents: Dr. Rivera, Nurse Okafor, Dr. Chen, Nurse Kowalski.
4. **Startup** (Pressure) — NovaTech HQ, 48 hours to investor demo with a broken core feature. Agents: Alex (founder), Maya (engineer), Jordan (hustler), Sam (designer).

## Technical Architecture

AgentSim processes simulations in discrete "ticks." Each tick follows four phases:

1. **Perceive** — Agents observe public actions and receive private messages.
2. **Decide** — Claude evaluates personality, memory, relationships, and context to choose an action.
3. **Act** — The chosen action is broadcast, relationships update, and memory is stored.
4. **Reflect** — Agents compress and consolidate memories when thresholds are reached.

## Tech Stack

- **Backend**: Ruby on Rails with ActionCable (WebSocket)
- **AI**: Anthropic Claude API for agent cognition and memory summarization
- **Database**: PostgreSQL with jsonb for agent memory and personality storage
- **Frontend Dashboard**: React, TypeScript, Tailwind CSS, D3.js for network visualization
- **Real-Time**: WebSocket streaming of simulation events

## Quick Start

```bash
git clone https://github.com/vinimartinson/agent-sim.git
cd agent-sim
bundle install
rails db:setup
rails server
```

## Use Cases

- **AI Research**: Study emergent behavior in multi-agent systems
- **Game Design**: Prototype NPC social dynamics and narrative generation
- **Education**: Teach social psychology and group dynamics through simulation
- **Storytelling**: Generate unscripted character-driven narratives
- **Team Dynamics**: Model workplace scenarios and conflict resolution

## Contact

- GitHub: https://github.com/vinimartinson
- Repository: https://github.com/vinimartinson/agent-sim
- Website: https://www.agentsim.io