README.md

metadata

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

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