Single query

February 22, 2026 · View on GitHub

Vicobot

Lightweight AI agent in a single binary — built with V.

Vicobot is a V rewrite of picobot — a lightweight self-hosted AI chatbot. It gives you persistent memory, tool calling, skills, and Telegram integration in a single ~1.2MB binary.

No Python. No Node. No 500MB container. Just one binary and a config file.

Why Vicobot?

	Vicobot	Typical Agent Frameworks
Binary size	~1.2MB	200MB+ (Python + deps)
Docker image	~15MB (Alpine)	500MB–1GB+
Cold start	Instant	5–30 seconds
RAM usage	~2MB idle	200MB–1GB
Dependencies	Zero (single binary)	Python, pip, venv, Node…

Runs on a $5/mo VPS, a Raspberry Pi, or any Linux box.

Quick Start

Docker

cd docker
cp .env.example .env
# Edit .env with your API key
docker-compose build --no-cache
docker-compose up -d

From Source

# Build
v -o vicobot src/main.v

# Initialize config + workspace
./vicobot onboard

# Single query
./vicobot agent -m "Hello!"

# Long-running mode (Telegram, etc.)
./vicobot gateway

Messages flow through a Chat Hub into the Agent Loop, which builds context from memory/sessions/skills, calls the LLM via OpenAI-compatible API, and executes tools before sending replies back.

Channel — Communication channels (Telegram, etc.)
Agent Loop — Context building, LLM calls, tool execution
Memory — Daily notes + long-term storage with semantic search
Skills — Modular knowledge packages

Features

Built-in Tools

Tool	What it does
`filesystem`	Read, write, list files
`exec`	Run shell commands
`web`	Fetch web pages and APIs
`message`	Send messages to channels
`spawn`	Launch background subagents
`cron`	Schedule recurring tasks
`write_memory`	Persist information across sessions
`create_skill`	Create reusable skill packages
`list_skills`	List available skills
`read_skill`	Read a skill's content
`delete_skill`	Remove a skill

Persistent Memory

Daily notes — auto-organized by date
Long-term memory — survives restarts
Ranked recall — retrieves relevant memories

vicobot memory recent --days 7     # this week's notes
vicobot memory rank -q "meeting"   # search memories

Skills System

Teach your agent new tricks. Skills are markdown files in ~/.vicobot/workspace/skills/.

You: "Create a skill for checking weather using curl wttr.in"
Agent: Created skill "weather"

Telegram Integration

Message @BotFather — /newbot — copy token
Add to config or TELEGRAM_BOT_TOKEN env var
Run vicobot gateway

Heartbeat

Periodic check (default: 60s) reads HEARTBEAT.md for scheduled tasks.

Configuration

Config at ~/.vicobot/config.json:

{
  "agents": {
    "defaults": {
      "model": "google/gemini-2.5-flash",
      "maxTokens": 8192,
      "temperature": 0.7,
      "maxToolIterations": 200
    }
  },
  "providers": {
    "openai": {
      "apiKey": "sk-or-v1-YOUR_KEY",
      "apiBase": "https://openrouter.ai/api/v1"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}

Works with any OpenAI-compatible API (OpenAI, OpenRouter, Ollama, etc.).

CLI Reference

vicobot version                        # print version
vicobot onboard                        # create config + workspace
vicobot agent -m "..."                 # one-shot query
vicobot gateway                        # long-running mode
vicobot memory read today|long         # read memory
vicobot memory append today|long -c "" # append to memory
vicobot memory recent --days N         # recent N days
vicobot memory rank -q "query"         # search memories

Tech Stack

Layer	Technology
Language	V
LLM providers	OpenAI-compatible API
Telegram	Raw Bot API (net.http)
HTTP / JSON	V standard library
Container	Alpine Linux (multi-stage build)

Zero external dependencies. Everything uses the V standard library.

Project Structure

src/
├── main.v           # CLI entry point
├── chat/            # Message hub
├── channels/        # Telegram integration
├── config/          # Config loading
├── agent/           # Agent loop, tools
├── memory/          # Memory storage
├── cron/            # Job scheduler
├── providers/       # LLM providers
├── session/         # Session manager
└── heartbeat/       # Periodic tasks
docker/              # Docker deployment

Building

# Development
v run src/main.v

# Production binary
v -prod -cflags "-Os -flto -s" -o vicobot src/main.v

# Cross-compile for ARM
v -prod -os linux -arch arm64 -o vicobot-arm64 src/main.v

Testing

# Run all tests sequentially (recommended)
./run_tests.vsh

# Or run individual test files
v test src/agent/memory/
v test src/agent/tools/

The test runner (run_tests.vsh) automatically discovers all *_test.v files and runs them sequentially to avoid parallel runner issues.

Docs

AGENTS.md — Development guide (build, code style, patterns)
docker/README.md — Docker deployment

License

MIT