Ghostlight/docs/architecture/aetheria-persistent-agent-architecture.md

# Aetheria Persistent Agent Architecture

This is the companion document to
[Things To Steal](../research/things-to-steal.md).

For the first concrete target, see
[Aetheria Content Generation Targets](./aetheria-content-generation-targets.md).

For the scaling model that explains how a crowded region can be simulated with
a relatively small persistent cast, see
[Aetheria Agent Population Model](./aetheria-agent-population-model.md).

For the deeper note on how culture, personality distributions, memory, and
perceived state should project into prompts, see
[Agent State Distributions And Prompt Projection](./agent-state-distributions-and-prompt-projection.md).

That document is the theft list. This one is the machine we are trying to build
out of the stolen parts.

The long-horizon 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

The near-term target is content generation and story scaffolding, not a
standalone game slice. Ghostlight should first help Aetheria authors generate
dialogue, scene pressure, procedural drama, and character reactions from
explicit social state.

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 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 Supporting Stack Maps To This

The nice part is that some useful scaffolding already exists elsewhere.

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, the existing conversational stack 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: Authoring Cast Spine

- explicit agent identity dossiers
- explicit goal objects
- explicit relationship objects
- episodic + semantic memory split

### Phase 2: Dialogue And Drama Scaffolding

- prompt projection for scene and dialogue drafts
- relationship-aware dialogue skeletons
- conflict beat generation from incompatible goals
- author-visible rationale for generated moves

### Phase 3: Social Simulation

- scene objects
- scene scheduler
- relationship updates from scenes
- goal revision from scenes

### Phase 4: Persistent World

- region state
- off-screen strategic ticking
- rumor/news propagation
- faction and economy hooks

### Phase 5: Human Integration

- live player-facing interactions
- persistent human reputation
- access, trust, and consequence systems

### Phase 6: 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.