# snowlights2022/maibot architecture

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

- Interactive diagram: https://gitdiagram.com/snowlights2022/maibot
- Repository: https://github.com/snowlights2022/maibot

## Overview

MaiBot is a conversational LLM agent designed for lifelike interaction in group chats, with persistent personal memory, extensibility through plugins, and a browser-based management dashboard. The documented user workflow is incoming conversation → agent reasoning and response → conversation platform; memory ingestion and retrieval support that interaction. The graph also preserves dashboard management and monitoring capabilities. Source excerpts are partial and do not expose the host’s full message-dispatch wiring, so uncertain connections between the host, reasoning engine, and memory runtime are omitted.

Main entry points: [`dashboard/src/router.tsx`](https://github.com/snowlights2022/maibot/blob/main/dashboard/src/router.tsx) (Dashboard app), [`src/A_memorix/core/runtime/services/ingest_service.py`](https://github.com/snowlights2022/maibot/blob/main/src/A_memorix/core/runtime/services/ingest_service.py) (Memory ingestion), [`src/maisaka/reasoning_engine.py`](https://github.com/snowlights2022/maibot/blob/main/src/maisaka/reasoning_engine.py) (Reasoning engine), [`src/A_memorix/core/utils/aggregate_query_service.py`](https://github.com/snowlights2022/maibot/blob/main/src/A_memorix/core/utils/aggregate_query_service.py) (Memory retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation Agent"]
  node_host["Bot host<br/>[bot.py]"]
  node_reasoning["Reasoning engine"]
  node_llm["LLM service<br/>[llm_service.py]"]
end

subgraph group_memory["Memory System"]
  node_memory_ingest["Memory ingestion<br/>[ingest_service.py]"]
  node_memory_retrieval["Memory retrieval"]
  node_memory_storage[("Memory storage<br/>[metadata_store.py]")]
  node_vector_storage[("Vector storage<br/>[vector_store.py]")]
  node_embedding["Embedding service"]
  node_tuning["Retrieval tuning"]
end

subgraph group_extensions["Extensions"]
  node_plugin_runtime["Plugin runtime"]
end

subgraph group_dashboard["Management Dashboard"]
  node_dashboard["Dashboard app<br/>[router.tsx]"]
  node_chat_ui["Chat workspace<br/>[index.tsx]"]
  node_memory_ui["Memory management<br/>[knowledge-base.tsx]"]
  node_plugin_ui["Plugin management"]
  node_monitor_ui["Runtime monitoring<br/>[index.tsx]"]
end

node_participant(("Chat participant"))
node_platform(("Chat platform"))
node_llm_provider(("LLM provider"))
node_dashboard_backend(("MaiBot backend"))

node_participant -->|"sends messages"| node_platform
node_platform -->|"delivers messages"| node_host
node_host -->|"triggers turns"| node_reasoning
node_reasoning -->|"requests generation"| node_llm
node_llm -->|"dispatches requests"| node_llm_provider
node_reasoning -->|"produces replies"| node_platform
node_memory_ingest -->|"writes metadata"| node_memory_storage
node_memory_ingest -->|"writes vectors"| node_vector_storage
node_memory_ingest -->|"requests embeddings"| node_embedding
node_memory_retrieval -->|"reads metadata"| node_memory_storage
node_memory_retrieval -->|"searches vectors"| node_vector_storage
node_tuning -->|"configures retrieval"| node_memory_retrieval
node_dashboard -->|"routes to"| node_chat_ui
node_dashboard -->|"routes to"| node_memory_ui
node_dashboard -->|"routes to"| node_plugin_ui
node_dashboard -->|"routes to"| node_monitor_ui
node_chat_ui -->|"uses backend APIs"| node_dashboard_backend
node_memory_ui -->|"uses memory APIs"| node_dashboard_backend
node_plugin_ui -->|"uses plugin APIs"| node_dashboard_backend
node_monitor_ui -->|"uses monitoring APIs"| node_dashboard_backend
node_dashboard_backend -.->|"manages plugins"| node_plugin_runtime

click node_host "https://github.com/snowlights2022/maibot/blob/main/bot.py"
click node_reasoning "https://github.com/snowlights2022/maibot/blob/main/src/maisaka/reasoning_engine.py"
click node_llm "https://github.com/snowlights2022/maibot/blob/main/src/services/llm_service.py"
click node_memory_ingest "https://github.com/snowlights2022/maibot/blob/main/src/A_memorix/core/runtime/services/ingest_service.py"
click node_memory_retrieval "https://github.com/snowlights2022/maibot/blob/main/src/A_memorix/core/utils/aggregate_query_service.py"
click node_memory_storage "https://github.com/snowlights2022/maibot/blob/main/src/A_memorix/core/storage/metadata_store.py"
click node_vector_storage "https://github.com/snowlights2022/maibot/blob/main/src/A_memorix/core/storage/vector_store.py"
click node_embedding "https://github.com/snowlights2022/maibot/blob/main/src/services/embedding_service.py"
click node_tuning "https://github.com/snowlights2022/maibot/blob/main/src/A_memorix/core/utils/retrieval_tuning_manager.py"
click node_plugin_runtime "https://github.com/snowlights2022/maibot/blob/main/src/plugin_runtime/dependency_pipeline.py"
click node_dashboard "https://github.com/snowlights2022/maibot/blob/main/dashboard/src/router.tsx"
click node_chat_ui "https://github.com/snowlights2022/maibot/blob/main/dashboard/src/routes/chat/index.tsx"
click node_memory_ui "https://github.com/snowlights2022/maibot/blob/main/dashboard/src/routes/resource/knowledge-base.tsx"
click node_plugin_ui "https://github.com/snowlights2022/maibot/blob/main/dashboard/src/routes/plugins/PluginMarketplacePage.tsx"
click node_monitor_ui "https://github.com/snowlights2022/maibot/blob/main/dashboard/src/routes/monitor/index.tsx"

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_host,node_reasoning,node_llm toneBlue
class node_memory_ingest,node_memory_retrieval,node_memory_storage,node_vector_storage,node_embedding,node_tuning toneAmber
class node_plugin_runtime toneMint
class node_dashboard,node_chat_ui,node_memory_ui,node_plugin_ui,node_monitor_ui toneRose
class node_participant,node_platform,node_llm_provider,node_dashboard_backend toneIndigo
```

## Components

### Conversation Agent

- [Bot host](https://github.com/snowlights2022/maibot/blob/main/bot.py): `bot.py`
- [Reasoning engine](https://github.com/snowlights2022/maibot/blob/main/src/maisaka/reasoning_engine.py): `src/maisaka/reasoning_engine.py`
- [LLM service](https://github.com/snowlights2022/maibot/blob/main/src/services/llm_service.py): `src/services/llm_service.py`

### Memory System

- [Memory ingestion](https://github.com/snowlights2022/maibot/blob/main/src/A_memorix/core/runtime/services/ingest_service.py): `src/A_memorix/core/runtime/services/ingest_service.py`
- [Memory retrieval](https://github.com/snowlights2022/maibot/blob/main/src/A_memorix/core/utils/aggregate_query_service.py): `src/A_memorix/core/utils/aggregate_query_service.py`
- [Memory storage](https://github.com/snowlights2022/maibot/blob/main/src/A_memorix/core/storage/metadata_store.py): `src/A_memorix/core/storage/metadata_store.py`
- [Vector storage](https://github.com/snowlights2022/maibot/blob/main/src/A_memorix/core/storage/vector_store.py): `src/A_memorix/core/storage/vector_store.py`
- [Embedding service](https://github.com/snowlights2022/maibot/blob/main/src/services/embedding_service.py): `src/services/embedding_service.py`
- [Retrieval tuning](https://github.com/snowlights2022/maibot/blob/main/src/A_memorix/core/utils/retrieval_tuning_manager.py): `src/A_memorix/core/utils/retrieval_tuning_manager.py`

### Extensions

- [Plugin runtime](https://github.com/snowlights2022/maibot/blob/main/src/plugin_runtime/dependency_pipeline.py): `src/plugin_runtime/dependency_pipeline.py`

### Management Dashboard

- [Dashboard app](https://github.com/snowlights2022/maibot/blob/main/dashboard/src/router.tsx): `dashboard/src/router.tsx`
- [Chat workspace](https://github.com/snowlights2022/maibot/blob/main/dashboard/src/routes/chat/index.tsx): `dashboard/src/routes/chat/index.tsx`
- [Memory management](https://github.com/snowlights2022/maibot/blob/main/dashboard/src/routes/resource/knowledge-base.tsx): `dashboard/src/routes/resource/knowledge-base.tsx`
- [Plugin management](https://github.com/snowlights2022/maibot/blob/main/dashboard/src/routes/plugins/PluginMarketplacePage.tsx): `dashboard/src/routes/plugins/PluginMarketplacePage.tsx`
- [Runtime monitoring](https://github.com/snowlights2022/maibot/blob/main/dashboard/src/routes/monitor/index.tsx): `dashboard/src/routes/monitor/index.tsx`

### Other components

- **Chat participant**
- **Chat platform**
- **LLM provider**
- **MaiBot backend**

## Connections

- Chat participant → Chat platform: sends messages
- Chat platform → Bot host: delivers messages
- Bot host → Reasoning engine: triggers turns
- Reasoning engine → LLM service: requests generation
- LLM service → LLM provider: dispatches requests
- Reasoning engine → Chat platform: produces replies
- Memory ingestion → Memory storage: writes metadata
- Memory ingestion → Vector storage: writes vectors
- Memory ingestion → Embedding service: requests embeddings
- Memory retrieval → Memory storage: reads metadata
- Memory retrieval → Vector storage: searches vectors
- Retrieval tuning → Memory retrieval: configures retrieval
- Dashboard app → Chat workspace: routes to
- Dashboard app → Memory management: routes to
- Dashboard app → Plugin management: routes to
- Dashboard app → Runtime monitoring: routes to
- Chat workspace → MaiBot backend: uses backend APIs
- Memory management → MaiBot backend: uses memory APIs
- Plugin management → MaiBot backend: uses plugin APIs
- Runtime monitoring → MaiBot backend: uses monitoring APIs
- MaiBot backend → Plugin runtime: manages plugins