# rafaelssenna/brain architecture

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

- Interactive diagram: https://gitdiagram.com/rafaelssenna/brain
- Repository: https://github.com/rafaelssenna/brain

## Overview

brAIn is an online-learning, embodied brain-like AI: it learns perceptions and language from experience rather than relying on a fixed pretrained model. The main user workflow is to show or discuss scenes, receive answers grounded in what the agent perceives, and teach it through feedback; separate workflows support adaptive lessons and learning from web text. The README documents additional cognitive capabilities across prediction, memory, planning, vision, language, and reasoning. Those capabilities are grouped by role; unsampled module wiring is not inferred.

Main entry points: [`conversa.py`](https://github.com/rafaelssenna/brain/blob/main/conversa.py) (Portuguese conversation), [`src/brain/agent.py`](https://github.com/rafaelssenna/brain/blob/main/src/brain/agent.py) (Living agent), [`src/brain/integrated.py`](https://github.com/rafaelssenna/brain/blob/main/src/brain/integrated.py) (Integrated organism), [`professor.py`](https://github.com/rafaelssenna/brain/blob/main/professor.py) (Adaptive lessons)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interaction and learning"]
  node_chat["Simple-world chat<br/>[chat.py]"]
  node_conversation["Portuguese conversation<br/>[conversa.py]"]
  node_teacher["Adaptive lessons<br/>[professor.py]"]
end

subgraph group_cognition["Embodied cognition"]
  node_agent["Living agent<br/>[agent.py]"]
  node_neuron["Spiking neurons<br/>[neuron.py]"]
  node_synapse["Plastic synapses<br/>[synapse.py]"]
  node_world["Embodied world<br/>[world.py]"]
  node_integrated["Integrated organism<br/>[integrated.py]"]
  node_prediction["Predictive coding<br/>[predictive.py]"]
  node_memory["Memory and replay<br/>[memory.py]"]
  node_vision["Visual perception<br/>[rich_world.py]"]
  node_planning["Imaginative planning<br/>[planning.py]"]
end

subgraph group_language["Language and reasoning"]
  node_language["Language capabilities<br/>[communication.py]"]
  node_dialogue["Contextual dialogue<br/>[conversation.py]"]
  node_reasoning["Reasoning<br/>[reasoning.py]"]
end

subgraph group_reading["Reading and memory"]
  node_reading["Reading brain<br/>[reading.py]"]
  node_webreader["Web access<br/>[web.py]"]
  node_longterm[("Saved brain state<br/>[agent.py]")]
end

node_user(("Learner"))
node_environment(("Scene"))
node_web(("Wikipedia PT"))

node_user -->|"teaches or asks"| node_chat
node_environment -->|"supplies scene"| node_chat
node_chat -->|"perceives and learns"| node_agent
node_agent -->|"returns naming"| node_chat
node_user -->|"asks or corrects"| node_conversation
node_conversation -->|"perceives scene"| node_vision
node_conversation -->|"handles turns"| node_dialogue
node_conversation -->|"queries learned text"| node_reading
node_teacher -->|"conducts lessons"| node_conversation
node_teacher -->|"selects objects"| node_vision
node_teacher -->|"loads and saves"| node_longterm
node_agent -.->|"uses spiking substrate"| node_neuron
node_agent -.->|"learns by plasticity"| node_synapse
node_agent -.->|"acts in environment"| node_world
node_integrated -.->|"combines prediction"| node_prediction
node_integrated -.->|"combines memory"| node_memory
node_integrated -.->|"combines planning"| node_planning
node_integrated -.->|"co-emerges language"| node_language
node_integrated -.->|"integrates perception"| node_vision
node_conversation -.->|"answers reasoning queries"| node_reasoning
node_user -->|"starts study"| node_teacher
node_web -->|"provides articles"| node_webreader
node_webreader -->|"fetches text"| node_reading
node_reading -->|"persists knowledge"| node_longterm
node_reading -.->|"provides learned associations"| node_conversation
node_agent -->|"saves and loads"| node_longterm

click node_chat "https://github.com/rafaelssenna/brain/blob/main/chat.py"
click node_conversation "https://github.com/rafaelssenna/brain/blob/main/conversa.py"
click node_teacher "https://github.com/rafaelssenna/brain/blob/main/professor.py"
click node_agent "https://github.com/rafaelssenna/brain/blob/main/src/brain/agent.py"
click node_neuron "https://github.com/rafaelssenna/brain/blob/main/src/brain/neuron.py"
click node_synapse "https://github.com/rafaelssenna/brain/blob/main/src/brain/synapse.py"
click node_world "https://github.com/rafaelssenna/brain/blob/main/src/brain/world.py"
click node_integrated "https://github.com/rafaelssenna/brain/blob/main/src/brain/integrated.py"
click node_prediction "https://github.com/rafaelssenna/brain/blob/main/src/brain/predictive.py"
click node_memory "https://github.com/rafaelssenna/brain/blob/main/src/brain/memory.py"
click node_vision "https://github.com/rafaelssenna/brain/blob/main/src/brain/rich_world.py"
click node_planning "https://github.com/rafaelssenna/brain/blob/main/src/brain/planning.py"
click node_language "https://github.com/rafaelssenna/brain/blob/main/src/brain/communication.py"
click node_dialogue "https://github.com/rafaelssenna/brain/blob/main/src/brain/conversation.py"
click node_reasoning "https://github.com/rafaelssenna/brain/blob/main/src/brain/reasoning.py"
click node_reading "https://github.com/rafaelssenna/brain/blob/main/src/brain/reading.py"
click node_webreader "https://github.com/rafaelssenna/brain/blob/main/src/brain/web.py"
click node_longterm "https://github.com/rafaelssenna/brain/blob/main/src/brain/agent.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_chat,node_conversation,node_teacher toneBlue
class node_agent,node_neuron,node_synapse,node_world,node_integrated,node_prediction,node_memory,node_vision,node_planning toneAmber
class node_language,node_dialogue,node_reasoning toneMint
class node_reading,node_webreader,node_longterm toneRose
class node_user,node_environment,node_web toneIndigo
```

## Components

### Interaction and learning

- [Simple-world chat](https://github.com/rafaelssenna/brain/blob/main/chat.py): `chat.py`
- [Portuguese conversation](https://github.com/rafaelssenna/brain/blob/main/conversa.py): `conversa.py`
- [Adaptive lessons](https://github.com/rafaelssenna/brain/blob/main/professor.py): `professor.py`

### Embodied cognition

- [Living agent](https://github.com/rafaelssenna/brain/blob/main/src/brain/agent.py): `src/brain/agent.py`
- [Spiking neurons](https://github.com/rafaelssenna/brain/blob/main/src/brain/neuron.py): `src/brain/neuron.py`
- [Plastic synapses](https://github.com/rafaelssenna/brain/blob/main/src/brain/synapse.py): `src/brain/synapse.py`
- [Embodied world](https://github.com/rafaelssenna/brain/blob/main/src/brain/world.py): `src/brain/world.py`
- [Integrated organism](https://github.com/rafaelssenna/brain/blob/main/src/brain/integrated.py): `src/brain/integrated.py`
- [Predictive coding](https://github.com/rafaelssenna/brain/blob/main/src/brain/predictive.py): `src/brain/predictive.py`
- [Memory and replay](https://github.com/rafaelssenna/brain/blob/main/src/brain/memory.py): `src/brain/memory.py`
- [Visual perception](https://github.com/rafaelssenna/brain/blob/main/src/brain/rich_world.py): `src/brain/rich_world.py`
- [Imaginative planning](https://github.com/rafaelssenna/brain/blob/main/src/brain/planning.py): `src/brain/planning.py`

### Language and reasoning

- [Language capabilities](https://github.com/rafaelssenna/brain/blob/main/src/brain/communication.py): `src/brain/communication.py`
- [Contextual dialogue](https://github.com/rafaelssenna/brain/blob/main/src/brain/conversation.py): `src/brain/conversation.py`
- [Reasoning](https://github.com/rafaelssenna/brain/blob/main/src/brain/reasoning.py): `src/brain/reasoning.py`

### Reading and memory

- [Reading brain](https://github.com/rafaelssenna/brain/blob/main/src/brain/reading.py): `src/brain/reading.py`
- [Web access](https://github.com/rafaelssenna/brain/blob/main/src/brain/web.py): `src/brain/web.py`
- [Saved brain state](https://github.com/rafaelssenna/brain/blob/main/src/brain/agent.py): `src/brain/agent.py`

### Other components

- **Learner**
- **Scene**
- **Wikipedia PT**

## Connections

- Learner → Simple-world chat: teaches or asks
- Scene → Simple-world chat: supplies scene
- Simple-world chat → Living agent: perceives and learns
- Living agent → Simple-world chat: returns naming
- Learner → Portuguese conversation: asks or corrects
- Portuguese conversation → Visual perception: perceives scene
- Portuguese conversation → Contextual dialogue: handles turns
- Portuguese conversation → Reading brain: queries learned text
- Adaptive lessons → Portuguese conversation: conducts lessons
- Adaptive lessons → Visual perception: selects objects
- Adaptive lessons → Saved brain state: loads and saves
- Living agent → Spiking neurons: uses spiking substrate
- Living agent → Plastic synapses: learns by plasticity
- Living agent → Embodied world: acts in environment
- Integrated organism → Predictive coding: combines prediction
- Integrated organism → Memory and replay: combines memory
- Integrated organism → Imaginative planning: combines planning
- Integrated organism → Language capabilities: co-emerges language
- Integrated organism → Visual perception: integrates perception
- Portuguese conversation → Reasoning: answers reasoning queries
- Learner → Adaptive lessons: starts study
- Wikipedia PT → Web access: provides articles
- Web access → Reading brain: fetches text
- Reading brain → Saved brain state: persists knowledge
- Reading brain → Portuguese conversation: provides learned associations
- Living agent → Saved brain state: saves and loads