# Multi-Agent Roleplay System with Stanford Memory Architecture

This is a Python-based multi-agent roleplay system that implements Stanford's proven "Generative Agents" memory architecture for creating believable AI characters with long-term memory, reflection, and emergent behaviors.

## Core Architecture

### Memory System (Stanford's Approach)
- **Memory Stream**: Each agent maintains observations, reflections, and plans
- **Smart Retrieval**: Combines recency (exponential decay), importance (1-10 scale), and relevance (cosine similarity)
- **Auto-Reflection**: When importance threshold (150) is hit, generates higher-level insights
- **Natural Forgetting**: Older memories become less accessible over time

### Agent Components
- **Character**: Core personality, background, relationships, goals
- **CharacterAgent**: Handles memory, planning, reactions based on Stanford architecture
- **MemoryStream**: Implements the full memory/reflection/planning system
- **SceneManager**: Orchestrates multi-agent interactions and scene state

## Key Features
- Real-time character interactions with persistent memory
- Automatic insight generation (reflections) from accumulated experiences  
- Time advancement that triggers planning and memory decay
- Character-to-character conversations with relationship memory
- Emergent behaviors through memory-driven decision making

## Technology Stack
- Python 3.8+
- OpenAI GPT API (gpt-3.5-turbo for agents, gpt-4o-mini for scene management)
- OpenAI Embeddings API for memory relevance scoring
- scikit-learn for cosine similarity calculations
- Rich character personalities with background relationships and goals

## Research Basis
Based on Stanford's 2023 "Generative Agents" paper that successfully created 25 AI agents in a virtual town who formed relationships, spread information, and coordinated group activities entirely through emergent behavior.

## Development Focus
The system emphasizes psychological realism over game mechanics - agents should behave like real people with genuine memory limitations, emotional consistency, and relationship development over time.