explaingit

tianhangzhuzth/fundamental-ava

Analysis updated 2026-05-18

521PythonAudience · researcherComplexity · 4/5LicenseSetup · moderate

TLDR

A Python framework for simulating large populations of autonomous agents with memory, beliefs, and social models to study how group behaviors and social structures emerge from individual interactions.

Mindmap

mindmap
  root((Ava))
    Agent design
      Episodic memory
      Semantic memory
      Procedural skills
      Belief system
    Social layer
      Relationship tracking
      Theory of mind
      Message bus
    Civilization level
      Norms and culture
      Governance rules
      Population ticks
    Analysis
      Change-point detection
      Emergence measurement
      Statistical confidence
Click or tap to explore — scroll the page freely

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

Run a simulation of 500 agents in a shared environment and measure whether distinct roles like forager or builder emerge without being programmed in.

USE CASE 2

Study how social norms or wealth distribution change over time in a virtual population using the built-in statistical change-point detection.

USE CASE 3

Build a custom agent subclass with a specific behavior strategy and observe how it interacts with and influences the broader population.

USE CASE 4

Inspect individual agent memory and relationship state in real time using the reference dashboard during a running simulation.

What is it built with?

Pythonasyncio

How does it compare?

tianhangzhuzth/fundamental-avapluviobyte/video-production-skillskasothaphie/genrecon
Stars521503478
LanguagePythonPythonPython
Setup difficultymoderateeasyhard
Complexity4/52/55/5
Audienceresearcherdeveloperresearcher

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

How do you get it running?

Difficulty · moderate Time to first run · 30min

Requires Python 3.11 or later, the async architecture means some debugging patterns are different from synchronous code.

Apache 2.0 license, use, modify, and distribute freely including for commercial purposes, with attribution and license notice required.

In plain English

Ava is a Python framework for running large simulations where hundreds or thousands of AI agents live in a shared virtual environment and interact with each other. The goal is to see what kinds of social patterns, roles, and group behaviors emerge naturally from many simple individuals following their own rules, rather than being told to produce those patterns. Each agent in the simulation has its own memory system divided into three layers: episodic memory for specific events it has lived through, semantic memory for facts it has derived from those events, and procedural memory for skills that get reinforced when they succeed. Agents also track relationships with other agents and form beliefs based on what they perceive. The combination of memory, beliefs, and goals drives each agent to choose actions each time step without following a central script. The framework is built to handle scale without collapsing. Each simulation tick runs all agents at the same time using Python's async infrastructure with a controlled limit on how many run simultaneously. A single slow or failing agent does not block the others. The architecture also separates the tracking of social norms, governance rules, and analytical measurement into distinct modules that observe what is happening in the population. A key part of the design is measuring emergence statistically rather than just watching it. If agents start specializing into distinct roles or wealth becomes concentrated, the analysis layer detects that shift using a change-point detection method and associates a confidence score with the observation, rather than relying on visual inspection of charts. The simulation engine itself does not include a visual interface, but a reference dashboard is documented that reads live state from the running simulation and displays each agent's current memory, beliefs, and relationships. Installation requires Python 3.11 or later, and the library is Apache 2.0 licensed. The repository also references a cryptocurrency token called AVA, which appears to be a separate commercial project from the same organization.

Copy-paste prompts

Prompt 1
I want to create a multi-agent simulation with 200 agents using the Ava framework. Show me how to subclass AgentCore, define a deliberate method, set up a Civilization, and run it for 500 ticks.
Prompt 2
How does tiered memory work in Ava? Show me how to record an episodic event, trigger a reflection to extract semantic facts, and retrieve memories by recency and importance.
Prompt 3
I want to detect when agents in my Ava simulation start specializing into distinct roles. How does the EmergenceDetector work and how do I read its output?
Prompt 4
How do I add a governance module to an Ava civilization so agents can propose and vote on rules that then affect their available actions?

Frequently asked questions

What is fundamental-ava?

A Python framework for simulating large populations of autonomous agents with memory, beliefs, and social models to study how group behaviors and social structures emerge from individual interactions.

What language is fundamental-ava written in?

Mainly Python. The stack also includes Python, asyncio.

What license does fundamental-ava use?

Apache 2.0 license, use, modify, and distribute freely including for commercial purposes, with attribution and license notice required.

How hard is fundamental-ava to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is fundamental-ava for?

Mainly researcher.

Open on GitHub → Explain another repo

This repo across BitVibe Labs

Scan in gitsafehub Deploy in gitdeployhub tianhangzhuzth on gitmyhub

Verify against the repo before relying on details.