Aetheel/docs/research/nanobot.md

🐈 Nanobot — Architecture & How It Works

Ultra-Lightweight Personal AI Assistant — ~4,000 lines of Python, 99% smaller than OpenClaw.

Overview

Nanobot is a minimalist personal AI assistant written in Python that focuses on delivering core agent functionality with the smallest possible codebase. It uses LiteLLM for multi-provider LLM routing, supports 9+ chat channels, and includes memory, skills, scheduled tasks, and MCP tool integration.

Attribute	Value
Language	Python 3.11+
Lines of Code	~4,000 (core agent)
Config	~/.nanobot/config.json
Package	pip install nanobot-ai
LLM Routing	LiteLLM (multi-provider)

---

Architecture Flowchart

graph TB
    subgraph Channels["📱 Chat Channels"]
        TG["Telegram"]
        DC["Discord"]
        WA["WhatsApp"]
        FS["Feishu"]
        MC["Mochat"]
        DT["DingTalk"]
        SL["Slack"]
        EM["Email"]
        QQ["QQ"]
    end

    subgraph Gateway["🌐 Gateway (nanobot gateway)"]
        CH["Channel Manager"]
        MQ["Message Queue"]
    end

    subgraph Agent["🧠 Core Agent"]
        LOOP["Agent Loop\n(loop.py)"]
        CTX["Context Builder\n(context.py)"]
        MEM["Memory System\n(memory.py)"]
        SK["Skills Loader\n(skills.py)"]
        SA["Subagent\n(subagent.py)"]
    end

    subgraph Tools["🔧 Built-in Tools"]
        SHELL["Shell Exec"]
        FILE["File R/W/Edit"]
        WEB["Web Search"]
        SPAWN["Spawn Subagent"]
        MCP["MCP Servers"]
    end

    subgraph Providers["☁️ LLM Providers (LiteLLM)"]
        OR["OpenRouter"]
        AN["Anthropic"]
        OA["OpenAI"]
        DS["DeepSeek"]
        GR["Groq"]
        GE["Gemini"]
        VL["vLLM (local)"]
    end

    Channels --> Gateway
    Gateway --> Agent
    CTX --> LOOP
    MEM --> CTX
    SK --> CTX
    LOOP --> Tools
    LOOP --> Providers
    SA --> LOOP

---

Message Flow

sequenceDiagram
    participant User
    participant Channel as Chat Channel
    participant GW as Gateway
    participant Agent as Agent Loop
    participant LLM as LLM Provider
    participant Tools as Tools

    User->>Channel: Send message
    Channel->>GW: Forward message
    GW->>Agent: Route to agent
    Agent->>Agent: Build context (memory, skills, identity)
    Agent->>LLM: Send prompt + tools
    LLM-->>Agent: Response (text or tool call)
    
    alt Tool Call
        Agent->>Tools: Execute tool
        Tools-->>Agent: Tool result
        Agent->>LLM: Send tool result
        LLM-->>Agent: Final response
    end
    
    Agent->>Agent: Update memory
    Agent-->>GW: Return response
    GW-->>Channel: Send reply
    Channel-->>User: Display response

---

Key Components

1. Agent Loop (agent/loop.py)

The core loop that manages the LLM ↔ tool execution cycle:

• Builds a prompt using context (memory, skills, identity files)
• Sends to LLM via LiteLLM
• If LLM returns a tool call → executes it → sends result back
• Continues until LLM returns a text response (no more tool calls)

2. Context Builder (agent/context.py)

Assembles the system prompt from:

• Identity files: AGENTS.md, SOUL.md, USER.md, TOOLS.md, IDENTITY.md
• Memory: Persistent MEMORY.md with recall
• Skills: Loaded from ~/.nanobot/workspace/skills/
• Conversation history: Session-based context

3. Memory System (agent/memory.py)

• Persistent memory stored in MEMORY.md in the workspace
• Agent can read and write memories
• Survives across sessions

4. Provider Registry (providers/registry.py)

• Single-source-of-truth for all LLM providers
• Adding a new provider = 2 steps (add ProviderSpec + config field)
• Auto-prefixes model names for LiteLLM routing
• Supports 12+ providers including local vLLM

5. Channel System (channels/)

• 9 chat platforms supported (Telegram, Discord, WhatsApp, Feishu, Mochat, DingTalk, Slack, Email, QQ)
• Each channel handles auth, message parsing, and response delivery
• Allowlist-based security (allowFrom)
• Started via nanobot gateway

6. Skills (skills/)

• Bundled skills: GitHub, weather, tmux, etc.
• Custom skills loaded from workspace
• Skills are injected into the agent's context

7. Scheduled Tasks (Cron)

• Add jobs via nanobot cron add
• Supports cron expressions and interval-based scheduling
• Jobs stored persistently

8. MCP Integration

• Supports Model Context Protocol servers
• Stdio and HTTP transport modes
• Compatible with Claude Desktop / Cursor MCP configs
• Tools auto-discovered and registered at startup

---

Project Structure

nanobot/
├── agent/              # 🧠 Core agent logic
│   ├── loop.py         #    Agent loop (LLM ↔ tool execution)
│   ├── context.py      #    Prompt builder
│   ├── memory.py       #    Persistent memory
│   ├── skills.py       #    Skills loader
│   ├── subagent.py     #    Background task execution
│   └── tools/          #    Built-in tools (incl. spawn)
├── skills/             # 🎯 Bundled skills (github, weather, tmux...)
├── channels/           # 📱 Chat channel integrations
├── providers/          # ☁️ LLM provider registry
├── config/             # ⚙️ Configuration schema
├── cron/               # ⏰ Scheduled tasks
├── heartbeat/          # 💓 Heartbeat system
├── session/            # 📝 Session management
├── bus/                # 📨 Internal event bus
├── cli/                # 🖥️ CLI commands
└── utils/              # 🔧 Utilities

---

CLI Commands

Command	Description
nanobot onboard	Initialize config & workspace
nanobot agent -m "..."	Chat with the agent
nanobot agent	Interactive chat mode
nanobot gateway	Start all channels
nanobot status	Show status
nanobot cron add/list/remove	Manage scheduled tasks
nanobot channels login	Link WhatsApp device

---

Key Design Decisions

1. LiteLLM for provider abstraction — One interface for all LLM providers
2. JSON config over env vars — Single config.json file for all settings
3. Skills-based extensibility — Modular skill system for adding capabilities
4. Provider Registry pattern — Adding providers is 2-step, zero if-elif chains
5. Agent social network — Can join MoltBook, ClawdChat communities