# kesepain-ke/kemo-agent architecture

> Architecture diagram of the GitHub repository kesepain-ke/kemo-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/kesepain-ke/kemo-agent
- Repository: https://github.com/kesepain-ke/kemo-agent

## Overview

kemo-agent is a local-first, multi-user agent runtime and personal workspace. The main interaction runs from a user in the web UI through HTTP routes and services into the conversation runtime, which assembles context, calls a configured model provider, and executes available tools; results stream back to the UI. History, tiered memory, task plans, scheduled work, and external message entry points extend that loop. The README documents additional knowledge, sensing, extension, file, and subagent capabilities. Some of those modules were not sampled, so their links are documented or left unasserted rather than inferred from names.

Main entry points: [`run/conversation/runtime.py`](https://github.com/kesepain-ke/kemo-agent/blob/main/run/conversation/runtime.py) (Conversation runtime), [`web/service.py`](https://github.com/kesepain-ke/kemo-agent/blob/main/web/service.py) (Web services), [`web/app.py`](https://github.com/kesepain-ke/kemo-agent/blob/main/web/app.py) (HTTP routes), [`cron/service.py`](https://github.com/kesepain-ke/kemo-agent/blob/main/cron/service.py) (Scheduled entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_webui["Web workspace<br/>[AppShell.tsx]"]
  node_webapi["HTTP routes<br/>[app.py]"]
  node_webservice["Web services<br/>[service.py]"]
  node_message["Message entry<br/>[router.py]"]
  node_cron["Scheduled entry<br/>[service.py]"]
  node_taskweb["Task workspace<br/>[tasks.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_engine["Conversation runtime<br/>[runtime.py]"]
  node_context["Context assembly<br/>[service.py]"]
  node_provider["Provider factory<br/>[factory.py]"]
  node_tools["Tool execution<br/>[__init__.py]"]
  node_agents["Agent queue<br/>[queue.py]"]
end

subgraph group_continuity["Memory and work"]
  node_history[("Conversation history<br/>[session_api.py]")]
  node_memory[("Tidal memory<br/>[pipeline.py]")]
  node_tasks[("Task plans<br/>[service.py]")]
  node_schedule["Cron scheduling<br/>[schedule.py]"]
end

subgraph group_extensions["External capabilities"]
  node_knowledge["Knowledge graph<br/>[client.py]"]
  node_expansion["Expansion modules<br/>[app.py]"]
  node_sense["Environment sensing<br/>[register.py]"]
  node_files[("User files<br/>[files.py]")]
end

node_user(("User"))
node_model{{"Model service"}}

node_user -->|"uses"| node_webui
node_webui -->|"sends requests"| node_webapi
node_webapi -->|"routes requests"| node_webservice
node_webservice -->|"streams requests"| node_engine
node_engine -->|"assembles context"| node_context
node_engine -.->|"uses history"| node_history
node_engine -.->|"requests completion"| node_provider
node_provider -->|"calls provider"| node_model
node_engine -.->|"executes tools"| node_tools
node_engine -.->|"updates memory"| node_memory
node_webservice -->|"manages sessions"| node_history
node_webservice -->|"delegates plans"| node_tasks
node_taskweb -->|"computes run times"| node_schedule
node_cron -->|"uses schedule"| node_schedule
node_message -->|"runs conversations"| node_engine
node_cron -.->|"runs scheduled work"| node_engine
node_agents -.->|"uses provider"| node_provider
node_webapi -->|"routes file access"| node_files
node_user -->|"messages agent"| node_message
node_user -->|"schedules work"| node_cron
node_engine -.->|"uses knowledge"| node_knowledge
node_engine -.->|"loads extensions"| node_expansion
node_engine -.->|"uses sensing"| node_sense
node_user -->|"shares files"| node_files

click node_webui "https://github.com/kesepain-ke/kemo-agent/blob/main/web/frontend/src/components/AppShell.tsx"
click node_webapi "https://github.com/kesepain-ke/kemo-agent/blob/main/web/app.py"
click node_webservice "https://github.com/kesepain-ke/kemo-agent/blob/main/web/service.py"
click node_message "https://github.com/kesepain-ke/kemo-agent/blob/main/message/router.py"
click node_cron "https://github.com/kesepain-ke/kemo-agent/blob/main/cron/service.py"
click node_engine "https://github.com/kesepain-ke/kemo-agent/blob/main/run/conversation/runtime.py"
click node_context "https://github.com/kesepain-ke/kemo-agent/blob/main/run/context/service.py"
click node_provider "https://github.com/kesepain-ke/kemo-agent/blob/main/provider/factory.py"
click node_tools "https://github.com/kesepain-ke/kemo-agent/blob/main/run/tools/__init__.py"
click node_agents "https://github.com/kesepain-ke/kemo-agent/blob/main/run/agents/queue.py"
click node_history "https://github.com/kesepain-ke/kemo-agent/blob/main/run/history/session_api.py"
click node_memory "https://github.com/kesepain-ke/kemo-agent/blob/main/run/memory/pipeline.py"
click node_tasks "https://github.com/kesepain-ke/kemo-agent/blob/main/run/tasks/service.py"
click node_taskweb "https://github.com/kesepain-ke/kemo-agent/blob/main/web/services/tasks.py"
click node_schedule "https://github.com/kesepain-ke/kemo-agent/blob/main/cron/schedule.py"
click node_knowledge "https://github.com/kesepain-ke/kemo-agent/blob/main/global_expand/kemo_graph/client.py"
click node_expansion "https://github.com/kesepain-ke/kemo-agent/blob/main/global_expand/kemo_app/app.py"
click node_sense "https://github.com/kesepain-ke/kemo-agent/blob/main/global_sense/register.py"
click node_files "https://github.com/kesepain-ke/kemo-agent/blob/main/web/services/files.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_webui,node_webapi,node_webservice,node_message,node_cron,node_taskweb,node_user toneBlue
class node_engine,node_context,node_provider,node_tools,node_agents toneAmber
class node_history,node_memory,node_tasks,node_schedule toneMint
class node_knowledge,node_expansion,node_sense,node_files toneRose
class node_model toneIndigo
```

## Components

### User interaction

- [Web workspace](https://github.com/kesepain-ke/kemo-agent/blob/main/web/frontend/src/components/AppShell.tsx): `web/frontend/src/components/AppShell.tsx`
- [HTTP routes](https://github.com/kesepain-ke/kemo-agent/blob/main/web/app.py): `web/app.py`
- [Web services](https://github.com/kesepain-ke/kemo-agent/blob/main/web/service.py): `web/service.py`
- [Message entry](https://github.com/kesepain-ke/kemo-agent/blob/main/message/router.py): `message/router.py`
- [Scheduled entry](https://github.com/kesepain-ke/kemo-agent/blob/main/cron/service.py): `cron/service.py`
- [Task workspace](https://github.com/kesepain-ke/kemo-agent/blob/main/web/services/tasks.py): `web/services/tasks.py`

### Agent runtime

- [Conversation runtime](https://github.com/kesepain-ke/kemo-agent/blob/main/run/conversation/runtime.py): `run/conversation/runtime.py`
- [Context assembly](https://github.com/kesepain-ke/kemo-agent/blob/main/run/context/service.py): `run/context/service.py`
- [Provider factory](https://github.com/kesepain-ke/kemo-agent/blob/main/provider/factory.py): `provider/factory.py`
- [Tool execution](https://github.com/kesepain-ke/kemo-agent/blob/main/run/tools/__init__.py): `run/tools/__init__.py`
- [Agent queue](https://github.com/kesepain-ke/kemo-agent/blob/main/run/agents/queue.py): `run/agents/queue.py`

### Memory and work

- [Conversation history](https://github.com/kesepain-ke/kemo-agent/blob/main/run/history/session_api.py): `run/history/session_api.py`
- [Tidal memory](https://github.com/kesepain-ke/kemo-agent/blob/main/run/memory/pipeline.py): `run/memory/pipeline.py`
- [Task plans](https://github.com/kesepain-ke/kemo-agent/blob/main/run/tasks/service.py): `run/tasks/service.py`
- [Cron scheduling](https://github.com/kesepain-ke/kemo-agent/blob/main/cron/schedule.py): `cron/schedule.py`

### External capabilities

- [Knowledge graph](https://github.com/kesepain-ke/kemo-agent/blob/main/global_expand/kemo_graph/client.py): `global_expand/kemo_graph/client.py`
- [Expansion modules](https://github.com/kesepain-ke/kemo-agent/blob/main/global_expand/kemo_app/app.py): `global_expand/kemo_app/app.py`
- [Environment sensing](https://github.com/kesepain-ke/kemo-agent/blob/main/global_sense/register.py): `global_sense/register.py`
- [User files](https://github.com/kesepain-ke/kemo-agent/blob/main/web/services/files.py): `web/services/files.py`

### Other components

- **User**
- **Model service**

## Connections

- User → Web workspace: uses
- Web workspace → HTTP routes: sends requests
- HTTP routes → Web services: routes requests (evidence: `web/app.py`)
- Web services → Conversation runtime: streams requests (evidence: `web/service.py`)
- Conversation runtime → Context assembly: assembles context (evidence: `run/context/service.py`)
- Conversation runtime → Conversation history: uses history
- Conversation runtime → Provider factory: requests completion
- Provider factory → Model service: calls provider (evidence: `provider/factory.py`)
- Conversation runtime → Tool execution: executes tools
- Conversation runtime → Tidal memory: updates memory
- Web services → Conversation history: manages sessions (evidence: `web/service.py`)
- Web services → Task plans: delegates plans
- Task workspace → Cron scheduling: computes run times (evidence: `web/services/tasks.py`)
- Scheduled entry → Cron scheduling: uses schedule (evidence: `cron/service.py`)
- Message entry → Conversation runtime: runs conversations (evidence: `message/router.py`)
- Scheduled entry → Conversation runtime: runs scheduled work
- Agent queue → Provider factory: uses provider
- HTTP routes → User files: routes file access (evidence: `web/app.py`)
- User → Message entry: messages agent
- User → Scheduled entry: schedules work
- Conversation runtime → Knowledge graph: uses knowledge
- Conversation runtime → Expansion modules: loads extensions
- Conversation runtime → Environment sensing: uses sensing
- User → User files: shares files