agent9

A simple Telegram bot that runs on GitHub Actions, processes messages using OpenAI's GPT-4o-mini, and replies to users.

Features

• Runs automatically on GitHub Actions every 10 minutes
• Fetches updates from Telegram Bot API using curl
• Processes messages with OpenAI's GPT-4o-mini model
• Executes shell commands from natural language: Ask the bot in plain English to perform system tasks (e.g., "list all files", "show disk usage", "create a directory") and it will convert your request to the appropriate shell command and execute it
• Persistent Memory System: The bot remembers information across sessions using three memory files:
  • soul.md: Stores reflections, learnings, and philosophical insights
  • memory.md: Records episodic memory - significant events and conversations
  • user.md: Maintains user profiles and preferences
• Memory Management: Users can clear all memory or specific memory types when needed (e.g., "clear all memory", "forget about me")
• Self-Updating Memory: The bot can update its memory files when instructed and automatically commits changes back to the repository
• Sends AI-generated responses back to users
• Lightweight shell script implementation with jq for reliable JSON parsing
• Automatic installation of jq if not available

Setup

Prerequisites

1. Telegram Bot Token: Create a bot via @BotFather on Telegram and get your bot token
2. OpenAI API Key: Get your API key from OpenAI Platform

Configuration

Add the following secrets to your GitHub repository:

1. Go to your repository settings → Secrets and variables → Actions
2. Add the following secrets:
   • TELEGRAM_BOT_TOKEN: Your Telegram bot token (e.g., 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
   • OPENAI_API_KEY: Your OpenAI API key (e.g., sk-...)

How It Works

1. The GitHub Action runs every 10 minutes (configurable in .github/workflows/telegram-bot.yml)
2. The bot.sh script:
   • Fetches updates from Telegram Bot API
   • Extracts messages and user IDs
   • Sends each message to OpenAI's GPT-4o-mini for processing
   • If the message is a command request (e.g., "list files", "show date"):
     • OpenAI converts the natural language to a shell command
     • The bot executes the command safely (with a 30-second timeout)
     • Returns the command output to the user
   • Otherwise, replies with a normal AI-generated response
3. The script runs for 10 minutes per execution, continuously polling for new messages

Example Commands

You can ask the bot to execute commands in natural language:

• "list all files" → executes ls -la
• "show current directory" → executes pwd
• "show disk usage" → executes df -h
• "what's the date and time?" → executes date
• "show system information" → executes uname -a
• "create a test directory" → executes mkdir test
• "copy file A to file B" → executes cp A B
• "move file A to file B" → executes mv A B

The bot will also respond to regular conversation without executing commands.

Memory System

The bot has a persistent memory system that allows it to remember information across sessions:

Memory Files:

• soul.md: Reflections, learnings, and philosophical insights
• memory.md: Episodic memory of significant events and conversations
• user.md: User profiles and preferences

How to Use:

• The bot automatically loads these files as context for every conversation
• You can ask the bot to remember things: "Remember that I prefer Python over JavaScript"
• You can ask the bot to reflect: "What have you learned from our conversations?"
• The bot will update these files when it learns something significant
• All memory updates are automatically committed and pushed to the repository

Clearing Memory:

• You can ask the bot to clear all memory: "clear all memory" or "forget everything"
• You can clear specific memory types:
  • "forget about me" or "clear user profile" - clears user information
  • "forget our conversations" or "clear episodic memory" - clears conversation history
  • "reset your learnings" or "clear your reflections" - clears reflections and insights
• Memory clearing is permanent and committed to the repository

Examples:

• "Remember that my name is John and I love coding in Python"
• "Update your memory about what we discussed today"
• "What do you know about me?"
• "Reflect on what you've learned"
• "Clear all memory" - removes all stored information
• "Forget about me" - removes your user profile

Manual Trigger

You can also manually trigger the bot:

1. Go to Actions tab in your repository
2. Select "Telegram Bot" workflow
3. Click "Run workflow"

File Structure

.
├── .github/
│   └── workflows/
│       └── telegram-bot.yml    # GitHub Actions workflow
├── bot.sh                       # Main bot script
├── soul.md                      # Bot's reflections and learnings
├── memory.md                    # Episodic memory
├── user.md                      # User profiles
└── README.md                    # This file

Customization

• Polling Frequency: Edit the cron schedule in .github/workflows/telegram-bot.yml
• Execution Time: Modify TIMEOUT variable in bot.sh (default: 600 seconds / 10 minutes)
• OpenAI Model: Change the model parameter in the process_with_openai function (default: gpt-4o-mini)

Notes

• The bot processes messages sequentially to avoid rate limiting
• Update offset is saved to /tmp/telegram_offset.txt to avoid processing duplicate messages
• The script uses curl for all API calls and jq for JSON parsing (automatically installed if needed)
• Proper JSON escaping ensures messages with special characters are handled correctly
• Memory Persistence: Memory files are automatically loaded as context for every conversation and can be updated by the bot when instructed
• Memory Updates: The bot commits and pushes memory file changes to the repository automatically
• Command execution safety:
  • Commands are executed with a 30-second timeout to prevent hanging processes
  • File deletion and destructive commands (rm, rmdir, unlink, shred, dd, mkfs, truncate) are blocked for security
  • File redirection (>, >>) is blocked to prevent file creation/overwrites
  • Command substitution ($(), backticks) is blocked to prevent indirect execution of blocked commands
  • Command chaining with blocked operations is prevented
  • All other command types are allowed (mkdir, touch, cp, mv, etc.)
  • Command validation is performed before execution
• Security note: The bot runs in a sandboxed GitHub Actions environment. The command blacklist prevents file deletion and destructive operations