GameCult/VoidBot
Watch
9
0
Fork
You've already forked VoidBot
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add Aetheria agent world architecture note

Browse source
This commit is contained in:
Meta Vens 2026-04-25 08:27:54 +01:00
commit 2b627b0d13
3 changed files with 548 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

1
README.md
View file

@ -553,5 +553,6 @@ Reasonable next steps from here:
- [SPEC.md](./SPEC.md)
- [Architecture Overview](./docs/architecture/overview.md)
- [Aetheria Persistent Agent Architecture](./docs/architecture/aetheria-persistent-agent-architecture.md)
- [Things To Steal](./docs/research/things-to-steal.md)
- [TypeScript Workspace Decision](./docs/decisions/0001-typescript-workspace.md)

545
docs/architecture/aetheria-persistent-agent-architecture.md Normal file
View file

@ -0,0 +1,545 @@
# Aetheria Persistent Agent Architecture
This is the companion document to [Things To Steal](../research/things-to-steal.md).
That document is the theft list. This one is the machine we are trying to build out of the stolen parts.
The target is a persistent world full of in-universe agents who:
- remember what happened
- want different things
- collide with each other because their values and interests do not line up
- interact with humans without collapsing into quest dispensers or therapy plushies
The important bit is that the world should not exist solely to flatter the player. Humans are participants, not the sun around which every synthetic little bastard must orbit.
## Design Goals
We want a world where:
- agents persist across sessions
- relationships evolve over time
- off-screen life continues
- conflict emerges from incentives
- the same character remains recognizably themselves under pressure
- human intervention can redirect events without erasing everyone else's agency
We do **not** want:
- a thin layer of LLM chat stapled onto static NPC behavior
- every character becoming a slightly differently dressed assistant
- a world that only animates when a human looks at it
- fake drama generated by random hostility instead of meaningful friction
## World Model
The world should be represented as a persistent simulation with five main state layers:
1. **Canonical world state**
- locations
- factions
- resources
- institutions
- active conflicts
- world-level events
2. **Agent identity state**
- role
- background
- loyalties
- values
- aversions
- appetites
- speech style
3. **Agent dynamic state**
- current location
- current obligations
- current mood / pressure / fatigue
- current social exposure
- short-horizon plans
4. **Relationship state**
- trust
- respect
- resentment
- fascination
- fear
- obligation
- debt
5. **Memory state**
- episodic incidents
- scene summaries
- semantic profile conclusions
- relationship summaries
- active inferred goals and concerns
## Agent Stack
Each agent should be built from explicit layers instead of one giant persona prompt.
### 1. Identity Layer
Relatively stable facts:
- who they are
- what they believe
- what they want to be seen as
- what they cannot tolerate
- what they are drawn toward
This should be treated as durable but revisable. Identity is not immutable, but neither should it drift because the model got bored.
### 2. Relationship Layer
Every important other should have a relationship record, including:
- another agent
- a human player
- a group or faction
The record should track:
- trust
- respect
- resentment
- dependence
- attraction or fascination where relevant
- leverage
- recent unresolved incidents
The point is not to create one friendship slider like a life sim from 2004. The point is to track the actual shape of a social bond.
### 3. Goal Layer
Agents need active goals, not just a biography.
Goals should be:
- private or public
- immediate or long-range
- strategic or emotional
- revisable in response to new information
A goal object should include:
- description
- priority
- time horizon
- emotional stake
- blockers
- dependencies
- known rivals
- likely next moves
### 4. Memory Layer
Memory should be split into:
- **working memory**
- current scene
- immediate context
- active inferences
- **episodic memory**
- timestamped incidents
- where, who, what, consequence
- **scene memory**
- distilled summaries of interactions
- **semantic memory**
- generalized beliefs about self, others, and world
- **relationship memory**
- remembered incidents and inferred patterns tied to a specific other
This is where the current VoidBot interaction-memory work is directly useful.
### 5. Theory-of-Mind Layer
Each active interaction should have a lightweight scratchpad:
- what the other party likely wants
- what they fear
- what they think is happening
- what they are trying to get from me
- how confident we are about those guesses
This should be ephemeral and revisable. First impressions are useful, but worshipping them is how systems become smug and stupid.
## Simulation Tiers
A persistent world cannot run every agent at full dialogue fidelity all the time unless we want to immolate the hardware.
So the world should run on tiers.
### Tier 0: Dormant Persistence
For agents far away from any relevant action:
- maintain location, obligations, and long-horizon goals
- advance the clock coarsely
- update minimal state
### Tier 1: Strategic Tick
For agents in active regions but not in a live scene:
- update goals
- choose broad actions
- move, trade, coordinate, prepare, avoid, investigate
- write compact event records
### Tier 2: Scene Simulation
For agents inside a socially or narratively relevant scene:
- model who is present
- what each actor knows
- what each actor wants
- who is hiding what
- who is under pressure
- resolve short exchanges, negotiations, or conflicts
### Tier 3: Live Interactive Presence
For agents currently engaged with a human or central dramatic scene:
- full dialogue generation
- richer perception and recall
- fine-grained ToM updates
- explicit action selection tied to the live interaction
This tiered model is how we get a world that feels alive without paying for a small national grid.
## Core Loop
At a high level, each active agent loop looks like:
1. Perceive
- scene state
- nearby actors
- new events
- human input
2. Interpret
- what matters
- what changed
- what this implies for goals and relationships
3. Update internal state
- working memory
- ToM scratchpad
- emotional pressure / stance
4. Retrieve memory
- relevant episodes
- relationship incidents
- semantic conclusions
5. Evaluate goals
- what is threatened
- what is newly possible
- what should take precedence now
6. Choose action
- speech
- movement
- trade
- alliance
- concealment
- refusal
- violence
- delay
7. Commit result
- world state update
- event log
- memory writes
8. Reflect later
- consolidate incidents
- revise relationship state
- revise semantic beliefs
- revise goals
## Relationship Engine
The relationship system should be treated as first-class infrastructure, not decorative metadata.
Each relationship record should have:
- scores or categorical state for trust, respect, resentment, obligation, fear, fascination
- a short summary of the current relationship
- the unresolved incidents driving that summary
- known pressure points
- current access level
Example consequences:
- low trust + high obligation = brittle alliance
- low respect + high dependence = contemptuous reliance
- high fascination + high fear = unstable orbit
- high resentment + high access = sabotage risk
That is where drama comes from.
## Goal Engine
Goals should be generated and updated from:
- identity
- current needs
- memory
- faction context
- scene opportunities
- rival actions
We should distinguish between:
- **maintenance goals**
- survive
- maintain station
- avoid exposure
- **strategic goals**
- secure influence
- gain a resource
- undermine a rival
- **emotional goals**
- seek vindication
- restore dignity
- protect someone
- punish betrayal
Emotional goals matter because otherwise every character becomes a boring little optimization engine with no pulse.
## Scene Engine
A scene should be an explicit object, not just “some chat happened.”
A scene record should contain:
- location
- participants
- public stakes
- hidden stakes
- triggering event
- current tension axes
- known facts by actor
- unknown facts by actor
- scene outcome
Useful tension axes:
- status
- safety
- secrecy
- leverage
- affection
- ideology
- scarcity
The scene engine should decide:
- whether to escalate
- whether to de-escalate
- whether to fork into violence, bargain, confession, retreat, or deception
## Human Participation
Humans should be one force in the world, not the privileged audience every character was born to adore.
That means:
- agents should remember human actions
- agents should form durable impressions of specific humans
- agents should change how much they reveal, trust, or tolerate
- agents should be willing to refuse or redirect
- agents should sometimes try to use the human for their own ends
Humans should be able to:
- build alliances
- ruin them
- become symbols
- become liabilities
- become prey
- become confidants
That is much more interesting than “click NPC, receive lore paragraph.”
## Narrative Layer
We should not hard-script drama, but we should summarize it.
The narrative layer should:
- generate personal chronicles from actual events
- generate regional or faction news from high-impact changes
- generate rumor propagation when information is partial or distorted
The crucial rule:
- narrative is downstream of simulation
- not a replacement for simulation
## How The Current VoidBot Stack Maps To This
The nice part is that the scaffolding is already inching in the right direction.
Current useful pieces:
- Postgres-backed persistent state
- Qdrant-backed semantic retrieval
- interaction memory with behavioral dimensions
- source and lore indexing
- provider-side tool use
- owner-safe MCP patterns
What needs to be added:
- multi-agent world state store
- relationship graph
- explicit goal objects
- scene scheduler
- reflection/consolidation jobs for cast state
- tiered simulation runtime
- world-facing tools for observation and action
In other words, VoidBot is already halfway to being a mind-and-memory service. What it lacks is the world model and the cast scheduler.
## Suggested Data Model
At minimum, the persistent store should grow tables or equivalents for:
- `world_regions`
- `world_events`
- `agents`
- `agent_identity_snapshots`
- `agent_dynamic_state`
- `agent_goals`
- `agent_relationships`
- `agent_memories_episodic`
- `agent_memories_scene`
- `agent_memories_semantic`
- `scene_instances`
- `scene_participants`
- `human_agent_interactions`
- `rumors`
Qdrant or equivalent can remain the retrieval layer for:
- episodic recall
- lore retrieval
- source grounding
- scene similarity
But the canonical social and world state should stay relational and inspectable.
## Suggested Runtime Services
The world runtime should likely split into:
- **world scheduler**
- advances ticks
- activates scenes
- downgrades inactive agents
- **agent executor**
- runs an agent turn
- retrieves memory
- updates goals and relationships
- **scene resolver**
- handles active multi-party interactions
- **reflection worker**
- consolidates events into longer-term memory
- **narrative worker**
- writes chronicles and reports
That keeps the system legible instead of letting one monstrous worker do all the thinking and all the plumbing at once.
## Failure Modes To Watch For
### 1. Everyone Becomes The Same Person
The agent voices flatten and all conflict becomes cosmetic.
Countermeasure:
- strong identity layer
- explicit value hierarchy
- personality consistency evaluation
### 2. Memory Becomes Sludge
Everything is stored, nothing is distinguished, retrieval turns to soup.
Countermeasure:
- tiered memory
- write-path filtering
- periodic consolidation
- clear forgetting policy
### 3. Drama Becomes Random Meanness
Characters feel chaotic rather than motivated.
Countermeasure:
- tie conflict to values, history, incentives, and pressure
### 4. Humans Break The World By Existing
Every character over-orients around the nearest player.
Countermeasure:
- keep off-screen goals live
- preserve non-human social gravity
- let humans matter without becoming the axis mundi
### 5. Sycophancy Wears A Costume
The bot sounds spicier but still validates whatever frame the user wants.
Countermeasure:
- explicit anti-sycophancy evaluation
- persistent relationship memory
- boundary-aware response guidance
## Build Order
### Phase 1: Cast Spine
- explicit agent identity dossiers
- explicit goal objects
- explicit relationship objects
- episodic + semantic memory split
### Phase 2: Social Simulation
- scene objects
- scene scheduler
- relationship updates from scenes
- goal revision from scenes
### Phase 3: Persistent World
- region state
- off-screen strategic ticking
- rumor/news propagation
- faction and economy hooks
### Phase 4: Human Integration
- live player-facing interactions
- persistent human reputation
- access, trust, and consequence systems
### Phase 5: Rich Narrative Surface
- chronicles
- regional reports
- replay and spectator tooling
## The Real Ambition
The ambition here is not “better NPC dialogue.”
It is:
- a world with inhabitants
- inhabitants with memory
- memory that changes what they want
- wants that collide
- collisions that produce story
That is the actual prize. Everything else is just wiring and smoke.

2
docs/research/things-to-steal.md
View file

@ -2,6 +2,8 @@
This document is the running backlog of ideas worth stealing from frontier research, adjacent products, and our own better impulses.
If you want the companion systems sketch for turning this into a persistent Aetheria cast engine, see [Aetheria Persistent Agent Architecture](../architecture/aetheria-persistent-agent-architecture.md).
The goal is not to build a chatbot that exists to nod, flatter, and perform a personality like a cheap mask. The goal is a system that can:
- remember specific events