🤖 SimpleContext-Bot

AI Telegram Bot powered by SimpleContext
Setup wizard · 15 agents · Dynamic plugins · Works with Gemini, OpenAI, Ollama

---

✨ What is this?

SimpleContext-Bot is a ready-to-run Telegram bot powered by SimpleContext — a structured AI brain with tiered memory, intent planning, and context scoring.

A built-in setup wizard automatically downloads the engine, 15 agents, and optional plugins — then walks you through configuration step by step.

---

🚀 Installation

Option A — pip (recommended)

pip install simplecontext-bot
simplecontext-bot setup
simplecontext-bot start

Option B — from source

git clone https://github.com/zacxyonly/SimpleContext-Bot.git
cd SimpleContext-Bot
pip install .
simplecontext-bot setup
simplecontext-bot start

---

🧙 Setup Wizard

simplecontext-bot setup

The wizard handles everything in 6 steps:

═══════════════════════════════════════════════════════
🧠 SimpleContext-Bot — Setup Wizard
═══════════════════════════════════════════════════════
Step 1/6 Download SimpleContext engine ✅
Step 2/6 Download 15 agent definitions ✅
Step 3/6 Plugin Ecosystem (Optional)
Install Vector Search? [y/N]: y ✅
Install Summarizer? [y/N]: y ✅
Step 4/6 Telegram Bot Token → paste from @BotFather
Step 5/6 LLM Provider & API Key → Gemini / OpenAI / Ollama
Step 6/6 Final configuration ✅ Done!

---

🔑 Getting Your Tokens

Telegram Bot Token

1. Open Telegram → search @BotFather
2. Send /newbot → follow the steps → copy the token

Gemini API Key(free, recommended)

1. Go to aistudio.google.com/app/apikey
2. Click Create API Key → copy

OpenAI API Key

1. Go to platform.openai.com/api-keys
2. Click Create new secret key → copy

Ollama(local, free, no API key)

1. Install from ollama.ai
2. ollama pull llama3
3. Make sure Ollama is running before starting the bot

---

🎯 Auto-Routing

No need to manually switch agents. The bot detects the best agent automatically:

"ada bug di python saya" → 🖥️ coding
"deploy ke server nginx" → 🚀 devops
"tulis caption instagram" → ✍️ writer
"terjemahkan ke english" → 🌐 translator
"jelaskan konsep ini" → 📚 tutor
"ringkas artikel ini" → 📝 summarizer
"cek fakta berita ini" → 🔍 researcher
"komplain order saya" → 🎧 customer_service
"analisis data penjualan" → 📊 analyst
"bantu investasi saham" → 💰 finance
"cek kontrak ini" → ⚖️ legal
"brainstorm ide startup" → 🎨 creative
"tips produktivitas" → ⚡ productivity
"olahraga untuk pemula" → 💪 health

---

🤖 Available Agents (15)

Core

	Agent	Description
🧠	general	Default fallback — smart routing to specialized agents
🖥️	coding	Expert programmer — debug, review, all languages
🚀	devops	Server, Docker, CI/CD, Linux infrastructure
✍️	writer	Content, copywriting, email, social media

Knowledge & Research

	Agent	Description
🔍	researcher	Fact-checking, research, source evaluation
📚	tutor	Patient adaptive teacher for any subject
📝	summarizer	Condense any content into clear summaries
🌐	translator	Multi-language, idiom-aware translation

Business & Professional

	Agent	Description
📊	analyst	Data analysis, business insights, KPIs
🎧	customer_service	Empathetic CS, complaint handling
💰	finance	Budgeting, investing, financial planning
⚖️	legal	Contracts, rights, Indonesian law reference

Lifestyle & Creativity

	Agent	Description
🎨	creative	Brainstorming, storytelling, naming, worldbuilding
⚡	productivity	Time management, habits, GTD, focus systems
💪	health	Fitness, nutrition, sleep, mental wellness

---

💬 Bot Commands

Built-in Commands

Command	Description
/start	Welcome message, saves your name
/help	Show all commands including plugin commands
/agents	List all available agents
/agent <n>	Switch to a specific agent
/agent auto	Back to auto-routing
/clear	Clear conversation history (keeps profile)
/status	Show current agent, message count, active plugins
/memory	Show your saved profile
/plugins	List active plugins and their commands

Plugin Commands (auto-registered)

Plugin commands register automatically when a plugin is loaded:

Command	Plugin Required	Description
/semantic <query>	vector-search	Search memory by meaning
/summary	summarizer	Summarize conversation
/search <query>	web-search	Search the internet
/translate <lang>	translate	Set language or translate
/sentiment	sentiment	View sentiment analysis
/analytics	analytics	View usage statistics
/usage	rate-limiter	Check your usage quota

---

🔌 Plugin Ecosystem

Extend the bot with plugins from SimpleContext-Plugin.

Available Official Plugins

Plugin	Description
vector-search	Semantic memory search — find by meaning, not exact words
analytics	Usage statistics per user and agent
summarizer	Auto-compress conversation to episodic memory via LLM
web-search	Real-time internet search (DuckDuckGo free, Bing, Google)
translate	Multi-language — auto-detect 20+ languages
sentiment	Sentiment analysis — adapts agent tone when user is frustrated
rate-limiter	Limit requests per hour/day, token estimation

Install Plugins

simplecontext-bot plugins list # fetch list from GitHub registry
simplecontext-bot plugins install vector-search # install a plugin
simplecontext-bot plugins install summarizer
simplecontext-bot plugins remove vector-search # remove a plugin

Manual (community plugins):

cp my_plugin.py ~/.simplecontext-bot/plugins/
simplecontext-bot start # auto-detected on startup

How Plugin Commands Work

Plugins declare their own Telegram commands via app_commands (SimpleContext v4.3 standard). The bot registers them automatically — no code changes needed:

classMyPlugin(BasePlugin):
app_commands= {
"mycommand": {
"description": "What this does",
"usage": "/mycommand <arg>",
"handler": "handle_mycommand",
}
}
asyncdefhandle_mycommand(self, ctx: AppCommandContext) ->str:
returnf"Hello from {ctx.platform}! Query: {ctx.args_str}"

Drop the file → restart → /mycommand is live in Telegram.

---

⚙️ CLI Commands

# Setup & Start
simplecontext-bot setup # First-time setup wizard
simplecontext-bot start # Start the bot
simplecontext-bot start --debug # Start with verbose logging# Status & Info
simplecontext-bot status # Show configuration summary
simplecontext-bot status --test # Check + test LLM connection
simplecontext-bot dashboard # Show usage stats and system info
simplecontext-bot agents # List installed agents# Update
simplecontext-bot update # Update engine + agents + plugins
simplecontext-bot update --engine-only # Update engine only
simplecontext-bot update --agents-only # Update agents only
simplecontext-bot update --plugins-only # Update installed plugins only# Plugins
simplecontext-bot plugins list # List plugins (fetches from GitHub)
simplecontext-bot plugins install <id># Install a plugin
simplecontext-bot plugins remove <id># Remove a plugin# Config (change any value without re-running setup)
simplecontext-bot set llm.api_key <key># Update API key
simplecontext-bot set llm.model <model># Change LLM model
simplecontext-bot set llm.provider <p># Switch provider (gemini/openai/ollama)
simplecontext-bot set telegram.token <t># Update Telegram token
simplecontext-bot set bot.debug true# Enable debug logging
simplecontext-bot set bot.memory_limit 30 # Increase memory limit

---

📊 Dashboard

simplecontext-bot dashboard

╔══════════════════════════════════════════════════╗
║ SimpleContext-Bot Dashboard ║
╚══════════════════════════════════════════════════╝
🔧 System
──────────────────────────────────────────────────
Engine : ✅ Installed
DB size : 2.4 MB
Telegram : ✅ Configured
🤖 Agents & Plugins
──────────────────────────────────────────────────
Agents : 15 installed
Plugins : 2 installed (vector_search_plugin, summarizer_plugin)
🧠 LLM
──────────────────────────────────────────────────
Provider : gemini
Model : gemini/gemini-2.0-flash
📊 Usage Stats
──────────────────────────────────────────────────
Users : 42
Nodes : 1,847

---

📁 Files After Setup

~/.simplecontext-bot/
├── config.json ← settings (tokens, LLM, plugins)
├── bot.db ← conversation memory (SQLite)
├── simplecontext/ ← engine (auto-downloaded)
├── agents/ ← 15 agent YAML files (auto-downloaded)
│ ├── general.yaml
│ ├── coding.yaml
│ └── ...
└── plugins/ ← installed plugins
├── vector_search_plugin.py
└── summarizer_plugin.py

---

🔧 Troubleshooting

Diagnose issues:

simplecontext-bot status --test

Update everything:

simplecontext-bot update

Change a config value without re-running setup:

simplecontext-bot set llm.api_key <new-key>
simplecontext-bot set llm.model gemini/gemini-2.5-flash
simplecontext-bot set telegram.token <new-token>

Start fresh:

rm -rf ~/.simplecontext-bot
simplecontext-bot setup

---

🧠 Powered By

Repo	Role
SimpleContext	AI brain — tiered memory, context scoring, intent planning
SimpleContext-Agents	15 ready-to-use agent definitions
SimpleContext-Plugin	Official plugin registry
LiteLLM	Universal LLM connector

---

🔗 Ecosystem

Repo	Description
SimpleContext	Core engine — Universal AI Brain
SimpleContext-Agents	Ready-to-use agent definitions
SimpleContext-Plugin	Plugin registry
SimpleContext-Bot	This repo
SimpleContext-Docs	Full documentation

---

Built with ❤️ on top of SimpleContext

⭐ Star the engine repo if you find this useful!