A Telegram-based conversational AI agent that acts as a personal companion. It maintains long-term memory through user/agent profiles, manages daily routines, supports file uploads/workspace editing, performs web searches with headless browser fallback, analyzes images, visits websites directly, and sends proactive messages based on configured schedules.

Key Features

Long-term memory: User and agent profiles with auto-enrichment from conversations
Daily routine management: Schedule activities, meals, work/study times
File workspace: Create, edit, list and download files via natural language
Web search: Automatic or on-demand search with headless browser fallback for JS-rendered e-commerce sites
Direct website access: Visit and analyze any website by name — the agent can enter sites and extract their content
Anti-hallucination: Post-search validation ensures responses cite sources and don't invent facts
Vision: Image analysis with configurable vision models
Voice: Voice message transcription and response
Proactive messaging: Scheduled automatic messages based on daily routine
Multi-provider AI: OpenRouter, StepFun, QwenCloud, and llama.cpp (local)
System auto-improvement: AI-driven suggestions to evolve the agent behavior

Project Structure

app/
├── psagentai_agent.py          # Main agent code (~5000 lines)
├── iniciar.sh                  # Setup and run script
├── requirements.txt            # Python dependencies
├── .env                        # Local settings (do not commit)
├── user_profile.json           # User profile (auto-created)
├── agent_profile.json          # Agent profile (auto-created)
├── uploads_metadata.json       # Uploaded files metadata (auto-created)
├── config.json                 # Schedule configuration (auto-created)
├── system_improvements.json    # Auto-improvement history (auto-created)
├── contexts/                   # Conversation history by date
│   └── YYYY-MM-DD.json
├── workspace/                  # Created and edited files
│   ├── projects/
│   └── web_cache/              # Cached webpage content (auto-created)
├── README.md
├── DEPLOY.md
├── RULES.md
└── LICENSE

Prerequisites

Python 3.9+
Telegram account with a bot created via @BotFather
At least one supported AI API key (OpenRouter, StepFun, or QwenCloud)

Configuration

Copy .env from the example or create it manually:

cp .env.example .env   # if .env.example exists
nano .env

Required variables:

Variable	Required	Description
`TELEGRAM_BOT_TOKEN`	Yes	Token from @BotFather
`TELEGRAM_CHAT_ID`	Yes	Your Telegram chat ID
`AI_PROVIDER`	Yes	`openrouter`, `stepfun`, `qwencloud` or `llamacpp`
`DEFAULT_MODEL`	Yes	Model identifier for the chosen provider
`OPENROUTER_API_KEY`	Conditional	Required if using OpenRouter
`STEPFUN_API_KEY`	Conditional	Required if using StepFun
`QWENCLOUD_API_KEY`	Conditional	Required if using QwenCloud

Optional tuning:

Variable	Default	Description
`MIN_INTERVAL_MINUTES`	`3`	Minimum minutes between proactive messages
`MAX_INTERVAL_MINUTES`	`30`	Maximum minutes between proactive messages
`MIN_MESSAGE_LINES`	`3`	Minimum lines per agent response
`MAX_HISTORY_LENGTH`	`50`	Max messages kept in context
`UPLOAD_CONTEXT_MAX_CHARS`	`8000`	Max chars from uploads sent to AI (`0` = unlimited)
`WEB_SEARCH_ENABLED`	`true`	Enable automatic web search
`WEB_SEARCH_MAX_RESULTS`	`5`	Max search results returned
`WEB_SEARCH_SCRAPE_ENABLED`	`true`	Fetch page content for search results (uses headless browser fallback)
`WEB_SEARCH_SCRAPE_CACHE_TTL`	`3600`	Cache TTL for scraped pages in seconds
`WEB_SEARCH_SCRAPE_MAX_CHARS`	`15000`	Max characters per scraped page
`VISION_MODEL`	`meta-llama/llama-4-maverick-17b-128b-instruct`	Model for image analysis
`VISION_PROVIDER`	auto	Provider for vision model
`AUTO_ENRICH_EVERY`	`2`	Update profiles every N messages (`0` = disabled)
`AUTO_IMPROVE_EVERY`	`20`	Run auto-improvement every N messages (`0` = disabled)

Installation

cd app
chmod +x iniciar.sh
./iniciar.sh

The setup script will:

Create a Python virtual environment (venv/)
Upgrade pip
Install dependencies from requirements.txt
Validate .env configuration
Start the agent

Running

# From the app directory:
python3 psagentai_agent.py

# Or use the setup script:
./iniciar.sh

Available Commands

Core

/start — Starts or restarts the conversation and onboarding if needed
/help — Displays quick command reference
/manual — Full user manual with examples and tips
/about — System information, version, author and license

Profile

/profile — Displays your profile and agent summary
/editprofile — Edit your profile fields interactively
/addtouserprofile <text> — Add information to your profile
/agentprofile — Displays the full agent profile
/editagentprofile — Edit agent profile fields interactively
/configagentprofile — Configure agent profile interactively (name, personality, traits, notes)
/addtoagentprofile <text> — Add a note/characteristic to the agent profile
/onboarding — Re-run your profile onboarding

AI Configuration

/viewai — Shows current AI provider and model
/configai — Configure AI provider and model interactively with buttons
/viewvision — Shows current vision provider and model
/configvision — Configure vision model interactively with buttons
/updatesystem — Force analysis and application of auto improvements

Files and Documents

/uploadfile — Instructions for sending files (.pdf, .txt, .docx, .png, .jpg)
/listfiles — List all uploaded and created files
/download <name> — Download a workspace file by name

You can also send files directly in the chat. The agent will read text-based files and images automatically.

Workspace Editing

You can ask the agent to create or edit files in workspace/:

Create:

create a python script to calculate fibonacci
develop a web project with html css and js
generate a document about home automation

Edit:

edit the file test.txt and add line 4
modify the file hello.py to print hello world
in the file test.txt replace Line 2 with Line 2 edited

Daily Routine and Schedule

/schedule — Set days and times for automatic messages
/viewschedule — View current schedule
/dailyroutine — Manage your daily routine (wake up, meals, work/study, sleep)
/viewdailyroutine — View current daily routine
/addactivity — Add a new activity to your routine
/editactivity — Edit an existing activity
/deleteactivity — Delete an activity

Management

/newconfig — Reset everything and reconfigure from scratch
/reset — Reset only user and agent profiles
/clear — Remove all data (profiles, contexts, chat_id)
/removetopic <topic> — Remove all content related to a topic from the system
/cancel — Cancel an ongoing operation

Utilities

/debug — Shows system debug information
/reload — Reload .env settings without restarting
/timezone — Shows the server timezone (read-only)

Natural Language Profile Updates

During conversation, you can update profiles using phrases:

User profile:

Include this in my profile: ...
Note in my profile: ...
Add to my profile: ...
Save in my profile: ...

Agent profile:

Include this in the agent profile: ...
Note in the agent profile: ...

How It Works

Onboarding: When you first start, the agent asks questions to build your profile (name, age, gender, location, interests, personality, etc.)
Context: Every message is saved to a daily context file (contexts/YYYY-MM-DD.json)
Profiles: User and agent profiles are persisted as JSON and enriched automatically based on conversations
AI Calls: The agent uses the configured provider/model to generate responses with full context
Proactive Messages: Based on your schedule and routine, the agent may initiate conversations
Web Search: When enabled, the agent searches the web for questions requiring current information. If HTTP scraping fails (JS-rendered sites), it falls back to a headless Chromium browser via Playwright.
Direct Website Access: You can ask the agent to visit any website by name or URL. It fetches the page content using a headless browser (or HTTP scrape for static sites) and extracts the readable text.
Vision: Images are analyzed using the configured vision model
Auto-improvement: The system periodically analyzes conversations and suggests improvements

Web Search & Website Access

How Web Search Works

When you ask a question that requires current information, the agent:

Runs a DuckDuckGo search to find relevant results
Fetches page content from each result using HTTP scraping + BeautifulSoup
For JS-rendered sites (e-commerce, SPAs), automatically falls back to a headless Chromium browser via Playwright
Extracts readable text, strips scripts/styles, and passes it to the AI for grounded responses
Validates the response against source data to prevent hallucination

The system caches scraped pages for 1 hour (configurable via WEB_SEARCH_SCRAPE_CACHE_TTL).

Direct Website Visit

You can ask the agent to enter or analyze any website:

Entre no site syspanel.com.br e me diga do que se trata
Analisa https://www.google.com para mim
Visite este site e verifique os preços

The agent detects URLs + action keywords (entra, acesse, analise, visite, pesquise, etc.) and automatically scrapes the page. It uses:

Headless Chromium (Playwright) — best for JS-rendered/spa sites like KaBuM, MercadoLivre, Buscape
HTTP scraping (BeautifulSoup) — fallback for static sites
Cache — previously fetched pages are reused from workspace/web_cache/

Supported websites: Most informational sites, blogs, news portals, e-commerce product listing pages. Sites with heavy bot protection (Cloudflare CAPTCHA) may not work.

Example Use Cases

Price comparison: Encontre os SSD de 120GB mais baratos e me informe detalhes e link de compra → agent searches and fetches real prices from KaBuM/Zoom/Buscape
Website analysis: Entre no site syspanel.com.br e me diga do que se trata → agent visits and summarizes the site
Current events: Pesquisa na internet as notícias sobre tecnologia → agent searches and reads article content

File Upload and Analysis

Supported formats:

Documents: .pdf, .txt, .docx
Images: .png, .jpg, .jpeg

When you upload a file:

It's saved to workspace/ or uploads/
Text is extracted and stored in uploads_metadata.json
Images are analyzed automatically
You can ask questions about the file content

Workspace Editing

The agent can create and edit files in workspace/ using AI. Files are organized in subdirectories based on the request type.

To edit an existing file:

Use /listfiles to see available files
Use /download <name> to download a file
Ask the agent to edit by name or partial name

Conversation Context

Contexts are stored in contexts/YYYY-MM-DD.json
Old messages are automatically cleaned when limits are exceeded
The agent references recent context to maintain coherent conversations

Scheduling

The agent sends proactive messages only within the configured schedule:

Configure days of the week and time range with /schedule
Messages are sent at random intervals within the configured window
The agent always uses server time

Security Notes

Never commit .env to version control
Restrict .env permissions: chmod 600 .env
Sensitive data (emails, phones) is preserved but not exposed in logs
File paths are validated to prevent traversal attacks

Backups

Regularly back up these files:

user_profile.json
agent_profile.json
system_improvements.json
uploads_metadata.json
config.json
contexts/ folder
workspace/ folder

Example backup:

tar czf /root/backups/psagentai-$(date +%F).tar.gz -C /opt/psagentai/app user_profile.json agent_profile.json system_improvements.json uploads_metadata.json config.json contexts workspace

Troubleshooting

Bot not responding: Ensure /start has been sent once in the Telegram chat
AI errors: Check API keys and provider configuration with /viewai
Voice not working: Ensure ffmpeg is installed
Image analysis not working: Check vision configuration with /viewvision
Web search results empty: Check that web scraping works — e-commerce sites (KaBuM, MercadoLivre) require Playwright + Chromium. Reinstall with ./iniciar.sh. Sites with CAPTCHA protection may fail regardless.
Website visit fails: Some sites block headless browsers or show CAPTCHA. Try simpler informational sites first. The agent shows [URL_VISIT] failed to fetch url=... in console output if fetching fails.

Dependencies

Python packages

All listed in requirements.txt:

python-telegram-bot — Telegram bot framework
requests + beautifulsoup4 + lxml — HTTP scraping for static pages
playwright — Headless Chromium for JS-rendered/spa sites (e-commerce, dynamic content)
openai — OpenAI-compatible AI API client
PyMuPDF, python-docx, Pillow, SpeechRecognition, pydub — File processing

System packages

ffmpeg — Voice message processing
chromium-browser — Installed automatically by Playwright (playwright install chromium)

Run ./iniciar.sh to set up all dependencies including browser installation.

Development

See RULES.md for development standards, code conventions, and contribution guidelines.

License

Proprietary for Syspanel.com.br. See LICENSE file.