README.md

---
title: AI Town Clone
emoji: 🏙️
colorFrom: purple
colorTo: blue
sdk: static
pinned: false
tags:
- ml-intern
---

# 🏙️ AI Town Clone — Virtual World with AI Inhabitants

A mobile simulation game where AI characters live, interact, remember, and evolve — built with the Stanford "Generative Agents" architecture.

## Architecture

```
Expo (React Native) + Convex (Realtime Backend) + OpenAI (GPT-4o-mini)
```

## Key Features

- 🗺️ **Town Builder** — 2D Skia canvas with pan/zoom/tap-to-place buildings
- 🤖 **8 AI Characters** — Each with unique personality (Big Five model), backstory, and memory
- 🧠 **Memory System** — Vector-indexed RAG retrieval with recency × importance × relevance scoring
- 💬 **Chat** — Talk to any character; they remember past conversations
- 🔄 **Autonomous Simulation** — Characters observe, plan, act, and converse every 30 seconds
- 🕸️ **Relationship Graph** — Characters form opinions about each other based on interactions
- 🎭 **Reflection** — Characters generate high-level insights when enough happens (Stanford paper threshold: 150)
- 🌤️ **Town Events** — Weather changes, festivals, gossip, random acts of kindness

## Files

| File | Purpose |
|------|---------|
| `convex/schema.ts` | Database schema (9 tables, vector indexes) |
| `convex/memory.ts` | Memory stream with RAG retrieval |
| `convex/agent.ts` | Agent brain: observe → reflect → plan → act |
| `convex/characters.ts` | Character CRUD + user chat (RAG-powered) |
| `convex/world.ts` | Game tick, time, weather, events |
| `convex/town.ts` | Town grid + building management |
| `components/town/TownMap.tsx` | 2D Skia renderer with gestures |
| `components/chat/ChatScreen.tsx` | Chat UI with typing indicator |
| `components/characters/RelationshipGraph.tsx` | Visual relationship web |
| `lib/seed-data.ts` | 8 characters + 8 buildings |

## Setup

```bash
git clone https://huggingface.co/spaces/Muthukumarank/ai-town-clone
npx convex init && npx convex deploy
# Set OPENAI_API_KEY in Convex dashboard
npx expo start
```