# Agent Architecture

#### 🧠 Overview: How Agents Work

Oxyde agents are **LLM-powered actors** that:

1. Maintain internal state (emotion, memory, goals)
2. Perceive external input (chat, events, player actions)
3. Dynamically construct prompts from their state
4. Query a selected LLM for a response
5. Emit structured actions, emotions, or replies

***

#### 🔁 The Agent Loop

Each frame or turn, agents:

```
[Input Received]
     ↓
[Update Emotion State]
     ↓
[Recall Relevant Memories]
     ↓
[Reweight & Reprioritize Goals]
     ↓
[Construct Prompt]
     ↓
[Route to LLM]
     ↓
[Parse & Act on Response]
```

***

#### 🧠 Emotional State

Agents maintain a 6D emotional vector:

| Emotion   | Type               |
| --------- | ------------------ |
| Curiosity | Positive           |
| Trust     | Positive           |
| Anger     | Negative           |
| Fear      | Negative           |
| Happiness | Positive           |
| Energy    | Neutral/modulatory |

This vector:

* Decays naturally over time
* Is influenced by inputs or LLM responses
* Shapes tone and memory recall bias

***

#### 📘 Memory System

Each memory has:

* `content`: what happened
* `tags`: emotional tags (e.g., "trust", "fear")
* `importance`: how strong its weight is
* `recency`: timestamp for freshness

At runtime, top-K memories are recalled and injected into prompts. Memory can be:

* **Short-term** (session)
* **Long-term** (persistent, WIP)

***

#### 🎯 Goal Engine

Agents have a list of goal objects with:

* `description`
* `priority` (float)
* optional `trigger` (event or condition)

Goals can be reprioritized dynamically based on:

* New memories
* Player interaction
* Emotional state

Agents behave differently when pursuing different goals — like “explore” vs. “protect”.

***

#### 🔄 State Update Frequency

Agents can run:

* **Every frame** (WASM, native)
* **Every dialogue event** (Unity, Unreal)
* **Interval-based** (idle simulation loops)

Runtime config controls this behavior per agent.