How zhan-zip/personal-assistant works
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: message_processor.py Message processor · adapter.py OneBot adapter · proactive.py Proactive tasks · tools.py Tool registry
Components 26
Chat protocols
- OneBot adapter
protocols/onebot/adapter.py - Web adapter
protocols/web/adapter.py
Assistant core
- Bot runtime
bot.py - Event handler
core/event_handler.py - Message processor
core/message_processor.py - Command handling
core/commands.py - Progress reporting
core/progress_reporter.py - LLM router
llm/llm.py - Tool registry
llm/tools.py
Memory
- Conversation memory
core/memory_store.py - Long-term facts
core/long_memory.py - Semantic memory
core/vector_store.py
Tools and actions
- Proactive tasks
proactive/proactive.py - Profile management
profile/profile.py - QZone automation
qzone/qzone_browser.py - Search and vision
services/services.py
External integrations
- MCP server
mcp_integration/server.py - MCP client
mcp_integration/client.py
Other components
- Chat user
- LLM providers
- Peer MCP server
- SQLite store
- ChromaDB
- NapCat / OneBot
- QQ Space
- External APIs
Connections 35
- 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