nanobot

Overview

nanobot is an open-source, ultra-lightweight personal AI agent developed by HKUDS. Currently at v0.2.2 with over 45,000 GitHub stars, it's a self-hosted AI agent runtime designed for personal use with an emphasis on keeping the "agent core small and readable." Unlike heavyweight enterprise agent platforms, nanobot focuses on practical, long-running work automation while maintaining a minimal, hackable architecture.

The project provides extensive access methods including WebUI, terminal CLI, and integrations with Telegram, Discord, Slack, WeChat, Feishu, Teams, Email, and Mattermost. This makes it accessible from virtually any platform you use daily. nanobot also features a unique "Dream" memory system for session history and long-term knowledge persistence.

Built for the self-hosted community, nanobot emphasizes privacy and control - your agent runs on your infrastructure, with your data, using your preferred models. The OpenAI-compatible API makes it easy to integrate with existing tools and workflows.

Features

• Ultra-Lightweight Core: Small, readable codebase designed for personalization
• Multi-Platform Access: WebUI, terminal CLI, and 8+ chat platform integrations
• Dream Memory System: Session history and long-term memory persistence
• Tool Support: Files, shell, web search, web fetch, MCP servers, cron, image generation
• Subagent Architecture: Spawn specialized subagents for complex tasks
• Long-Horizon Goals: Persistent workflows that span multiple sessions
• Model Flexibility: OpenAI-compatible APIs, local LLMs, with fallback configurations
• Python SDK: Programmatic access for custom integrations
• OpenAI-Compatible API: Drop-in replacement for existing OpenAI workflows
• Scheduled Tasks: Cron-based automation for recurring jobs

Installation

Quick Install

# One-command setup
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh

Via uv (Recommended)

uv tool install nanobot-ai

Via pip

python -m pip install nanobot-ai

From Source

git clone https://github.com/HKUDS/nanobot.git
cd nanobot
pip install -e .

Quick Start

Initialization

# Initialize nanobot
nanobot onboard

# Configure your API keys and model settings in ~/.nanobot/config.json
# Example config.json:

{
  "providers": [
    {
      "name": "openai",
      "base_url": "https://api.openai.com/v1",
      "api_key": "${OPENAI_API_KEY}",
      "model": "gpt-4"
    }
  ],
  "memory": {
    "type": "dream",
    "enabled": true
  }
}

# Start the WebUI
nanobot webui

# Start terminal mode
nanobot terminal

Basic Usage

# Chat with nanobot
nanobot chat "Help me analyze this data"

# Execute a long-horizon goal
nanobot goal "Monitor competitor pricing daily"

# View memory
nanobot memory view

Core Concepts

Dream Memory System

nanobot's Dream memory system provides persistent knowledge across sessions:

from nanobot import Memory

memory = Memory()
memory.store("user_preference", "prefers Python over JavaScript")
memory.recall("user_preference")  # Retrieves stored preference

Long-Horizon Goals

Define persistent goals that nanobot pursues over time:

goals:
  - name: "market-monitoring"
    schedule: "daily 9:00"
    task: "Analyze market trends and report findings"
    persistence: true

Subagent Delegation

Spawn specialized subagents for complex tasks:

from nanobot import Agent

research_agent = Agent(role="research", tools=["web_search", "web_fetch"])
code_agent = Agent(role="coding", tools=["shell", "file_system"])

result = research_agent.run("Research best practices for X")

Advanced Features

Chat Platform Integration

# Telegram
telegram:
  enabled: true
  bot_token: "${TELEGRAM_BOT_TOKEN}"
  chat_id: "${TELEGRAM_CHAT_ID}"

# Discord
discord:
  enabled: true
  bot_token: "${DISCORD_BOT_TOKEN}"
  channel_id: "${DISCORD_CHANNEL_ID}"

# Slack
slack:
  enabled: true
  bot_token: "${SLACK_BOT_TOKEN}"
  signing_secret: "${SLACK_SIGNING_SECRET}"

MCP Server Integration

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Python SDK Integration

import nanobot

agent = nanobot.Agent(
    model="openai/gpt-4",
    tools=["web_search", "file_system", "shell"],
    memory="dream"
)

# Run a task
result = agent.run("Analyze the sales data in ./data/")

# Access memory
memory = agent.memory.recall("sales_trends")

Examples

Market Analysis Automation

User: "Monitor competitor pricing daily"
nanobot: Sets up cron job with web search and data extraction
nanobot: Daily at 9 AM: gathers prices, creates comparison chart, sends report

Software Engineering Assistant

User: "Help me refactor this codebase"
nanobot: Creates subagent for analysis, another for implementation
nanobot: Tracks progress across sessions, remembers your coding preferences

Personal Knowledge Management

User: "Organize my research notes"
nanobot: Scans documents, creates knowledge graph, suggests connections
nanobot: Daily: summarizes new findings, updates knowledge base

Use Cases

• Personal AI Assistant: 24/7 intelligent assistance across messaging platforms
• Research Automation: Continuous monitoring and analysis of topics
• Development Assistant: Code review, refactoring, and testing automation
• Business Intelligence: Market monitoring and competitive analysis
• Content Creation: Automated writing, editing, and publishing
• Learning Assistant: Personalized education and skill development

Pros

• ✅ Ultra-lightweight and readable codebase
• ✅ Extensive chat platform integration (8+ platforms)
• ✅ Dream memory system for persistent knowledge
• ✅ Model freedom with fallback options
• ✅ Full self-hosting capability
• ✅ Python SDK for custom integrations
• ✅ Long-horizon goal support
• ✅ Active development with 45,000+ stars

Cons

• ❌ Requires Python 3.11+
• ❌ API keys needed for most functionality
• ❌ Configuration requires technical comfort
• ❌ Smaller ecosystem than enterprise platforms
• ❌ Memory system still maturing
• ❌ Limited documentation compared to larger projects

When to Use

nanobot is ideal for:

• Self-Hosted Enthusiasts: Full control over your AI agent
• Multi-Platform Teams: Need agent access across many chat platforms
• Long-Term Automation: Tasks that benefit from persistent memory
• Privacy-Focused Users: Keep all data local and under your control
• Custom Integration: Need programmatic access via Python SDK
• Budget-Conscious Teams: Runs on minimal hardware

Resources

• GitHub Repository
• Official Documentation
• PyPI Package
• Discord Community