diff --git a/README.md b/README.md index c90d979..6b3721b 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/docs/architecture/aetheria-persistent-agent-architecture.md b/docs/architecture/aetheria-persistent-agent-architecture.md new file mode 100644 index 0000000..88bf1f6 --- /dev/null +++ b/docs/architecture/aetheria-persistent-agent-architecture.md @@ -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. diff --git a/docs/research/things-to-steal.md b/docs/research/things-to-steal.md index 99b0ef6..0355805 100644 --- a/docs/research/things-to-steal.md +++ b/docs/research/things-to-steal.md @@ -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