Cognitive agent simulation template README
City, civilization, and planetary layers describe external dynamics: resources, governance, interactions, regimes, collapse, renewal. The cognitive agent layer describes internal dynamics: perception, memory, belief, motivation, coordination, and choice—bounded by time, attention, and legitimacy.
An agent here is not a personality. It’s a constraint‑shaped decision process.
Purpose#
This template set exists to:
- define agent architecture compatible with EcoEchoSystem’s substrate-first design
- standardize cognition primitives for humans, institutions, and hybrid entities
- support multi-agent simulation with bounded rationality and social influence
- enable AI-assisted exploration without turning agents into oracles
- preserve S/E/R coherence inside minds, not just societies
What belongs in this folder#
This directory contains templates for modeling cognition as a system:
- agent loops (perceive → interpret → decide → act → learn)
- memory systems (short, long, institutional, cultural)
- belief and narrative dynamics (legitimacy, ideology, identity)
- attention and salience (what gets noticed vs ignored)
- motivation and utility proxies (needs, values, status, safety)
- coordination and trust (networks, reputation, signaling)
- conflict and persuasion (propaganda, misinformation, polarization)
- time-bounded learning (habituation, trauma, forgetting, drift)
If a mechanism changes how agents choose, it belongs here.
Substrate alignment for cognition#
Cognitive models must remain compatible with the EcoEchoSystem substrate:
- Structure (S): internal representations, social graphs, roles, institutional scaffolds
- Activation (E): stress, urgency, arousal, persuasion intensity, conflict load
- Relational time (R): attention cycles, memory half-life, learning lag, generational transmission
Cognition is where activation meets meaning.
Agent classes#
Use these classes as defaults (extend as needed):
- Individual agents: bounded attention, personal memory, local incentives
- Group agents: coalitions, factions, movements, identity clusters
- Institution agents: bureaucracies, courts, markets, churches, guilds
- Hybrid agents: AI-augmented institutions, cybernetic governance, collective intelligence systems
The key distinction is not “human vs AI,” but where memory lives and how decisions propagate.
Recommended file map#
This README is the entry point. Typical companion templates in this folder include:
- agent_loop.md: canonical cognition loop and update rules
- memory_models.md: layered memory, decay, rehearsal, institutional persistence
- belief_narrative_dynamics.md: legitimacy, ideology, identity, myth engines
- attention_salience.md: salience competition, agenda setting, perception filters
- social_influence_networks.md: trust graphs, reputation, diffusion, polarization
- coordination_protocols.md: norms, contracts, enforcement, cooperation failure modes
- agent_metrics.md: observables, instrumentation hooks, diagnostics
If your repo already has different filenames, treat this list as a semantic checklist.
How this connects to other templates#
The cognitive agent layer is the coupling tissue between:
- city simulation: micro choices → emergent urban behavior
- civilization simulation: legitimacy + coordination → regime stability or transition
- cross-civilization interaction: diffusion, rivalry, imitation, propaganda
- planetary simulation: collective action thresholds, coordination emergence
- AI-driven exploration: agents as test subjects, not narrators
Put simply:
Cities and civilizations don’t “decide.” Agents decide.
Regimes are what decisions look like when aggregated over time.
Guardrails#
Cognitive agent simulation must avoid these failure modes:
- omniscient agents: nobody has the full map
- perfect rationality: bounded attention and social bias are primary drivers
- single-utility collapse: humans and institutions optimize across competing motives
- narrative override: stories explain behavior, but do not replace constraints
- deterministic outcomes: path dependence is real; inevitability claims are out-of-scope
Agents are fallible by design.
Minimal “hello world” run#
A minimal cognitive-agent-enabled run should demonstrate:
- perception limits: agents miss signals under load
- belief drift: narratives shift with stress and influence
- coordination thresholds: cooperation fails/succeeds based on trust and legitimacy
- feedback coupling: agent choices shift city/civ metrics, which reshape agent state
If your run doesn’t show feedback, you don’t have cognition yet—you have scripted actors.
Status#
Canonical template README for cognitive agent simulation. Designed to be forked, extended, and used as the onboarding gateway for agent-based cognition in EcoEchoSystem.