init

project_description.md

@@ -0,0 +1,37 @@
+# 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.