whatisgithub

What is ai-town?

ambrosex/ai-town — explained in plain English

Analysis updated 2026-08-04 · repo last pushed 2023-09-09

Audience · developerComplexity · 4/5DormantSetup · hard

In one sentence

AI Town is a starter kit for building a virtual town where AI characters chat, remember past events, and socialize on their own. You customize characters and maps, then watch their interactions unfold.

Mindmap

mindmap
  root((repo))
    What it does
      AI characters interact
      Running memory journal
      Live demo included
    Tech stack
      JavaScript and TypeScript
      Convex game engine
      OpenAI for dialogue
    External services
      Pinecone memory storage
      Clerk user login
      Fly.io hosting
    Use cases
      Emergent storytelling games
      Social behavior research
      Interactive AI prototypes
    Customization
      Edit character configs
      Swap maps and art
      Change background music
    Audience
      Game builders
      Researchers
      Founders

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

What do people build with it?

USE CASE 1

Build a game with emergent storytelling where AI characters form relationships and hold conversations on their own.

USE CASE 2

Run social behavior simulations by creating characters with different personalities and observing how they interact on a shared map.

USE CASE 3

Prototype an interactive AI experience by customizing characters, swapping art and music, then watching how the town plays out.

USE CASE 4

Experiment with AI memory by giving characters past experiences and seeing how their recall shapes future conversations.

What is it built with?

TypeScriptJavaScriptConvexOpenAIPineconeClerkFly.io

How does it compare?

ambrosex/ai-town00kaku/gallery-slider-block04amanrajj/netwatch
Stars0
LanguageJavaScriptRust
Last pushed2023-09-092021-05-19
MaintenanceDormantDormant
Setup difficultyhardeasymoderate
Complexity4/52/53/5
Audiencedevelopergeneralops devops

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · hard Time to first run · 1h+

Requires configuring four external services, OpenAI, Pinecone, Clerk, and Convex, each with its own account and API keys before the project will run.

The license terms are not specified in the repository explanation, so it is unclear what permissions apply to using this code.

So what is it?

AI Town is a starter kit that lets you create a virtual town populated by AI characters who go about their lives, talk to each other, and socialize on their own. You can think of it as a petri dish for artificial personalities, you set up the characters and their world, then watch them interact. It comes with a live demo so you can see what a finished version looks like before building your own. Under the hood, each character is powered by a large language model (the same kind of technology behind ChatGPT) that decides what they say and do moment to moment. The project keeps a running journal of everything that happens, so characters can remember past conversations and events. It also stores memories in a way that lets characters recall relevant experiences, which is what makes their behavior feel coherent over time rather than random. The whole thing runs in JavaScript and TypeScript, which the creators note is unusual, most similar projects are written in Python. This would appeal to someone building a game with emergent storytelling, a researcher experimenting with simulated social behavior, or a founder prototyping an interactive AI experience. For example, you could create a town of characters with different personalities, drop them into a shared map, and see how relationships and conversations unfold, then tweak character descriptions, swap in new art, change the background music, and run it again to get different results. The project pulls together several external services: OpenAI for the character dialogue, Pinecone for memory storage, Clerk for user login, and Convex as the game engine and database. It can be deployed to Fly.io for hosting. Customization is straightforward, characters, maps, music, and art are all defined in configuration files that you edit directly. The README notes that the backend is designed to scale from a simple personal experiment up to a multiplayer game, with built-in support for shared state and transaction safety.

Copy-paste prompts

Prompt 1
Help me set up AI Town locally. I have cloned the repo and installed Node.js. Walk me through configuring the OpenAI, Pinecone, Clerk, and Convex environment variables step by step.
Prompt 2
I want to add a new character to AI Town with a grumpy personality who loves gardening. Show me which configuration file to edit and how to define the character's name, personality, and starting position on the map.
Prompt 3
How do I deploy my AI Town project to Fly.io after I have it running locally and have all my environment variables configured?
Prompt 4
I want to replace the default map and background music in AI Town with my own assets. Explain where those files are defined and how to point the config to my custom art and audio.
Prompt 5
Help me understand how AI Town stores character memories using Pinecone. Walk me through how a character recalls a past conversation and how that memory influences their next action.

Frequently asked questions

What is ai-town?

AI Town is a starter kit for building a virtual town where AI characters chat, remember past events, and socialize on their own. You customize characters and maps, then watch their interactions unfold.

Is ai-town actively maintained?

Dormant — no commits in 2+ years (last push 2023-09-09).

What license does ai-town use?

The license terms are not specified in the repository explanation, so it is unclear what permissions apply to using this code.

How hard is ai-town to set up?

Setup difficulty is rated hard, with roughly 1h+ to a first successful run.

Who is ai-town for?

Mainly developer.

Open on GitHub → Ask about another repo

This repo across BitVibe Labs

Verify against the repo before relying on details.