A persistent, self-evolving agentic AI that lives across your devices with a soul, a memory, and a personality that's actually yours. Inspired by the powerful OpenClaw and the lightweight architecture of Nanobot.
LimeBot is not a wrapper around an API. It's a full agentic system event-driven, multi-channel, and built to remember who you are. It browses the web, manages your files, schedules reminders, spawns sub-agents for complex tasks, and evolves its personality through every conversation. All of it runs on your hardware. Currently in public Beta and works best with Google Gemini.
Three-tier memory system that persists across sessions:
- Episodic Memory every conversation is appended to a daily markdown journal (
persona/memory/YYYY-MM-DD.md) - Semantic Memory entries are embedded and stored in a local LanceDB vector database, enabling fuzzy recall of anything said weeks ago
- Auto-RAG before every reply, LimeBot automatically searches its memory (semantically first, grep fallback) and injects relevant context into the prompt without you asking
- Reflection Engine a background cron job runs every 4 hours, reads today's journal, and distills the key facts into a permanent
MEMORY.mdlong-term essence file
Not a hardcoded system prompt. A living identity that evolves:
SOUL.mdcore values, personality, and behavioral boundariesIDENTITY.mdname, emoji, avatar URL, style, catchphrases, interests, birthday- Local-first persona files first boot auto-creates starter
SOUL.md,IDENTITY.md, andMEMORY.mdfrom shipped.exampletemplates so users get a clean bot without committing live persona state - Per-platform styles separate voice for Discord, WhatsApp, and Web
- Per-user profiles builds a relationship profile for each person it talks to, tracking affinity scores, relationship level, in-jokes, and milestones
- Dynamic Mood optional
MOOD.mdthat shifts based on conversations and persists between sessions - Setup Interview if the local persona files are missing or invalid, the bot interviews you to rebuild its identity and saves the result automatically once it has enough to work with.
Full Playwright-powered browser automation:
- Navigate to any URL, click elements, fill forms, scroll pages
google_search()shortcut for quick lookups- Extract page text, take DOM snapshots, list all media on a page
- Download high-resolution images from Pinterest, Reddit, Wikimedia, direct URLs
- Results stream back in real time with progress updates in the dashboard
Whitelisted filesystem operations:
- Read, write, create, delete, move, rename files and directories
- All operations sandboxed to
ALLOWED_PATHSnothing outside those roots is touchable unless you explicitly allow it - Dangerous operations (write, delete, run) require explicit confirmation through the web UI before executing
Secure subprocess execution with real-time output streaming:
- Runs shell commands inside the project root
- Shell injection filter blocks
;,&&,|, backticks,$(), and env manipulation - Stall detection if a command produces no output for 30 seconds (likely waiting for interactive input), it's automatically terminated with guidance to retry using non-interactive flags
- Requires user confirmation via the dashboard before any command executes
- Autonomous Mode optionally bypass all confirmation prompts for full hands-off operation
- Session-based approval approve a tool once for the current session without enabling full autonomy
Persistent cron system:
- One-time reminders:
"remind me in 2 hours to call mom" - Repeating jobs: full cron expression support (
0 8 * * *) - Jobs survive restarts (persisted to
data/cron.json) - With Dynamic Personality enabled: automatic morning greetings and silence check-ins
For complex multi-step tasks, LimeBot can delegate work to an isolated background agent:
- Sub-agent runs in its own session with its own tool loop
- Built-in specialist profiles like
reviewer,verifier, andexplorercan be recommended automatically when the request wording matches the task - Custom subagents can also be suggested when their descriptions overlap strongly with the current request
- Reports back to the parent session when complete
- The web chat renders delegated results as a dedicated sub-agent report card instead of raw trace text
- Useful for long-running research, file processing, or anything that shouldn't block the main conversation
LimeBot is a fully-featured MCP client:
- Universal Tool Integration connect to any MCP server (Fetch, Filesystem, Brave Search, etc.) to immediately expand the bot's capabilities.
- Dynamic Discovery tools from connected MCP servers are automatically prefixed with
mcp_server_name_and injected into the AI's tool registry. - Configurable Servers manage server arguments and environment variables directly from the web dashboard.
- Safety & Resilience built-in timeouts and error handling ensure that misbehaving MCP servers don't hang the main agent loop.
| Channel | How it works |
|---|---|
| Web Dashboard | React + Vite UI connecting over WebSocket. Streams tokens as they arrive, shows live tool execution cards, confirmation prompts, thinking traces, and ghost activity indicators. Includes a Custom CSS editor for global UI personalization. |
| Discord | Full discord.py integration. Responds to DMs and @mentions. Configurable allow-list by user ID and channel ID. Custom presence status, activity type, and display name. |
Connects to a local whatsapp-web.js bridge over WebSocket. Contact approval whitelist with pending/blocked states. QR code displayed in the web dashboard for easy pairing. |
|
| Telegram | Bot API long-polling scaffold. Supports text send/receive, per-user allow-listing, optional per-chat allow-listing, and startup wiring for future expansion. |
LimeBot uses LiteLLM any model it supports, LimeBot supports:
| Provider | Example model string |
|---|---|
| Gemini (default) | gemini/gemini-2.0-flash |
| OpenAI | openai/gpt-4o |
| Anthropic | anthropic/claude-3-5-sonnet-20241022 |
| xAI | xai/grok-2 |
| DeepSeek | deepseek/deepseek-chat |
| Qwen (DashScope) | qwen/qwen-max |
| NVIDIA Reference | nvidia/meta/llama-3.1-405b-instruct |
| Switch models live from the web dashboard without restarting. |
LimeBot supports routing all LLM traffic through external security or caching middleware (like AI Gateway, Open Guardian, or Helicone):
LLM_PROXY_URLconfigure a global proxy URL in the dashboard or.env. This overrides the default base URL for all providers.- Provider Normalization LiteLLM handles the complex routing and header manipulation required to use custom gateways with cloud providers.
Skills extend what LimeBot can do. Each skill is a folder with a SKILL.md (the LLM instructions) and a skill.py or script (the execution logic).
Built-in skills:
| Skill | What it does |
|---|---|
browser |
Full Playwright web browsing navigate, click, type, search, extract |
download_image |
Download high-res images from Pinterest, Reddit, Wikimedia, or direct URLs |
filesystem |
Extended file operations beyond the core toolbox |
discord |
Send messages and embeds to any Discord channel by ID |
whatsapp |
Send files and media to WhatsApp conversations |
docx-creator |
Generate formatted Microsoft Word .docx documents |
ClawHub Skills:
LimeBot supports installing skills from the ClawHub registry. These are community-built tools that LimeBot can call as clawhub_<skill_name>.
| Skill | What it does |
|---|---|
clawhub_weather |
Get current weather and forecasts for any location (no API key required) |
Install a ClawHub skill:
npx clawhub install <skill-name> --workdir ./skills/clawhub --dir installedInstalled skills appear in skills/clawhub/installed/ and are automatically available as tools. Enable or disable them from the Skills tab in the web dashboard.
Install community skills from GitHub:
# Full URL
python -m core.skill_installer install https://github.com/user/my-lime-skill
# GitHub shorthand
python -m core.skill_installer install user/my-lime-skill
# Or via the CLI wrapper
npm run lime-bot skill install https://github.com/user/my-lime-skillThe installer auto-detects the repo's default branch, and automatically runs pip install or npm install if dependency files are present.
Other skill commands:
python -m core.skill_installer list
python -m core.skill_installer update <skill_name>
python -m core.skill_installer uninstall <skill_name>
python -m core.skill_installer enable <skill_name>
python -m core.skill_installer disable <skill_name>Skills can also be managed from the Skills tab in the web dashboard.
- OS: Windows 10+, macOS 11+, or Linux (Ubuntu 20.04+)
- CPU: Dual-core (Quad-core recommended for browser tools)
- RAM: 4GB Minimum (8GB recommended for multitasking)
- Disk: ~2GB for installation (venv, node_modules, Chromium)
- Software: Node.js 18+, Python 3.11-3.14
- Windows asyncio: LimeBot relies on asyncio's default Proactor loop on Windows instead of manually forcing a deprecated event loop policy, which keeps Python 3.11-3.14 on one runtime path.
- Connectivity: Stable internet for LLM API and web browsing
git clone https://github.com/LemonMantis5571/LimeBot.git
cd LimeBot
npm run lime-bot startThe CLI handles everything on first run: creates a Python venv, installs backend + frontend dependencies, and opens the web UI. On first chat, LimeBot will interview you to build its persona.
# Terminal 1 Backend
cp .env.example .env # fill in your keys
pip install -r requirements.txt
python main.py
# Terminal 2 Frontend
cd web && npm install && npm run devdocker-compose up --buildCopy .env.example to .env:
# Core
LLM_MODEL=gemini/gemini-2.0-flash
GEMINI_API_KEY=your_key_here
DASHSCOPE_API_KEY=your_dashscope_key_here
# Optional for Qwen region routing:
# LLM_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1
# Channels (all optional)
DISCORD_TOKEN=your_discord_bot_token
ENABLE_WHATSAPP=false
WEB_PORT=8000
FRONTEND_PORT=5173
# Security
ALLOWED_PATHS=./persona,./logs,./temp
APP_API_KEY=optional_dashboard_password
# Features
ENABLE_DYNAMIC_PERSONALITY=false # per-user affinity, mood tracking, proactive greetings
LLM_PROXY_URL=http://localhost:8080/v1 # Optional: Route all traffic through a gatewayEverything can also be changed live from the Config tab in the web dashboard changes write .env and trigger a clean restart.
- Local-first all conversations, memories, and personal data stay on your machine.
- Sandboxed Filesystem LimeBot can only read/write files in directories you explicitly whitelist.
- Human-in-the-loop sensitive actions (running code, deleting files) require your confirmation.
- Open Source audit the code yourself. No hidden telemetry.
We love contributions! Please check out CONTRIBUTING.md for guidelines on how to submit PRs, report bugs, or request features.
MIT © LemonMantis5571