https://github.com/umaarov/my-system
An intelligent Telegram userbot, featuring a persistent memory to learn from conversations, adapt, and respond with a unique, evolving persona.
https://github.com/umaarov/my-system
ai ai-memory asnycio automation chatbot gemini-api generative-ai mysql nlp python telegram-userbot telethon
Last synced: about 2 months ago
JSON representation
An intelligent Telegram userbot, featuring a persistent memory to learn from conversations, adapt, and respond with a unique, evolving persona.
- Host: GitHub
- URL: https://github.com/umaarov/my-system
- Owner: umaarov
- Created: 2025-09-07T20:31:29.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2025-09-07T20:31:33.000Z (9 months ago)
- Last Synced: 2026-01-21T05:42:37.290Z (5 months ago)
- Topics: ai, ai-memory, asnycio, automation, chatbot, gemini-api, generative-ai, mysql, nlp, python, telegram-userbot, telethon
- Language: Python
- Homepage:
- Size: 9.77 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
## My System
An intelligent, self-learning Telegram userbot powered by Google's Gemini AI and a persistent MySQL database for long-term memory.
---
### About The Project
My System is not just a standard userbot; it's a digital extension of the user. It actively listens to conversations it's part of, learns facts about the user, and understands their opinions on various topics. By leveraging a powerful AI model and a structured database, it builds a long-term memory, allowing it to reply to mentions with context, personality, and knowledge that grows over time.
The core philosophy is to create an AI assistant that is indistinguishable from a real person, with an adaptive, witty, and intelligent persona.
---
### Key Features
* **🧠AI with Persistent Memory**: Learns new facts and opinions from conversations and stores them in a MySQL database, ensuring knowledge is never lost.
* **💬 Context-Aware Replies**: Responds intelligently when mentioned by using both short-term (recent chat history) and long-term (facts and opinions) memory.
* **🎠Adaptive Persona**: Dynamically adjusts its response tone based on the context of the query—behaving as a helpful assistant for factual questions, a witty companion for casual chats, and a sharp defender against insults.
* **📜 Advanced Chat Summarization**: Quickly get the gist of any conversation with the powerful `.summarize` command, which can analyze recent messages, unread messages, or messages from a specific user.
* **🔒 Secure & Private**: Operates as a user account (userbot), giving you full control over its actions and ensuring your data and conversations remain private.
---
### Technology Stack
* **Core**: Python 3.9+
* **Telegram API**: Telethon
* **AI Model**: Google Gemini
* **Database**: MySQL (via aiomysql)
* **Configuration**: python-dotenv
---
### Setup and Installation
Follow these steps to get your instance of My System up and running.
#### **Prerequisites**
* Python 3.9 or higher.
* A running MySQL-compatible database (e.g., local MySQL, PlanetScale, Aiven).
* Your Telegram **API_ID** and **API_HASH**. Get them from [my.telegram.org](https://my.telegram.org).
* A **Google API Key** for Gemini. Get one from [Google AI Studio](https://aistudio.google.com/app/apikey).
#### **Installation Steps**
1. **Clone the repository:**
```sh
git clone https://github.com/umaarov/my-system.git
cd my-system
```
2. **Install the required packages:**
```sh
pip install -r requirements.txt
```
3. **Configure your environment variables:**
Create a file named `.env` in the project root and populate it with your credentials. You can use the example below as a template.
```env
# .env file
# --- Telegram Credentials ---
API_ID=1234567
API_HASH=your_api_hash_here
# --- Google Gemini AI ---
GOOGLE_API_KEY=your_google_api_key_here
# --- Database Connection ---
DB_HOST=your_database_host
DB_PORT=3306
DB_USER=your_database_username
DB_PASS=your_database_password
DB_NAME=your_database_name
```
4. **Set up your user identity:**
Open `config.py` and change the `MY_USERNAME` and `MY_ALIASES` to match your own Telegram username and real names/nicknames. This is crucial for the bot to know when a message is about you.
```python
# config.py
MY_USERNAME = "your_telegram_username"
MY_ALIASES = ["your_first_name", "your_last_name", "your_nickname"]
```
5. **Initialize the database:**
Run the setup script once to create all the necessary tables in your database.
```sh
python setup_database.py
```
You should see a success message indicating the tables are ready.
---
### Usage
To start the userbot, simply run the main script:
```sh
python userbot.py
```
The first time you run it, Telethon will ask you to log in with your phone number, password, and 2FA code in the console. After a successful login, a `userbot.session` file will be created, and subsequent runs will be automatic.
#### **Commands**
* **Summarize Chat**: Use the `.summarize` command in any chat.
* `.summarize 50`: Summarizes the last 50 messages.
* `.summarize @username`: Summarizes the last 50 messages from a specific user.
* `.summarize unread`: Summarizes all unread messages in the chat.
---
### Database Schema
The bot's "memory" is structured across four main tables:
* **`entities`**: Stores unique nouns identified in conversations (e.g., people, places, topics).
* **`facts`**: Stores specific attributes about entities, particularly the user (e.g., `(entity: dribbblxr, attribute: location, value: Uzbekistan)`).
* **`user_opinions`**: Stores the user's sentiment (positive, negative, neutral) towards different entities.
* **`conversation_history`**: Acts as the short-term memory, storing recent messages from chats for contextual replies.