# probablyapigeon/xembra_protocol architecture

> Architecture diagram of the GitHub repository probablyapigeon/xembra_protocol, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/probablyapigeon/xembra_protocol
- Repository: https://github.com/probablyapigeon/xembra_protocol
- Video tour (about a minute): https://gitdiagram.com/probablyapigeon/xembra_protocol/video

## Overview

Xembra is a conversational creature: its runtime scripts accept user interaction and produce layered, stateful responses, drawing on emotional, social, identity, memory, motivation, and world-scene capabilities. The graph shows the root `XEMBRAROBOT.py` runtime and its documented module dependencies; `xembra_creature.py` is a second runtime variant. The sampled excerpts do not establish how either script is launched or show the full response loop, so those actor links are marked unverified. Research experiments and empty core stubs are excluded.

Main entry points: [`xembra_creature.py`](https://github.com/probablyapigeon/xembra_protocol/blob/main/xembra_creature.py) (Creature runtime), [`XEMBRAROBOT.py`](https://github.com/probablyapigeon/xembra_protocol/blob/main/XEMBRAROBOT.py) (Robot runtime), [`modules/attachment.py`](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/attachment.py) (Attachment), [`modules/relationship.py`](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/relationship.py) (Relationship)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Creature runtimes"]
  node_robot["Robot runtime<br/>[XEMBRAROBOT.py]"]
  node_creature["Creature runtime<br/>[xembra_creature.py]"]
end

subgraph group_social["Social and identity"]
  node_attachment["Attachment<br/>[attachment.py]"]
  node_relationship["Relationship<br/>[relationship.py]"]
  node_identity["Identity<br/>[identity.py]"]
end

subgraph group_cognition["Mind and motivation"]
  node_learning["Learning<br/>[learning.py]"]
  node_memory["Memory<br/>[memory.py]"]
  node_goals["Goals<br/>[goals.py]"]
  node_novelty["Novelty<br/>[novelty.py]"]
  node_thought["Thought loop<br/>[thought_loop.py]"]
  node_questions["Question generation"]
end

subgraph group_expression["Response and world"]
  node_emotions["Emotions<br/>[emotions.py]"]
  node_reaction["Reaction generation"]
  node_scene["Scene<br/>[scene.py]"]
  node_world["World scene<br/>[world_scene.py]"]
  node_grandma["Grandma responses<br/>[grandma.py]"]
  node_hug["Hug responses<br/>[hug.py]"]
  node_name["Name handling<br/>[name.py]"]
  node_wordbook["Wordbook<br/>[wordbook.py]"]
end

node_user(("User"))

node_user -.->|"sends input"| node_robot
node_user -.->|"sends input"| node_creature
node_robot -->|"uses"| node_emotions
node_robot -->|"uses"| node_name
node_robot -->|"uses"| node_grandma
node_robot -->|"uses"| node_hug
node_robot -->|"uses"| node_learning
node_robot -->|"uses"| node_wordbook
node_robot -->|"uses"| node_questions
node_robot -->|"uses"| node_relationship
node_robot -->|"uses"| node_attachment
node_robot -->|"uses"| node_identity
node_robot -->|"uses"| node_novelty
node_robot -->|"uses"| node_memory
node_robot -->|"uses"| node_thought
node_robot -->|"uses"| node_goals
node_robot -->|"uses"| node_scene
node_robot -->|"uses"| node_world
node_creature -->|"uses"| node_emotions
node_creature -->|"uses"| node_name
node_creature -->|"uses"| node_grandma
node_creature -->|"uses"| node_hug
node_creature -->|"uses"| node_learning
node_creature -->|"uses"| node_wordbook
node_creature -->|"uses"| node_questions
node_creature -->|"uses"| node_relationship
node_creature -->|"uses"| node_attachment
node_creature -->|"uses"| node_identity
node_creature -->|"uses"| node_novelty
node_creature -->|"uses"| node_memory
node_creature -->|"uses"| node_thought
node_creature -->|"uses"| node_goals
node_creature -->|"uses"| node_scene
node_creature -->|"uses"| node_world
node_creature -->|"uses"| node_reaction

click node_robot "https://github.com/probablyapigeon/xembra_protocol/blob/main/XEMBRAROBOT.py"
click node_creature "https://github.com/probablyapigeon/xembra_protocol/blob/main/xembra_creature.py"
click node_attachment "https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/attachment.py"
click node_relationship "https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/relationship.py"
click node_identity "https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/identity.py"
click node_emotions "https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/emotions.py"
click node_reaction "https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/reaction_generator.py"
click node_scene "https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/scene.py"
click node_world "https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/world_scene.py"
click node_grandma "https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/grandma.py"
click node_hug "https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/hug.py"
click node_name "https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/name.py"
click node_wordbook "https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/wordbook.py"
click node_learning "https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/learning.py"
click node_memory "https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/memory.py"
click node_goals "https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/goals.py"
click node_novelty "https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/novelty.py"
click node_thought "https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/thought_loop.py"
click node_questions "https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/question_generator.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_robot,node_creature,node_user toneBlue
class node_attachment,node_relationship,node_identity toneAmber
class node_learning,node_memory,node_goals,node_novelty,node_thought,node_questions toneMint
class node_emotions,node_reaction,node_scene,node_world,node_grandma,node_hug,node_name,node_wordbook toneRose
```

## Components

### Creature runtimes

- [Robot runtime](https://github.com/probablyapigeon/xembra_protocol/blob/main/XEMBRAROBOT.py): `XEMBRAROBOT.py`
- [Creature runtime](https://github.com/probablyapigeon/xembra_protocol/blob/main/xembra_creature.py): `xembra_creature.py`

### Social and identity

- [Attachment](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/attachment.py): `modules/attachment.py`
- [Relationship](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/relationship.py): `modules/relationship.py`
- [Identity](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/identity.py): `modules/identity.py`

### Mind and motivation

- [Learning](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/learning.py): `modules/learning.py`
- [Memory](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/memory.py): `modules/memory.py`
- [Goals](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/goals.py): `modules/goals.py`
- [Novelty](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/novelty.py): `modules/novelty.py`
- [Thought loop](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/thought_loop.py): `modules/thought_loop.py`
- [Question generation](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/question_generator.py): `modules/question_generator.py`

### Response and world

- [Emotions](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/emotions.py): `modules/emotions.py`
- [Reaction generation](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/reaction_generator.py): `modules/reaction_generator.py`
- [Scene](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/scene.py): `modules/scene.py`
- [World scene](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/world_scene.py): `modules/world_scene.py`
- [Grandma responses](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/grandma.py): `modules/grandma.py`
- [Hug responses](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/hug.py): `modules/hug.py`
- [Name handling](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/name.py): `modules/name.py`
- [Wordbook](https://github.com/probablyapigeon/xembra_protocol/blob/main/modules/wordbook.py): `modules/wordbook.py`

### Other components

- **User**

## Connections

- User → Robot runtime: sends input
- User → Creature runtime: sends input
- Robot runtime → Emotions: uses (evidence: `XEMBRAROBOT.py`)
- Robot runtime → Name handling: uses (evidence: `XEMBRAROBOT.py`)
- Robot runtime → Grandma responses: uses (evidence: `XEMBRAROBOT.py`)
- Robot runtime → Hug responses: uses (evidence: `XEMBRAROBOT.py`)
- Robot runtime → Learning: uses (evidence: `XEMBRAROBOT.py`)
- Robot runtime → Wordbook: uses (evidence: `XEMBRAROBOT.py`)
- Robot runtime → Question generation: uses (evidence: `XEMBRAROBOT.py`)
- Robot runtime → Relationship: uses (evidence: `XEMBRAROBOT.py`)
- Robot runtime → Attachment: uses (evidence: `XEMBRAROBOT.py`)
- Robot runtime → Identity: uses (evidence: `XEMBRAROBOT.py`)
- Robot runtime → Novelty: uses (evidence: `XEMBRAROBOT.py`)
- Robot runtime → Memory: uses (evidence: `XEMBRAROBOT.py`)
- Robot runtime → Thought loop: uses (evidence: `XEMBRAROBOT.py`)
- Robot runtime → Goals: uses (evidence: `XEMBRAROBOT.py`)
- Robot runtime → Scene: uses (evidence: `XEMBRAROBOT.py`)
- Robot runtime → World scene: uses (evidence: `XEMBRAROBOT.py`)
- Creature runtime → Emotions: uses (evidence: `xembra_creature.py`)
- Creature runtime → Name handling: uses (evidence: `xembra_creature.py`)
- Creature runtime → Grandma responses: uses (evidence: `xembra_creature.py`)
- Creature runtime → Hug responses: uses (evidence: `xembra_creature.py`)
- Creature runtime → Learning: uses (evidence: `xembra_creature.py`)
- Creature runtime → Wordbook: uses (evidence: `xembra_creature.py`)
- Creature runtime → Question generation: uses (evidence: `xembra_creature.py`)
- Creature runtime → Relationship: uses (evidence: `xembra_creature.py`)
- Creature runtime → Attachment: uses (evidence: `xembra_creature.py`)
- Creature runtime → Identity: uses (evidence: `xembra_creature.py`)
- Creature runtime → Novelty: uses (evidence: `xembra_creature.py`)
- Creature runtime → Memory: uses (evidence: `xembra_creature.py`)
- Creature runtime → Thought loop: uses (evidence: `xembra_creature.py`)
- Creature runtime → Goals: uses (evidence: `xembra_creature.py`)
- Creature runtime → Scene: uses (evidence: `xembra_creature.py`)
- Creature runtime → World scene: uses (evidence: `xembra_creature.py`)
- Creature runtime → Reaction generation: uses (evidence: `xembra_creature.py`)
