# zhan-zip/personal-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/zhan-zip/personal-assistant
- Repository: https://github.com/zhan-zip/personal-assistant

## Overview

Personal Assistant is an asynchronous, locally hosted AI agent whose protocol adapters feed a shared assistant core. A user message is normalized and routed through event handling into the conversation processor, which draws on conversation and semantic memory and uses an LLM tool-calling loop to produce a reply. The product also supports proactive actions, profile and QZone automation, and MCP in both server and client roles. README documents several capabilities whose internal wiring is not shown in the sampled source, so those links are kept at subsystem level.

Main entry points: [`core/message_processor.py`](https://github.com/zhan-zip/personal-assistant/blob/main/core/message_processor.py) (Message processor), [`protocols/onebot/adapter.py`](https://github.com/zhan-zip/personal-assistant/blob/main/protocols/onebot/adapter.py) (OneBot adapter), [`proactive/proactive.py`](https://github.com/zhan-zip/personal-assistant/blob/main/proactive/proactive.py) (Proactive tasks), [`llm/tools.py`](https://github.com/zhan-zip/personal-assistant/blob/main/llm/tools.py) (Tool registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocols["Chat protocols"]
  node_onebot["OneBot adapter<br/>[adapter.py]"]
  node_web["Web adapter<br/>[adapter.py]"]
end

subgraph group_assistant["Assistant core"]
  node_bot["Bot runtime<br/>[bot.py]"]
  node_events["Event handler<br/>[event_handler.py]"]
  node_processor["Message processor"]
  node_commands["Command handling<br/>[commands.py]"]
  node_progress["Progress reporting"]
  node_llm["LLM router<br/>[llm.py]"]
  node_tool_registry["Tool registry<br/>[tools.py]"]
end

subgraph group_memory["Memory"]
  node_history[("Conversation memory<br/>[memory_store.py]")]
  node_long_memory["Long-term facts<br/>[long_memory.py]"]
  node_vectors[("Semantic memory<br/>[vector_store.py]")]
end

subgraph group_capabilities["Tools and actions"]
  node_proactive["Proactive tasks<br/>[proactive.py]"]
  node_profile["Profile management<br/>[profile.py]"]
  node_qzone["QZone automation<br/>[qzone_browser.py]"]
  node_services["Search and vision<br/>[services.py]"]
end

subgraph group_integrations["External integrations"]
  node_mcp_server["MCP server<br/>[server.py]"]
  node_mcp_client["MCP client<br/>[client.py]"]
end

node_user(("Chat user"))
node_model_providers{{"LLM providers"}}
node_mcp_peer{{"Peer MCP server"}}
node_sqlite[("SQLite store")]
node_chroma[("ChromaDB")]
node_qq_bridge{{"NapCat / OneBot"}}
node_browser{{"QQ Space"}}
node_web_services{{"External APIs"}}

node_user -->|"sends message"| node_onebot
node_user -->|"sends message"| node_web
node_onebot -->|"connects via"| node_qq_bridge
node_onebot -->|"dispatches events"| node_events
node_onebot -->|"delivers message"| node_processor
node_web -->|"delivers message"| node_processor
node_bot -->|"starts adapter"| node_onebot
node_bot -->|"starts adapter"| node_web
node_events -->|"routes messages"| node_processor
node_processor -->|"handles commands"| node_commands
node_processor -->|"reads and writes"| node_history
node_processor -->|"uses facts"| node_long_memory
node_processor -->|"uses semantic memory"| node_vectors
node_processor -->|"requests completion"| node_llm
node_llm -->|"routes and fails over"| node_model_providers
node_processor -->|"dispatches tools"| node_tool_registry
node_tool_registry -->|"calls services"| node_services
node_tool_registry -->|"calls profile actions"| node_profile
node_tool_registry -->|"calls QZone actions"| node_qzone
node_qzone -->|"automates browser"| node_browser
node_services -->|"requests APIs"| node_web_services
node_processor -->|"reports progress"| node_progress
node_processor -->|"sends replies"| node_onebot
node_processor -->|"sends replies"| node_web
node_proactive -->|"requests decisions"| node_llm
node_proactive -->|"changes profile"| node_profile
node_proactive -->|"publishes posts"| node_qzone
node_proactive -->|"reads and writes"| node_history
node_mcp_server -->|"exposes bot capabilities"| node_bot
node_mcp_server -->|"reads todos"| node_history
node_mcp_peer -->|"calls tools"| node_mcp_server
node_bot -->|"connects client"| node_mcp_client
node_mcp_client -->|"discovers and calls tools"| node_mcp_peer
node_history -->|"persists data"| node_sqlite
node_vectors -->|"stores embeddings"| node_chroma

click node_bot "https://github.com/zhan-zip/personal-assistant/blob/main/bot.py"
click node_onebot "https://github.com/zhan-zip/personal-assistant/blob/main/protocols/onebot/adapter.py"
click node_web "https://github.com/zhan-zip/personal-assistant/blob/main/protocols/web/adapter.py"
click node_events "https://github.com/zhan-zip/personal-assistant/blob/main/core/event_handler.py"
click node_processor "https://github.com/zhan-zip/personal-assistant/blob/main/core/message_processor.py"
click node_commands "https://github.com/zhan-zip/personal-assistant/blob/main/core/commands.py"
click node_progress "https://github.com/zhan-zip/personal-assistant/blob/main/core/progress_reporter.py"
click node_llm "https://github.com/zhan-zip/personal-assistant/blob/main/llm/llm.py"
click node_tool_registry "https://github.com/zhan-zip/personal-assistant/blob/main/llm/tools.py"
click node_history "https://github.com/zhan-zip/personal-assistant/blob/main/core/memory_store.py"
click node_long_memory "https://github.com/zhan-zip/personal-assistant/blob/main/core/long_memory.py"
click node_vectors "https://github.com/zhan-zip/personal-assistant/blob/main/core/vector_store.py"
click node_proactive "https://github.com/zhan-zip/personal-assistant/blob/main/proactive/proactive.py"
click node_profile "https://github.com/zhan-zip/personal-assistant/blob/main/profile/profile.py"
click node_qzone "https://github.com/zhan-zip/personal-assistant/blob/main/qzone/qzone_browser.py"
click node_services "https://github.com/zhan-zip/personal-assistant/blob/main/services/services.py"
click node_mcp_server "https://github.com/zhan-zip/personal-assistant/blob/main/mcp_integration/server.py"
click node_mcp_client "https://github.com/zhan-zip/personal-assistant/blob/main/mcp_integration/client.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_onebot,node_web,node_user toneBlue
class node_bot,node_events,node_processor,node_commands,node_progress,node_llm,node_tool_registry,node_sqlite,node_chroma toneAmber
class node_history,node_long_memory,node_vectors,node_mcp_peer,node_web_services toneMint
class node_proactive,node_profile,node_qzone,node_services toneRose
class node_mcp_server,node_mcp_client,node_model_providers,node_qq_bridge,node_browser toneIndigo
```

## Components

### Chat protocols

- [OneBot adapter](https://github.com/zhan-zip/personal-assistant/blob/main/protocols/onebot/adapter.py): `protocols/onebot/adapter.py`
- [Web adapter](https://github.com/zhan-zip/personal-assistant/blob/main/protocols/web/adapter.py): `protocols/web/adapter.py`

### Assistant core

- [Bot runtime](https://github.com/zhan-zip/personal-assistant/blob/main/bot.py): `bot.py`
- [Event handler](https://github.com/zhan-zip/personal-assistant/blob/main/core/event_handler.py): `core/event_handler.py`
- [Message processor](https://github.com/zhan-zip/personal-assistant/blob/main/core/message_processor.py): `core/message_processor.py`
- [Command handling](https://github.com/zhan-zip/personal-assistant/blob/main/core/commands.py): `core/commands.py`
- [Progress reporting](https://github.com/zhan-zip/personal-assistant/blob/main/core/progress_reporter.py): `core/progress_reporter.py`
- [LLM router](https://github.com/zhan-zip/personal-assistant/blob/main/llm/llm.py): `llm/llm.py`
- [Tool registry](https://github.com/zhan-zip/personal-assistant/blob/main/llm/tools.py): `llm/tools.py`

### Memory

- [Conversation memory](https://github.com/zhan-zip/personal-assistant/blob/main/core/memory_store.py): `core/memory_store.py`
- [Long-term facts](https://github.com/zhan-zip/personal-assistant/blob/main/core/long_memory.py): `core/long_memory.py`
- [Semantic memory](https://github.com/zhan-zip/personal-assistant/blob/main/core/vector_store.py): `core/vector_store.py`

### Tools and actions

- [Proactive tasks](https://github.com/zhan-zip/personal-assistant/blob/main/proactive/proactive.py): `proactive/proactive.py`
- [Profile management](https://github.com/zhan-zip/personal-assistant/blob/main/profile/profile.py): `profile/profile.py`
- [QZone automation](https://github.com/zhan-zip/personal-assistant/blob/main/qzone/qzone_browser.py): `qzone/qzone_browser.py`
- [Search and vision](https://github.com/zhan-zip/personal-assistant/blob/main/services/services.py): `services/services.py`

### External integrations

- [MCP server](https://github.com/zhan-zip/personal-assistant/blob/main/mcp_integration/server.py): `mcp_integration/server.py`
- [MCP client](https://github.com/zhan-zip/personal-assistant/blob/main/mcp_integration/client.py): `mcp_integration/client.py`

### Other components

- **Chat user**
- **LLM providers**
- **Peer MCP server**
- **SQLite store**
- **ChromaDB**
- **NapCat / OneBot**
- **QQ Space**
- **External APIs**

## Connections

- Chat user → OneBot adapter: sends message
- Chat user → Web adapter: sends message
- OneBot adapter → NapCat / OneBot: connects via
- OneBot adapter → Event handler: dispatches events
- OneBot adapter → Message processor: delivers message
- Web adapter → Message processor: delivers message
- Bot runtime → OneBot adapter: starts adapter
- Bot runtime → Web adapter: starts adapter
- Event handler → Message processor: routes messages
- Message processor → Command handling: handles commands
- Message processor → Conversation memory: reads and writes
- Message processor → Long-term facts: uses facts
- Message processor → Semantic memory: uses semantic memory
- Message processor → LLM router: requests completion
- LLM router → LLM providers: routes and fails over
- Message processor → Tool registry: dispatches tools
- Tool registry → Search and vision: calls services
- Tool registry → Profile management: calls profile actions
- Tool registry → QZone automation: calls QZone actions
- QZone automation → QQ Space: automates browser
- Search and vision → External APIs: requests APIs
- Message processor → Progress reporting: reports progress
- Message processor → OneBot adapter: sends replies
- Message processor → Web adapter: sends replies
- Proactive tasks → LLM router: requests decisions
- Proactive tasks → Profile management: changes profile
- Proactive tasks → QZone automation: publishes posts
- Proactive tasks → Conversation memory: reads and writes
- MCP server → Bot runtime: exposes bot capabilities
- MCP server → Conversation memory: reads todos
- Peer MCP server → MCP server: calls tools
- Bot runtime → MCP client: connects client
- MCP client → Peer MCP server: discovers and calls tools
- Conversation memory → SQLite store: persists data
- Semantic memory → ChromaDB: stores embeddings