AI Characters Chat 🤖🎭

The Lightweight AI Roleplay and Agents Platform - No Bloat, All Power

---

"A solid move against the bloat. Repo looks clean—great stack for quick setups." — Grok (xAI)

🎯 Why AI Characters Chat?

The Problem: Most AI tools require 2GB Docker images, complex configurations, and 50+ setup steps.

Our Solution: A lightning-fast, self-hosted platform that gets you roleplaying in under 5 minutes.

See Quick Start section below for detailed installation instructions.

🚀 Powerful Features

🧠 Advanced Memory System (RAG)

• Long-term Vector Memory - Powered by sqlite-vec for storing and retrieving facts
• Semantic Search - AI retrieves relevant memories based on conversation context
• Smart Fact Extraction - Automatically extracts key information before cleaning history
• Explicit Commands - Manually save facts using "Remember: [fact]" or "Запомни: [факт]"
• Infinite Context - Never truly "forgets" important details, even after history cleanup

💬 Smart Chat System

• Real-time Streaming - Watch AI responses appear word by word with SSE
• Multi-User Support - Each user gets isolated chat histories
• Smart Context Management - Auto-summarization when history gets long
• Vision Support - Upload images for AI to analyze

🎭 Character Management

• Visual Dashboard - No JSON editing required
• Full Customization - Personality, scenario, temperature, tokens, tools, Reasoning
• Avatar Support - Custom character images
• Quick Switching - Jump between characters instantly

🎨 AI Image Generation

• FLUX Model - High-quality image generation via Together AI
• Aspect Ratios - Perfect for any use case
• Advanced Controls - Steps, guidance scale, reference images
• Local Storage - All images saved on your server

🛠️ Agent Tools

• File Operations - AI can create and read text files
• Image Generation - Generate images on demand
• Sandbox Security - All operations isolated in safe environment
• Toggle Control - Enable/disable tools per character

---

🏗️ Clean Architecture

Backend Stack

🚀 Fastify 5 (TypeScript)    → 2x faster than Express
💾 SQLite + sqlite-vec       → Zero-config vector database
🧠 RAG Architecture          → Long-term memory retrieval
🔐 Session Auth              → Simple, secure authentication
📡 SSE Streaming             → Real-time responses
🎨 Sharp                     → Fast image processing

Frontend Stack

⚡ Alpine.js 3               → Lightweight reactivity (<10KB)
🎨 Bootstrap 5               → Professional UI components
📝 Marked + Highlight.js     → Beautiful markdown rendering
🛡️ DOMPurify                → XSS protection

AI Services

🤖 OpenRouter API           → Access to all major AI models & Embeddings
🎨 Together AI               → FLUX image generation

---

🚀 Quick Start

1. Install Dependencies

npm install

2. Configure Environment

cp .env.example .env
# Edit .env with your API keys

3. Setup Database

npm run db:reset    # Create fresh database
npm run db:seed     # Add admin user + sample characters

4. Launch

# Development (hot-reload)
npm run dev

# Production
npm run build && npm run start

🎉 Visit: http://localhost:3000

---

⚙️ Configuration

Required Variables

# Security
JWT_SECRET=your_jwt_secret_at_least_32_chars_long
NODE_ENV=development # or production


# Server
PORT=3000 # Default port
HOST=0.0.0.0 # Default host

# AI Chat (OpenRouter)
API_KEY=your_openrouter_api_key
API_URL=https://openrouter.ai/api/v1/chat/completions
AI_DEFAULT_MODEL=AI Model Name
AI_EMBEDDING_MODEL=AI Embedding Model Name

Optional Variables

Debugging

LOGGING_DEBUG=true DEBUG_REQUESTS=true AI_DEBUG_LOGS=true

# Image Generation Providers
# Provider 1: Together AI
TOGETHER_IMAGE_API_URL=https://api.together.xyz/v1/images/generations
TOGETHER_IMAGE_MODEL=black-forest-labs/FLUX.2-dev

# Provider 2: XAI
XAI_API_KEY=your_xai_api_key



# Telegram Bot Integration
TELEGRAM_BOT_TOKEN=
TELEGRAM_WEBHOOK_URL=
TELEGRAM_WEBHOOK_SECRET=
# Optional: Private mode ids (comma-separated) - default empty (public)
TELEGRAM_ALLOWED_USERS=
# Optional: Admin users ids (comma-separated) - default empty (no admin)
TELEGRAM_ADMIN_USERS=
# Optional: Features (disabled by default for security)
TELEGRAM_ENABLE_IMAGES=false
TELEGRAM_ENABLE_VOICE=false
# Optional: Character settings
TELEGRAM_DEFAULT_CHARACTER_ID=1
# Optional: Rate limiting
TELEGRAM_RATE_LIMIT_PER_USER=30
TELEGRAM_RATE_LIMIT_WINDOW=60

# Telegram Channel ID (optional)
TELEGRAM_CHANNEL=

---

🔐 Security Features

• Session-based Authentication - Simple, secure sessions
• Password Hashing - bcrypt with 10 rounds
• XSS Protection - DOMPurify sanitization
• Sandboxed File Operations - AI tools restricted to safe directory
• CSRF Protection - Built-in session security

---

🎨 UI Features

• Cyberpunk Theme - Modern, eye-catching design
• Responsive Layout - Works on all devices
• Real-time Updates - No page refreshes needed
• Markdown Support - Rich text formatting
• Code Highlighting - Syntax highlighting for all languages
• Image Previews - Inline image display

---

🤖 AI Capabilities

Supported Models

• Grok (xAI) - Fast, conversational
• Claude (Anthropic) - Advanced reasoning
• GPT-4 (OpenAI) - Versatile and powerful
• Llama (Meta) - Open-source excellence
• And many more via OpenRouter

Agent Tools

• File Creation - AI can write text files
• File Reading - AI can read existing files
• Image Generation - Create images on demand
• Context Awareness - Smart conversation management

---

📱 Pages & Navigation

Route	Description	Features
/	Login & Register	Session-based authentication
/chat	Main Chat Interface	Real-time SSE streaming, image uploads
/characters	Character Dashboard	Full CRUD management, avatars
/image-gen	Image Generator	FLUX model, aspect ratios, controls

---

📱 Telegram Bot Integration

Chat with AI Characters on Telegram

AI Character Chat includes a full-featured Telegram bot that allows users to interact with AI characters directly through Telegram.

Key Features

• Multi-character Support - Switch between different AI personalities
• Long-term Memory - AI remembers important facts across conversations
• Command System - Bot commands for character management
• Real-time Processing - Instant responses via webhooks
• Security - Whitelist support and admin controls

Available Commands

/start     - Welcome message and getting started
/help      - Show help information
/characters - List all available AI characters
/character [name] - Select specific character
/reset     - Clear conversation history
/post [channel] message - Post message to channel (admin only)
/status    - Show current character and status
/memory    - Display memory system information

Setup Instructions

1. Create Telegram Bot

   • Talk to @BotFather on Telegram
   • Create a new bot and save the token

2. Configure Environment

   • Refer to the Configuration section for setup instructions
   • Add the following variables to your .env file:

     TELEGRAM_BOT_TOKEN=your_bot_token_here
     TELEGRAM_WEBHOOK_URL=https://your-domain.com/webhook/telegram
     TELEGRAM_WEBHOOK_SECRET=your_webhook_secret

   • Optional: Restrict access to specific users

     TELEGRAM_ALLOWED_USERS=123456789,987654321

3. Start Server

   npm run dev
   # Telegram adapter auto-initializes when configured

API Endpoints

• POST /webhook/telegram - Telegram webhook endpoint
• GET /webhook/telegram/health - Health check status
• POST /webhook/telegram/set - Set webhook URL (admin)
• POST /webhook/telegram/send - Send test message (admin)

Detailed Setup

For complete Telegram bot setup instructions, troubleshooting, and advanced configuration, see: TELEGRAM_SETUP.md

---

Telegram Channel Posting

Post Messages to Channels and Groups

AI Character Chat allows AI characters and admins to post messages directly to Telegram channels and groups.

Key Features

• AI-Generated Posts - AI characters can create and post content to channels
• Admin Control - Only admins can use the /post command manually
• Channel Restrictions - Configure allowed channels for security
• HTML Formatting - Support for rich text formatting in posts
• Default Channel - Set a default channel for quick posting

AI Tool Integration

The post_to_telegram_channel tool is available to AI characters when enabled:

// AI can automatically post updates, announcements, or content
await post_to_telegram_channel({
  message: "Hello everyone! Here's today's update... <b>Important news</b>",
  channel: "@mychannel" // optional, uses default if not specified
});

Admin Commands

/post @channelname Hello everyone! - Post to specific channel
/post Hello everyone! - Post to default channel
/post @channelname <b>Bold text</b> and <i>italic</i> - HTML formatting

Configuration

Add these variables to your .env file:

# Admin users who can use /post command
TELEGRAM_ADMIN_USERS=123456789,987654321

# Allowed channels (optional - restrict posting to specific channels)
TELEGRAM_ALLOWED_CHANNELS=@mychannel,@anotherchannel

# Default channel for quick posting
TELEGRAM_DEFAULT_CHANNEL=@mychannel

Setup Requirements

1. Bot Permissions

   • Add bot as administrator to target channels/groups
   • Enable "Post Messages" permission
   • For channels: bot must be admin with post rights
   • For groups: bot needs "Can post messages" permission

2. Channel Identifiers

   • Use @channelname for public channels
   • Use chat ID (numeric) for private groups/channels
   • Get chat ID by adding bot to group and using /start

3. Security Best Practices

   • Always restrict admin users with TELEGRAM_ADMIN_USERS
   • Use TELEGRAM_ALLOWED_CHANNELS to limit posting destinations
   • Set a default channel to prevent accidental posts

---

🧠 Technical Deep Dive

AI Chat Engine

// Memory Architecture
User Message → Vector Search (sqlite-vec) → Relevant Facts → System Prompt Injection
Context Builder → Fact Extraction → Vector Storage → History Cleanup

Image Generation Pipeline

User Prompt → Together AI → FLUX Model → Image Download → Local Storage
Aspect Ratio → Pixel Optimization → Sharp Processing → Static Serving

Database Schema

users        → Authentication & profiles
characters   → AI personalities & settings
messages     → Chat history with metadata

---

🎯 Use Cases

Perfect For:

• Roleplaying Enthusiasts - Create and manage AI characters
• Writers & Storytellers - Develop characters and dialogue
• Developers - AI-powered coding assistants
• Educators - Interactive teaching characters
• Privacy-Conscious Users - 100% local control

Not For:

• Mobile-Only Users - Requires self-hosting
• No-Tech Users - Basic setup required
• Enterprise Scale - Designed for small teams/personal use

---

🛠️ Development

Tech Stack Details

• Backend: Fastify 5 + TypeScript + SQLite
• Frontend: Alpine.js 3 + Bootstrap 5 + Vanilla JS
• AI: OpenRouter + Together AI
• Images: Sharp + FLUX
• Auth: Session-based + bcrypt

Key Architectural Decisions

• SQLite over PostgreSQL - Zero config, perfect for self-hosting
• Sessions over JWT - Simpler, more secure for this use case
• Alpine.js over React - Lightweight, no build step needed
• Fastify over Express - 2x performance, better TypeScript support

---

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Make your changes
3. Test thoroughly: npm run test
4. Submit a pull request

Development Guidelines

• Follow existing code style
• Add TypeScript types for new features
• Update documentation
• Test with multiple AI models

---

⚡ Why Choose AI Character Chat?

Feature	AI Character Chat	SillyTavern	Character.AI
Setup Time	5 minutes	30+ minutes	Instant (cloud)
Installation	3 commands	Docker + config	Web only
Resource Usage	~100MB RAM	2GB+ Docker	N/A
Local Control	✅ Full control	✅ Full control	❌ Cloud only
Customization	✅ Full source	✅ Full source	❌ Limited
Privacy	✅ 100% private	✅ 100% private	❌ Data collected
Startup Time	~2 seconds	30+ seconds (Docker)
Memory Usage	~100MB	2GB+ (Docker)
Disk Space	~50MB	500MB+
Response Latency	<500ms	1000ms+
Setup Complexity	3 commands	Docker + config

---

� License

MIT License - feel free to use this project for personal or commercial purposes.

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

---

⭐ Star this repo if it helped you!

Made with ❤️ by AI Norayr Petrosyan Developed with AI control and Architecture by Norayr Petrosyan

---

Built with a touch of sarcasm and faith in a digital future.

#AI #aichat #aiagents #airoleplay #GrokAI #OpenRouter #Telegram #Automation #selfhosted #opensource