# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a character development system implementing Stanford's "Generative Agents" memory architecture for believable AI characters with dynamic personality evolution. The project uses a custom LLM connector that supports any OpenAI-compatible API endpoint, allowing flexible backend configuration.

## Key Architecture Components

### Agent System (living_agents/)
- **Memory Stream**: Stanford's memory architecture with observations, reflections, and plans
- **Smart Retrieval**: Combines recency (exponential decay), importance (1-10 scale), and relevance (cosine similarity)
- **Auto-Reflection**: Generates insights when importance threshold (150) is reached
- **Character Components**: Character, CharacterAgent, MemoryStream
- **Trait Development**: Dynamic personality evolution based on experiences
- Uses llm_connector for flexible backend support

### LLM Connector Package
- **Custom LLM abstraction** that supports any OpenAI-compatible API
- **Streaming support** with both reasoning and content chunks
- **Type definitions**: LLMBackend (base_url, api_token, model) and LLMMessage
- Environment variables: BACKEND_BASE_URL, BACKEND_API_TOKEN, BACKEND_MODEL

### Character Explorer CLI
- **CLI Testing Tool**: Interactive character development and testing interface
- **Character Loading**: YAML template system for character initialization
- **Real-time Development**: Direct testing of memory, traits, and personality evolution
- Located in `character_explorer.py` for easy development iteration

## Development Commands

```bash
# Install dependencies
uv sync

# Run the character explorer CLI
uv run python character_explorer.py

# Add new dependencies
uv add <package-name>

# Python environment management
uv python pin 3.12  # Pin to Python 3.12
```

## Important Development Notes

### Character Development Focus
The current focus is on perfecting single-agent character development:
- Characters evolve through experiences and interactions
- Memory system creates realistic personality development
- CLI tool allows rapid testing and iteration

### LLM Integration
The project uses a flexible LLM connector supporting any OpenAI-compatible API.

When implementing new features, use the llm_connector package:
```python
from llm_connector import get_response, LLMBackend, LLMMessage

backend: LLMBackend = {
    'base_url': os.environ['BACKEND_BASE_URL'],
    'api_token': os.environ['BACKEND_API_TOKEN'], 
    'model': os.environ['BACKEND_MODEL']
}

messages: List[LLMMessage] = [
    {'role': 'system', 'content': 'You are...'},
    {'role': 'user', 'content': 'Hello'}
]

# Non-streaming
response = await get_response(backend, messages, stream=False)

# Streaming
async for chunk in await get_response(backend, messages, stream=True):
    if 'content' in chunk:
        # Handle content
    if 'reasoning' in chunk:
        # Handle reasoning (if supported)
```

### Project Structure
- `character_explorer.py`: CLI tool for character development and testing
- `living_agents/`: Core agent system with memory, traits, and prompt management
- `character_templates/`: YAML files defining character backgrounds
- `llm_connector/`: Custom LLM integration package for flexible backend support

### Environment Variables
Required in `.env`:
- `BACKEND_BASE_URL`: LLM API endpoint
- `BACKEND_API_TOKEN`: API authentication token
- `BACKEND_MODEL`: Model identifier

## Current Development Status

The system currently focuses on single-agent character development:
1. Character agents with dynamic personality evolution
2. Stanford-inspired memory architecture
3. CLI testing tool for rapid iteration
4. Flexible LLM backend configuration

Future plans include multi-agent interactions and web interface integration.