A small agent-based social simulation inspired by Stanford's Generative Agents: Interactive Simulacra of Human Behavior. A handful of NPCs live in a shared town, each with their own personality, needs, and memory — and their relationships evolve based on how their conversations actually go.
Each agent tracks:
- Needs — energy, social, and entertainment levels that drift over time and drive mood (happy, tired, lonely, content, etc.)
- Personality — friendly, reserved, outgoing, thoughtful, or curious, which shapes how they behave and how they experience the same event differently from another agent
- Memory — a short-term rolling log of recent events, plus a smaller set of emotionally significant "persistent memories" that shape future location preferences and affinities toward other agents
- Relationships — a running score toward every other agent, moving from stranger → acquaintance → friend (or dislike → enemy) based on interaction history
When two agents meet, the simulation generates a conversation between them and then analyzes it separately from each agent's point of view — the same exchange can land as a warm moment for one agent and be draining or forgettable for the other, depending on their personality, energy, and history together. That asymmetry (and the resulting divergent-experience flag when the gap is large) is the core idea I wanted to explore.
Two conversation/analysis backends are supported:
- Simple mode — fast, deterministic, template-based conversations and rule-based emotional scoring. No dependencies, runs anywhere.
- LLM mode — calls the Anthropic API to generate in-character dialogue and to analyze it per-agent, with a fallback to simple mode if the call fails.
State is fully save/loadable (pickled to town_state.pkl), so a simulation can be paused and resumed across sessions.
pipenv install
pipenv run python virtual_town.pyThe simulation runs as an interactive CLI: choose how many timesteps to advance, inspect any agent's current state and relationships, or replay a specific conversation with its full per-agent analysis breakdown.
To enable LLM mode, set use_llm=True when constructing VirtualTown and make sure requests is installed and ANTHROPIC_API_KEY behavior is wired up for your environment — LLM mode is off by default so the project runs with zero setup.
I wanted to prototype a lightweight version of the "generative agents" idea, with the key difference being that two people can live through the same conversation and walk away with completely different read on it. Modeling agents as unreliable narrators of their own social lives — rather than agents with one shared ground truth — would allow for emergent relationships without set consequences to form.
- A minimal 2D visualization of agents moving between locations
- Multi-agent group conversations instead of strictly pairwise