# cellium-project/cellium-agent architecture

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

- Interactive diagram: https://gitdiagram.com/cellium-project/cellium-agent
- Repository: https://github.com/cellium-project/cellium-agent

## Overview

Cellium Agent is a self-learning assistant exposed through a Web UI and messaging channels. Its principal workflow accepts a user task, runs an agent session that consults memory and tools and streams model output, then uses control-loop feedback to adapt later decisions. Major documented branches include heuristic decisions, scheduled and component-triggered work, multi-platform messaging, and security controls. The graph follows README-described behavior and SOURCE INDEX references; unsampled implementations are represented only where the tree or README supports them.

Main entry points: [`app/agent/loop/agent_loop.py`](https://github.com/cellium-project/cellium-agent/blob/main/app/agent/loop/agent_loop.py) (Agent Loop), [`app/agent/control/control_loop.py`](https://github.com/cellium-project/cellium-agent/blob/main/app/agent/control/control_loop.py) (Control Loop), [`app/server/task_manager.py`](https://github.com/cellium-project/cellium-agent/blob/main/app/server/task_manager.py) (Task Manager), [`ui/src/App.tsx`](https://github.com/cellium-project/cellium-agent/blob/main/ui/src/App.tsx) (Web UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_web_ui["Web UI<br/>[App.tsx]"]
  node_chat_api["Chat Routes<br/>[chat.py]"]
  node_channels["Channel Manager<br/>[channel_manager.py]"]
end

subgraph group_execution["Agent Execution"]
  node_agent_loop["Agent Loop<br/>[agent_loop.py]"]
  node_task_manager["Task Manager<br/>[task_manager.py]"]
  node_llm_engine["LLM Engine<br/>[engine.py]"]
end

subgraph group_decision["Decision and Learning"]
  node_control_loop["Control Loop<br/>[control_loop.py]"]
  node_heuristics["Heuristic Engine<br/>[engine.py]"]
  node_learning["Policy Learning"]
  node_feedback["Feedback Evaluator"]
end

subgraph group_capabilities["Agent Capabilities"]
  node_tools["Agent Tools"]
  node_memory[("Three-Layer Memory<br/>[three_layer.py]")]
  node_memory_search[("Memory Retrieval<br/>[repository.py]")]
end

subgraph group_platform["Platform Services"]
  node_event_stream["Event Streaming<br/>[message_broker.py]"]
  node_websocket["WebSocket Events"]
  node_scheduler["Scheduled Tasks<br/>[manager.py]"]
  node_components["Extensible Components"]
  node_security["Security Policies<br/>[policy.py]"]
end

node_user(("User"))
node_model_service["Model Provider"]

node_user -->|"submits task"| node_web_ui
node_user -->|"messages through"| node_channels
node_web_ui -.->|"sends chat"| node_chat_api
node_chat_api -.->|"starts task"| node_task_manager
node_channels -->|"routes messages"| node_task_manager
node_task_manager -->|"runs session"| node_agent_loop
node_agent_loop -->|"requests completion"| node_llm_engine
node_llm_engine -->|"streams model output"| node_model_service
node_agent_loop -->|"executes actions"| node_tools
node_agent_loop -->|"uses session memory"| node_memory
node_memory -.->|"retrieves memories"| node_memory_search
node_agent_loop -->|"enters decision cycle"| node_control_loop
node_control_loop -->|"evaluates rules"| node_heuristics
node_control_loop -->|"selects policy"| node_learning
node_control_loop -->|"evaluates feedback"| node_feedback
node_feedback -->|"updates policy"| node_learning
node_task_manager -->|"publishes events"| node_event_stream
node_event_stream -.->|"forwards events"| node_websocket
node_scheduler -.->|"triggers execution"| node_agent_loop
node_components -.->|"triggers background work"| node_agent_loop
node_agent_loop -.->|"enforces controls"| node_security

click node_web_ui "https://github.com/cellium-project/cellium-agent/blob/main/ui/src/App.tsx"
click node_chat_api "https://github.com/cellium-project/cellium-agent/blob/main/app/server/routes/chat.py"
click node_channels "https://github.com/cellium-project/cellium-agent/blob/main/app/channels/channel_manager.py"
click node_agent_loop "https://github.com/cellium-project/cellium-agent/blob/main/app/agent/loop/agent_loop.py"
click node_task_manager "https://github.com/cellium-project/cellium-agent/blob/main/app/server/task_manager.py"
click node_llm_engine "https://github.com/cellium-project/cellium-agent/blob/main/app/agent/llm/engine.py"
click node_tools "https://github.com/cellium-project/cellium-agent/tree/main/app/agent/tools"
click node_memory "https://github.com/cellium-project/cellium-agent/blob/main/app/agent/memory/three_layer.py"
click node_memory_search "https://github.com/cellium-project/cellium-agent/blob/main/app/agent/memory/repository.py"
click node_control_loop "https://github.com/cellium-project/cellium-agent/blob/main/app/agent/control/control_loop.py"
click node_heuristics "https://github.com/cellium-project/cellium-agent/blob/main/app/agent/heuristics/engine.py"
click node_learning "https://github.com/cellium-project/cellium-agent/tree/main/app/agent/learning"
click node_feedback "https://github.com/cellium-project/cellium-agent/blob/main/app/agent/control/feedback_evaluator.py"
click node_event_stream "https://github.com/cellium-project/cellium-agent/blob/main/app/messaging/message_broker.py"
click node_websocket "https://github.com/cellium-project/cellium-agent/blob/main/app/server/routes/ws_event_manager.py"
click node_scheduler "https://github.com/cellium-project/cellium-agent/blob/main/app/core/scheduler/manager.py"
click node_components "https://github.com/cellium-project/cellium-agent/blob/main/components/component_builder.py"
click node_security "https://github.com/cellium-project/cellium-agent/blob/main/app/core/security/policy.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_web_ui,node_chat_api,node_channels,node_user toneBlue
class node_agent_loop,node_task_manager,node_llm_engine toneAmber
class node_control_loop,node_heuristics,node_learning,node_feedback toneMint
class node_tools,node_memory,node_memory_search toneRose
class node_event_stream,node_websocket,node_scheduler,node_components,node_security,node_model_service toneIndigo
```

## Components

### User Interfaces

- [Web UI](https://github.com/cellium-project/cellium-agent/blob/main/ui/src/App.tsx): `ui/src/App.tsx`
- [Chat Routes](https://github.com/cellium-project/cellium-agent/blob/main/app/server/routes/chat.py): `app/server/routes/chat.py`
- [Channel Manager](https://github.com/cellium-project/cellium-agent/blob/main/app/channels/channel_manager.py): `app/channels/channel_manager.py`

### Agent Execution

- [Agent Loop](https://github.com/cellium-project/cellium-agent/blob/main/app/agent/loop/agent_loop.py): `app/agent/loop/agent_loop.py`
- [Task Manager](https://github.com/cellium-project/cellium-agent/blob/main/app/server/task_manager.py): `app/server/task_manager.py`
- [LLM Engine](https://github.com/cellium-project/cellium-agent/blob/main/app/agent/llm/engine.py): `app/agent/llm/engine.py`

### Decision and Learning

- [Control Loop](https://github.com/cellium-project/cellium-agent/blob/main/app/agent/control/control_loop.py): `app/agent/control/control_loop.py`
- [Heuristic Engine](https://github.com/cellium-project/cellium-agent/blob/main/app/agent/heuristics/engine.py): `app/agent/heuristics/engine.py`
- [Policy Learning](https://github.com/cellium-project/cellium-agent/tree/main/app/agent/learning): `app/agent/learning`
- [Feedback Evaluator](https://github.com/cellium-project/cellium-agent/blob/main/app/agent/control/feedback_evaluator.py): `app/agent/control/feedback_evaluator.py`

### Agent Capabilities

- [Agent Tools](https://github.com/cellium-project/cellium-agent/tree/main/app/agent/tools): `app/agent/tools`
- [Three-Layer Memory](https://github.com/cellium-project/cellium-agent/blob/main/app/agent/memory/three_layer.py): `app/agent/memory/three_layer.py`
- [Memory Retrieval](https://github.com/cellium-project/cellium-agent/blob/main/app/agent/memory/repository.py): `app/agent/memory/repository.py`

### Platform Services

- [Event Streaming](https://github.com/cellium-project/cellium-agent/blob/main/app/messaging/message_broker.py): `app/messaging/message_broker.py`
- [WebSocket Events](https://github.com/cellium-project/cellium-agent/blob/main/app/server/routes/ws_event_manager.py): `app/server/routes/ws_event_manager.py`
- [Scheduled Tasks](https://github.com/cellium-project/cellium-agent/blob/main/app/core/scheduler/manager.py): `app/core/scheduler/manager.py`
- [Extensible Components](https://github.com/cellium-project/cellium-agent/blob/main/components/component_builder.py): `components/component_builder.py`
- [Security Policies](https://github.com/cellium-project/cellium-agent/blob/main/app/core/security/policy.py): `app/core/security/policy.py`

### Other components

- **User**
- **Model Provider**

## Connections

- User → Web UI: submits task
- User → Channel Manager: messages through
- Web UI → Chat Routes: sends chat
- Chat Routes → Task Manager: starts task
- Channel Manager → Task Manager: routes messages (evidence: `app/channels/channel_manager.py`)
- Task Manager → Agent Loop: runs session (evidence: `app/server/task_manager.py`)
- Agent Loop → LLM Engine: requests completion
- LLM Engine → Model Provider: streams model output (evidence: `app/agent/llm/engine.py`)
- Agent Loop → Agent Tools: executes actions
- Agent Loop → Three-Layer Memory: uses session memory
- Three-Layer Memory → Memory Retrieval: retrieves memories
- Agent Loop → Control Loop: enters decision cycle
- Control Loop → Heuristic Engine: evaluates rules (evidence: `app/agent/heuristics/engine.py`)
- Control Loop → Policy Learning: selects policy
- Control Loop → Feedback Evaluator: evaluates feedback
- Feedback Evaluator → Policy Learning: updates policy
- Task Manager → Event Streaming: publishes events (evidence: `app/server/task_manager.py`)
- Event Streaming → WebSocket Events: forwards events (evidence: `app/messaging/message_broker.py`)
- Scheduled Tasks → Agent Loop: triggers execution
- Extensible Components → Agent Loop: triggers background work
- Agent Loop → Security Policies: enforces controls
