Built in Zig for performance, designed for awareness. satibot is a lightweight, memory-aware AI agent framework that never forgets. Inspired by OpenClawd and nanobot, it combines the power of ReAct loops with persistent memory to create agents that remember, learn, and assist.

IMPORTANT: Currently, it only supports Openrouter (LLM provider), Telegram and console, other features are under development.

• Telegram + OpenRouter (Sync version)
• Console
• chat history saved to JSON base session file, start new session with /new message
• VectorDB - very simple local first vector searching for similar content chat logs.
• OpenTelemetry tracing for observability
• HTTP Web API (zap framework) for REST interface built on top of the Zap logging library (used for fast, structured logging)
• apps/music/README.md - MiniMax music generation CLI
• File operations - built-in read_file tool for reading local files with security restrictions
• Web fetching - built-in web_fetch tool for fetching and extracting readable content from URLs

• ⚡️ Blazing Fast: Written in Zig for zero-overhead performance
• 🐵 Never Forgets: Built-in RAG, VectorDB, and GraphDB for long-term memory
• 🔧 Extensible: Easy skill installation and tool system
• 💬 Multi-Platform: Telegram, Console, Web API, and more
• 📊 Observability: Built-in OpenTelemetry tracing support

View more in Features.

• OS: Linux, macOS, or Windows (with WSL)

Note: This project uses Zig 0.15.2's thread-based concurrency with XevEventLoop.

🪶 Lightweight & Fast: Minimal footprint with Zig's performance guarantees 🔬 Research-Ready: Clean, readable codebase perfect for experimentation ⚡️ Gateway System: Single command runs all services together 🤖 Smart Memory: RAG + VectorDB + GraphDB for intelligent context management 🔧 Skill Ecosystem: Browse and install skills from https://agent-skills.md/ 📁 File Operations: Built-in tools for reading and analyzing local files 🎙️ Voice Ready: Automatic voice transcription with Groq ⏰ Proactive: Heartbeat system wakes agent for pending tasks 📅 Scheduled: Built-in cron for recurring tasks

Install Zig: https://ziglang.org/learn/getting-started/

# verify zig version
zig version
# 0.15.2

git clone https://github.com/satibot/satibot.git
cd satibot

# build all targets
zig build
# output: zig-out/bin/
# run:
# ./zig-out/bin/sati
# ./zig-out/bin/s-console-sync
# ./zig-out/bin/s-console
# ./zig-out/bin/s-telegram

# build release version
zig build -Doptimize=ReleaseFast --prefix $HOME/.local
# or
make prod

# initialize `~/.bots/config.json` (at HOME path)
# If platform sections already exists, it will do nothing
# default config is:
# - using `arcee-ai/trinity-large-preview:free`
# - using `openrouter`
# - using `telegram`
sati init

This is a Zig monorepo with the following structure:

libs/
  ├── core/         - Config and constants (shared)
  ├── http/         - HTTP client module
  ├── providers/    - LLM provider implementations
  ├── db/           - Database and session modules
  ├── utils/        - Shared utilities (xev_event_loop)
  └── agent/        - Core agent logic

apps/
  ├── console/      - Console applications (sync + async)
  ├── telegram/     - Telegram bot
  └── web/          - Web API backend (CORS support)

Read docs/TELEGRAM_GUIDE.md for more details about Telegram + OpenRouter setup. Edit ~/.bots/config.json:

{
  "agents": {
    "defaults": {
      "model": "arcee-ai/trinity-large-preview:free"
    }
  },
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx"
    }
  },
  "tools": {
    "telegram": {
      "botToken": "",
      "chatId": ""
    }
  }
}

Add sati to your PATH, for example add to ~/.zshrc:

export PATH="/Users/your-username/chatbot/satibot/zig-out/bin:$PATH"

# Show help and available commands
sati help

# for console (sync version - simple & reliable)
sati console-sync

# for console (async version with xev event loop)
sati console

# for telegram (sync version - simple & reliable)
sati telegram-sync

# for telegram (async version)
sati telegram

# for web api backend (requires web module enabled)
sati web -Dweb=true

# Check system status
sati status

# Vector database operations
sati vector-db stats
sati vector-db add "Your text here"
sati vector-db search "query text"

# Test LLM provider connectivity
sati test-llm

# Run binaries directly from zig-out/bin/
./zig-out/bin/s-console-sync
./zig-out/bin/s-console
./zig-out/bin/s-telegram
./zig-out/bin/sati
./zig-out/bin/web              # Web API (build with -Dweb=true)

# Build all targets (debug)
zig build

# Build specific targets
zig build sati              # Sati CLI
zig build s-console          # Async console app
zig build s-console-sync     # Sync console app
zig build s-telegram         # Telegram bot
zig build web -Dweb=true     # Web API backend (requires -Dweb=true)

# Build and run
zig build run-console          # Build and run async console
zig build run-console-sync     # Build and run sync console
zig build run-telegram         # Build and run telegram bot
zig build run-web -Dweb=true   # Build and run web backend

# Web app specific commands
zig build -Dweb=true           # Build with web module enabled
./zig-out/bin/web              # Run built web binary
zig build run-web -Dweb=true   # Build and run web app directly

When using sati agent, you can use these options:

# Disable RAG (Retrieval-Augmented Generation)
sati agent --no-rag

# Single message with RAG disabled
sati agent -m "Hello, how are you?" --no-rag

# Interactive mode with specific session and RAG disabled
sati agent -s chat123 --no-rag

satibot offers two Telegram bot implementations: 🔄 Sync Version (s-telegram-sync)

• Simple, reliable, single-threaded
• Processes one message at a time
• Lower resource usage (~1MB on macOS M1)
• Text messages only (no voice support)
• Best for: development, small deployments, resource-constrained environments

⚡ Async Version (s-telegram)

• High-performance, event-driven (xev-based)
• Processes multiple messages concurrently
• Higher resource usage - RAM usage more than 3.5MB on macOS M1 (disable RAG with --no-rag option)

See docs/TELEGRAM_SYNC_VS_ASYNC.md for detailed comparison.

• Telegram: sati telegram-sync or sati telegram
• docs/TELEGRAM_GUIDE.md
• docs/TELEGRAM_SYNC_VS_ASYNC.md
• docs/TELEGRAM_SYNC.md
• Terminal console: sati console-sync or sati console
• docs/CONSOLE.md
• Web API: sati web -Dweb=true (requires web module enabled)
• docs/WEB_API.md

• VectorDB: Semantic search across conversations
• GraphDB: Relationship mapping for complex knowledge
• RAG: Retrieval-Augmented Generation for accurate responses
• Session Cache: In-memory session history with automatic cleanup (30 minutes idle timeout)

🎯 Perfect For Chat Logs:

• Semantic Search: Find similar conversations by meaning, not just keywords

• Local First: No external database dependencies

• Fast Enough: Linear search suitable for thousands of entries

• Auto-indexing: Already integrated with conversation indexing

• Storage: ~/.bots/vector_db.json

• Usage:

sati vector-db stats
sati vector-db list
sati vector-db search "your query" [top_k]
sati vector-db add "my name is John"

Browse and install skills from the community:

# Browse available skills
curl https://agent-skills.md/

# Install a new skill
./scripts/install-skill.sh <github-url-or-path>

# Use built-in tools
zig build s-console -- -- agent -m "Run: ls -la"

📁 read_file - Read local files The read_file tool allows the AI agent to read contents of local files on your system.

Usage Examples:

# Ask the agent to read a file
sati console-sync
> Please read the contents of /home/user/config.txt

# Read and analyze a log file
> Can you read /var/log/system.log and summarize any errors?

# Read a code file
> Read the main.zig file and explain what it does

Arguments:

• path (required): Absolute or relative path to the file to read

Example JSON:

{
  "path": "/path/to/your/file.txt"
}

Features:

• ✅ Supports text files of any size (10MB limit)
• ✅ Handles absolute and relative paths
• ✅ Proper error handling for missing files
• ✅ Built-in security restrictions for sensitive files
• ✅ Memory-efficient with automatic cleanup

Security Restrictions: For security reasons, the tool automatically blocks access to sensitive files:

• Environment files: .env, .env.local, .env.* variations
• Private keys: id_rsa, id_ed25519, private_key.*, *.key
• Credentials: credentials.*, secret.*
• Sensitive directories: .ssh/, .aws/, .kube/

Examples of blocked files:

• .env ❌
• id_rsa ❌
• private_key.pem ❌
• .ssh/config ❌
• config.txt ✅
• public_key.pem ✅
• data.json ✅

🌐 web_fetch - Fetch web content See docs/tasks/web-fetch.md for detailed documentation.

Heartbeat: Proactive task checking

# Create a heartbeat task
echo "Check emails" > ~/.bots/HEARTBEAT.md

# Run the telegram bot (includes heartbeat)
sati telegram

# TODO: Cron: Schedule recurring tasks
zig build run -- cron --schedule "0 9 * * *" --message "Daily summary"

TODO: Cron: Schedule recurring tasks via configuration in ~/.bots/config.json

We welcome contributions! Please read our docs/DEV.md for more information.

Sati (Pāli) means "mindful awareness" — the art of not forgetting the present moment - "remembering to stay aware of what is happening right now.". In Buddhist psychology, sati evolved from simple memory to profound awareness:

• Remember you are breathing
• Remember thoughts are arising
• Remember what is happening now

SatiBot embodies this principle:

• Never forgets context or conversations
• Tracks state consistently across sessions
• Stays aware of ongoing processes
• Never loses events in the flow

Licensed under the MIT License.