A D&D simulator where AI characters develop through lived experiences using temporal consciousness and cultural transmission. Characters have personal memories, learn from each other, and evolve through gameplay.
Comprehensive documentation is available in the docs/ directory:
- INDEX.md - Documentation hub and navigation guide
- ARCHITECTURE.md - Complete system architecture and design
- DEVELOPER.md - Developer guide with API reference
- USER_GUIDE.md - User documentation and tutorials
- EXAMPLES.md - Practical examples and use cases
- Personal Vector Databases: Each character has their own vector DB storing subjective memories
- Memory Consolidation: Episodic memories (events) automatically consolidate into semantic knowledge (understanding)
- Autobiographical Narratives: Characters build coherent life stories from experiences
- Identity Persistence: Characters maintain consistent personalities while allowing growth
- Character Laptops: Personal notebooks with journal entries, documents, and private LLM access
- D&D Mechanics: Full D&D 5e stats (ability scores, HP, AC, skills)
- Memory-Driven Decisions: Characters make choices based on personality + past experiences
- Cultural Learning: Characters learn skills from each other
- D&D Sessions: Turn-based gameplay with initiative, combat, and skill checks
- DM System: Human Dungeon Master with master vector DB for world lore
- Real-time Updates: WebSocket support for live gameplay
- Session Transcripts: Complete recording of all events for memory formation
- Learn from human players' decisions
- Observe behavioral patterns (timing, preferences, strategies)
- Create AI doubles that mimic play style
- Docker & Docker Compose
- OpenAI API key (for LLM calls)
- (Optional) Anthropic API key
- Clone and setup:
cd /home/claude/ai_society_dnd
cp .env.example .env
# Edit .env and add your API keys- Start services:
docker-compose up -dThis starts:
- Qdrant (vector database) on
localhost:6333 - Backend API on
localhost:8000
- Verify it's running:
curl http://localhost:8000/health# 1. Create a campaign
curl -X POST http://localhost:8000/campaigns/create \
-H "Content-Type: application/json" \
-d '{
"campaign_name": "Lost Mine of Phandelver",
"dm_id": "human_dm",
"initial_world_lore": [
"The town of Phandalin sits on the edge of the Sword Coast.",
"Gundren Rockseeker has discovered the location of Wave Echo Cave."
]
}'
# 2. Create a character
curl -X POST http://localhost:8000/characters/create \
-H "Content-Type: application/json" \
-d '{
"name": "Thorin Ironforge",
"race": "Dwarf",
"class_name": "Fighter",
"level": 1,
"personality_traits": ["Brave", "Stubborn", "Loyal"],
"backstory": "A dwarf warrior seeking to reclaim his ancestral mine.",
"strength": 16,
"dexterity": 12,
"constitution": 14,
"intelligence": 10,
"wisdom": 11,
"charisma": 8
}'
# Save the character_id from the response!
# 3. Create a game session
curl -X POST http://localhost:8000/sessions/create \
-H "Content-Type: application/json" \
-d '{
"campaign_name": "Lost Mine of Phandelver",
"session_number": 1
}'
# Save the session_id from the response!
# 4. Join the session
curl -X POST http://localhost:8000/sessions/join \
-H "Content-Type: application/json" \
-d '{
"session_id": "Lost Mine of Phandelver_session_1",
"character_id": "YOUR_CHARACTER_ID_HERE"
}'curl -X POST http://localhost:8000/sessions/dm_narrate \
-H "Content-Type: application/json" \
-d '{
"session_id": "Lost Mine of Phandelver_session_1",
"narration": "You find yourselves on the High Road, escorting a wagon to Phandalin. Suddenly, you see two dead horses blocking the path ahead."
}'curl -X POST http://localhost:8000/sessions/character_action \
-H "Content-Type: application/json" \
-d '{
"session_id": "Lost Mine of Phandelver_session_1",
"character_id": "YOUR_CHARACTER_ID",
"action_description": "I approach cautiously, battleaxe in hand, looking for signs of an ambush.",
"action_type": "roleplay"
}'curl -X POST http://localhost:8000/characters/YOUR_CHARACTER_ID/skill_check \
-H "Content-Type: application/json" \
-d '{
"skill": "perception",
"advantage": false,
"disadvantage": false
}'curl -X POST http://localhost:8000/sessions/combat/start \
-H "Content-Type: application/json" \
-d '{
"session_id": "Lost Mine of Phandelver_session_1",
"enemies": [
{"name": "Goblin 1", "dex_mod": 2},
{"name": "Goblin 2", "dex_mod": 1},
{"name": "Goblin 3", "dex_mod": 2}
]
}'curl -X POST http://localhost:8000/sessions/combat/action \
-H "Content-Type: application/json" \
-d '{
"session_id": "Lost Mine of Phandelver_session_1",
"attacker_id": "YOUR_CHARACTER_ID",
"action_type": "attack",
"target_id": "enemy_0",
"weapon": "Battleaxe",
"attack_bonus": 5,
"damage_dice": "1d8",
"damage_bonus": 3
}'curl http://localhost:8000/sessions/Lost_Mine_of_Phandelver_session_1/transcript?recent=10curl http://localhost:8000/characters/YOUR_CHARACTER_ID/memories- During Gameplay: Every action, narration, and event is stored as an episodic memory
- After Session: Memories consolidate into semantic knowledge (patterns, learnings)
- Vector Storage: Memories are embedded and stored in personal vector DB for retrieval
When a character needs to act:
# 1. Query their personal vector DB for relevant memories
relevant_memories = character.vector_store.retrieve_memories(
query="encountering goblins in ambush",
top_k=5
)
# 2. Use memories + personality + situation to decide
decision = await character.make_decision(
situation="Goblins ambush the wagon",
use_memories=True
)
# 3. Character acts based on past experiences
# If they were burned by goblins before → more cautious
# If they defeated goblins easily → more confidentEach character has a "laptop" with:
- Journal entries: Personal reflections on events
- Documents: Notes, maps, letters
- Private LLM access: Can ask questions privately (DM may or may not see)
# Character makes private query
curl -X POST http://localhost:8000/characters/YOUR_CHARACTER_ID/private_query \
-H "Content-Type: application/json" \
-d '{
"query": "What do I know about goblin tactics? Should I be worried?"
}'curl http://localhost:8000/campaigns/Lost_Mine_of_Phandelvercurl http://localhost:8000/characters/YOUR_CHARACTER_IDcurl http://localhost:8000/health┌─────────────────────────────────────────────────────────┐
│ Human DM (Dungeon Master) │
│ - Master Vector DB (world lore, campaign history) │
│ - NPC control │
│ - Oversight and narrative control │
└────────────────────┬────────────────────────────────────┘
│
│
┌────────────────────▼────────────────────────────────────┐
│ Game Session (D&D Room) │
│ - Turn-based gameplay │
│ - Combat encounters │
│ - Skill checks & dice rolls │
│ - Transcript recording │
└────────────────────┬────────────────────────────────────┘
│
┌────────────┼────────────┐
│ │ │
┌───────▼──────┐ ┌──▼──────┐ ┌──▼──────┐
│ Character 1 │ │ Char 2 │ │ Char 3 │
│ │ │ │ │ │
│ Personal │ │Personal │ │Personal │
│ Vector DB │ │VectorDB │ │VectorDB │
│ │ │ │ │ │
│ Memory │ │Memory │ │Memory │
│ System │ │System │ │System │
│ │ │ │ │ │
│ Laptop │ │Laptop │ │Laptop │
│ (Journal) │ │(Journal)│ │(Journal)│
└──────────────┘ └─────────┘ └─────────┘
| Endpoint | Method | Description |
|---|---|---|
/ |
GET | Health check |
/health |
GET | Detailed health status |
| Endpoint | Method | Description |
|---|---|---|
/characters/create |
POST | Create new character |
/characters/{id} |
GET | Get character details |
/characters/{id}/memories |
GET | Get character memories |
/characters/{id}/journal |
GET | Get journal entries |
/characters/{id}/private_query |
POST | Private LLM query |
/characters/{id}/skill_check |
POST | Make skill check |
| Endpoint | Method | Description |
|---|---|---|
/campaigns/create |
POST | Create new campaign |
/campaigns/{name} |
GET | Get campaign stats |
/campaigns/{name}/lore |
POST | Add world lore |
/campaigns/{name}/lore?query=X |
GET | Query world lore |
| Endpoint | Method | Description |
|---|---|---|
/sessions/create |
POST | Create game session |
/sessions/join |
POST | Join character to session |
/sessions/{id} |
GET | Get session details |
/sessions/{id}/transcript |
GET | Get session transcript |
/sessions/dm_narrate |
POST | DM narrates |
/sessions/character_action |
POST | Character acts |
/sessions/{id}/end |
POST | End session |
| Endpoint | Method | Description |
|---|---|---|
/sessions/combat/start |
POST | Start combat |
/sessions/combat/action |
POST | Combat action |
/sessions/{id}/combat/end |
POST | End combat |
Memories automatically consolidate after sessions:
# Episodic: "I fought goblins near the wagon"
# ↓ (consolidation)
# Semantic: "Goblins often ambush on roads near forests"Characters can learn skills from each other:
# Character A teaches Character B stealth tactics
cultural_engine.teach_skill(
teacher_id="char_a",
learner_id="char_b",
skill_name="Forest Stealth"
)Characters maintain core personality while growing:
identity_system.get_identity_coherence_index()
# > 0.7 = healthy personality
# 0.4-0.7 = monitor for drift
# < 0.4 = intervention needed# Install dependencies
cd backend
pip install -r requirements.txt
# Start Qdrant separately
docker run -p 6333:6333 qdrant/qdrant:latest
# Set environment variables
export OPENAI_API_KEY=your_key_here
export QDRANT_URL=http://localhost:6333
# Run server
python api_server.pyai_society_dnd/
├── backend/
│ ├── api_server.py # FastAPI server
│ ├── enhanced_character.py # Character system
│ ├── game_mechanics.py # D&D rules engine
│ ├── game_room.py # Game sessions & DM
│ ├── memory_system.py # Temporal consciousness
│ ├── vector_memory.py # Vector DB integration
│ ├── cultural_transmission.py # Skill learning
│ ├── requirements.txt
│ └── Dockerfile
├── data/
│ ├── qdrant_storage/ # Vector DB persistence
│ └── logs/ # Application logs
├── docker-compose.yml
├── .env.example
└── README.md
- Character system with D&D stats
- Memory consolidation engine
- Personal vector databases
- Game sessions and rooms
- DM system with master DB
- Combat mechanics
- Character laptops (journals)
- Web UI for easier interaction
- Skill learning between characters
- Advanced memory pathology detection
- Model routing (GPT-4 for complex, GPT-3.5 for simple)
- Record human player behavior
- Train behavioral models
- Create AI doubles of players
- DM digital twin for encounter design
- Multi-agent coordination
- Emergent social dynamics
- Dynamic world generation
- Self-directed quests
- DM creates campaign: "Curse of Strahd"
- Players create characters: Warrior, Rogue, Wizard
- DM starts session: "You arrive in the village of Barovia..."
- Characters act: Based on personalities + memories
- Combat: Initiative, attacks, spell casting
- Memories form: Each character stores experiences
- Session ends: Memories consolidate overnight
- Next session: Characters remember previous events
This is a prototype system. Key areas for contribution:
- UI Development: Build React/Vue frontend
- Memory Optimization: Improve consolidation algorithms
- Game Mechanics: Expand D&D rule coverage
- Digital Twin: Implement behavior learning
MIT License - See LICENSE file
Built with:
- FastAPI for API server
- LangChain for LLM integration
- Qdrant for vector storage
- Sentence Transformers for embeddings
Ready to play? Start with docker-compose up and follow the Quick Start guide!