# probablyapigeon/connectedxembra architecture

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

- Interactive diagram: https://gitdiagram.com/probablyapigeon/connectedxembra
- Repository: https://github.com/probablyapigeon/connectedxembra

## Overview

XEMBRA is an experimental, local-first cognitive state machine for observable conversational state changes. The documented workflow begins with an operator entering a turn in the interactive runtime, which coordinates cognitive modules and the associative-memory bridge; the bridge extracts and links concepts for persistent recall. Separate stages cover homeostasis, affect and identity, memory and thought, and environmental context. The graph preserves the README’s major capabilities and CORE MODULES. Relationship evidence is limited: README descriptions and source-index references support the architecture, but unsampled runtime calls are shown only as unverified dashed links.

Main entry points: [`xembra_july_live.py`](https://github.com/probablyapigeon/connectedxembra/blob/main/xembra_july_live.py) (Interactive runtime), [`july_bridge.py`](https://github.com/probablyapigeon/connectedxembra/blob/main/july_bridge.py) (Associative bridge), [`modules/emotions.py`](https://github.com/probablyapigeon/connectedxembra/blob/main/modules/emotions.py) (Emotion system), [`modules/identity.py`](https://github.com/probablyapigeon/connectedxembra/blob/main/modules/identity.py) (Identity drift)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and orchestration"]
  node_live["Interactive runtime"]
  node_bridge["Associative bridge<br/>[july_bridge.py]"]
  node_creature["Creature state machine<br/>[xembra_creature.py]"]
end

subgraph group_state["State and affect"]
  node_brain["Brain state<br/>[brain_state.py]"]
  node_emotions["Emotion system<br/>[emotions.py]"]
  node_identity["Identity drift<br/>[identity.py]"]
  node_attachment["Attachment dynamics<br/>[attachment.py]"]
  node_relationship["Relationship tracking<br/>[relationship.py]"]
  node_goals["Goal dynamics<br/>[goals.py]"]
end

subgraph group_memory["Memory and thought"]
  node_learning["Lexical learning<br/>[learning.py]"]
  node_wordbook[("Associative wordbook<br/>[wordbook.py]")]
  node_memorylog[("Episodic memory<br/>[memory.py]")]
  node_thought["Thought and dreams<br/>[thought_loop.py]"]
end

subgraph group_context["Context and interaction"]
  node_novelty["Novelty scoring<br/>[novelty.py]"]
  node_questions["Question generation"]
  node_world["World scene<br/>[world_scene.py]"]
  node_scene["Scene framing<br/>[scene.py]"]
  node_grandma["Recognition cues<br/>[grandma.py]"]
  node_hug["Comfort cues<br/>[hug.py]"]
  node_name["Name recognition<br/>[name.py]"]
end

node_operator(("Operator"))

node_operator -->|"enters turns"| node_live
node_live -->|"coordinates concepts"| node_bridge
node_live -.->|"runs state machine"| node_creature
node_live -.->|"updates telemetry"| node_brain
node_live -.->|"uses affect"| node_emotions
node_live -.->|"updates identity"| node_identity
node_live -.->|"uses bonding"| node_attachment
node_live -.->|"tracks bonds"| node_relationship
node_live -.->|"updates goals"| node_goals
node_live -.->|"learns words"| node_learning
node_live -.->|"recalls episodes"| node_memorylog
node_live -.->|"generates thought"| node_thought
node_live -.->|"scores novelty"| node_novelty
node_live -.->|"generates questions"| node_questions
node_live -.->|"updates context"| node_world
node_live -.->|"frames scenes"| node_scene
node_live -.->|"checks cues"| node_grandma
node_live -.->|"checks comfort"| node_hug
node_live -.->|"checks names"| node_name
node_bridge -->|"extracts concepts"| node_learning
node_bridge -->|"weaves associations"| node_wordbook
node_bridge -.->|"synthesizes affect"| node_emotions
node_bridge -.->|"updates identity"| node_identity
node_bridge -.->|"supports inquiry"| node_questions
node_bridge -.->|"uses context"| node_world

click node_live "https://github.com/probablyapigeon/connectedxembra/blob/main/xembra_july_live.py"
click node_bridge "https://github.com/probablyapigeon/connectedxembra/blob/main/july_bridge.py"
click node_creature "https://github.com/probablyapigeon/connectedxembra/blob/main/xembra_creature.py"
click node_brain "https://github.com/probablyapigeon/connectedxembra/blob/main/core/brain_state.py"
click node_emotions "https://github.com/probablyapigeon/connectedxembra/blob/main/modules/emotions.py"
click node_identity "https://github.com/probablyapigeon/connectedxembra/blob/main/modules/identity.py"
click node_attachment "https://github.com/probablyapigeon/connectedxembra/blob/main/modules/attachment.py"
click node_relationship "https://github.com/probablyapigeon/connectedxembra/blob/main/modules/relationship.py"
click node_goals "https://github.com/probablyapigeon/connectedxembra/blob/main/modules/goals.py"
click node_learning "https://github.com/probablyapigeon/connectedxembra/blob/main/modules/learning.py"
click node_wordbook "https://github.com/probablyapigeon/connectedxembra/blob/main/modules/wordbook.py"
click node_memorylog "https://github.com/probablyapigeon/connectedxembra/blob/main/modules/memory.py"
click node_thought "https://github.com/probablyapigeon/connectedxembra/blob/main/modules/thought_loop.py"
click node_novelty "https://github.com/probablyapigeon/connectedxembra/blob/main/modules/novelty.py"
click node_questions "https://github.com/probablyapigeon/connectedxembra/blob/main/modules/question_generator.py"
click node_world "https://github.com/probablyapigeon/connectedxembra/blob/main/modules/world_scene.py"
click node_scene "https://github.com/probablyapigeon/connectedxembra/blob/main/modules/scene.py"
click node_grandma "https://github.com/probablyapigeon/connectedxembra/blob/main/modules/grandma.py"
click node_hug "https://github.com/probablyapigeon/connectedxembra/blob/main/modules/hug.py"
click node_name "https://github.com/probablyapigeon/connectedxembra/blob/main/modules/name.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_live,node_bridge,node_creature toneBlue
class node_brain,node_emotions,node_identity,node_attachment,node_relationship,node_goals toneAmber
class node_learning,node_wordbook,node_memorylog,node_thought toneMint
class node_novelty,node_questions,node_world,node_scene,node_grandma,node_hug,node_name toneRose
class node_operator toneIndigo
```

## Components

### Runtime and orchestration

- [Interactive runtime](https://github.com/probablyapigeon/connectedxembra/blob/main/xembra_july_live.py): `xembra_july_live.py`
- [Associative bridge](https://github.com/probablyapigeon/connectedxembra/blob/main/july_bridge.py): `july_bridge.py`
- [Creature state machine](https://github.com/probablyapigeon/connectedxembra/blob/main/xembra_creature.py): `xembra_creature.py`

### State and affect

- [Brain state](https://github.com/probablyapigeon/connectedxembra/blob/main/core/brain_state.py): `core/brain_state.py`
- [Emotion system](https://github.com/probablyapigeon/connectedxembra/blob/main/modules/emotions.py): `modules/emotions.py`
- [Identity drift](https://github.com/probablyapigeon/connectedxembra/blob/main/modules/identity.py): `modules/identity.py`
- [Attachment dynamics](https://github.com/probablyapigeon/connectedxembra/blob/main/modules/attachment.py): `modules/attachment.py`
- [Relationship tracking](https://github.com/probablyapigeon/connectedxembra/blob/main/modules/relationship.py): `modules/relationship.py`
- [Goal dynamics](https://github.com/probablyapigeon/connectedxembra/blob/main/modules/goals.py): `modules/goals.py`

### Memory and thought

- [Lexical learning](https://github.com/probablyapigeon/connectedxembra/blob/main/modules/learning.py): `modules/learning.py`
- [Associative wordbook](https://github.com/probablyapigeon/connectedxembra/blob/main/modules/wordbook.py): `modules/wordbook.py`
- [Episodic memory](https://github.com/probablyapigeon/connectedxembra/blob/main/modules/memory.py): `modules/memory.py`
- [Thought and dreams](https://github.com/probablyapigeon/connectedxembra/blob/main/modules/thought_loop.py): `modules/thought_loop.py`

### Context and interaction

- [Novelty scoring](https://github.com/probablyapigeon/connectedxembra/blob/main/modules/novelty.py): `modules/novelty.py`
- [Question generation](https://github.com/probablyapigeon/connectedxembra/blob/main/modules/question_generator.py): `modules/question_generator.py`
- [World scene](https://github.com/probablyapigeon/connectedxembra/blob/main/modules/world_scene.py): `modules/world_scene.py`
- [Scene framing](https://github.com/probablyapigeon/connectedxembra/blob/main/modules/scene.py): `modules/scene.py`
- [Recognition cues](https://github.com/probablyapigeon/connectedxembra/blob/main/modules/grandma.py): `modules/grandma.py`
- [Comfort cues](https://github.com/probablyapigeon/connectedxembra/blob/main/modules/hug.py): `modules/hug.py`
- [Name recognition](https://github.com/probablyapigeon/connectedxembra/blob/main/modules/name.py): `modules/name.py`

### Other components

- **Operator**

## Connections

- Operator → Interactive runtime: enters turns
- Interactive runtime → Associative bridge: coordinates concepts (evidence: `xembra_july_live.py`)
- Interactive runtime → Creature state machine: runs state machine
- Interactive runtime → Brain state: updates telemetry
- Interactive runtime → Emotion system: uses affect (evidence: `xembra_july_live.py`)
- Interactive runtime → Identity drift: updates identity (evidence: `xembra_july_live.py`)
- Interactive runtime → Attachment dynamics: uses bonding (evidence: `xembra_july_live.py`)
- Interactive runtime → Relationship tracking: tracks bonds (evidence: `xembra_july_live.py`)
- Interactive runtime → Goal dynamics: updates goals (evidence: `xembra_july_live.py`)
- Interactive runtime → Lexical learning: learns words (evidence: `xembra_july_live.py`)
- Interactive runtime → Episodic memory: recalls episodes (evidence: `xembra_july_live.py`)
- Interactive runtime → Thought and dreams: generates thought (evidence: `xembra_july_live.py`)
- Interactive runtime → Novelty scoring: scores novelty (evidence: `xembra_july_live.py`)
- Interactive runtime → Question generation: generates questions (evidence: `xembra_july_live.py`)
- Interactive runtime → World scene: updates context (evidence: `xembra_july_live.py`)
- Interactive runtime → Scene framing: frames scenes (evidence: `xembra_july_live.py`)
- Interactive runtime → Recognition cues: checks cues (evidence: `xembra_july_live.py`)
- Interactive runtime → Comfort cues: checks comfort (evidence: `xembra_july_live.py`)
- Interactive runtime → Name recognition: checks names (evidence: `xembra_july_live.py`)
- Associative bridge → Lexical learning: extracts concepts (evidence: `july_bridge.py`)
- Associative bridge → Associative wordbook: weaves associations
- Associative bridge → Emotion system: synthesizes affect (evidence: `july_bridge.py`)
- Associative bridge → Identity drift: updates identity (evidence: `july_bridge.py`)
- Associative bridge → Question generation: supports inquiry (evidence: `july_bridge.py`)
- Associative bridge → World scene: uses context (evidence: `july_bridge.py`)