---

[Try it Now] [简体中文] [日本語]

Easily find and export your Telegram messages with powerful semantic search, supporting all languages and unsegmented sentences.

Make message retrieval fast, accurate, and privacy-friendly — self-host or try online.

💖 Sponsors

✅ What Can It Do

📦 Export & Backup

• Export to PostgreSQL or in-browser database (PGlite)
• Universal export format for easy import to any database
• One-click export to CSV / JSON

🔍 Search Your Chat History

• Keyword search: multi-language support (Chinese, English, etc.)
• Natural language search: find messages like asking a question
• Smart filters: by contact/group, time range, with attachments, etc.

🔄 Sync & Storage

• Incremental sync: sync while using
• Storage options: server (PostgreSQL + pgvector) or browser-only mode (PGlite)
• Resume from breakpoint: auto-continue after failure

🧠 AI Capabilities (Planned)

• Ask AI about your chats: query current chat or selected range
• AI message summary: auto-extract key points, todos, conclusions
• AI-powered search: natural language queries with pinpointed results
• AI chat: converse with AI based on your chat context
• AI analysis: trends, sentiment, keywords, insights from links & files
• Local model support: local Embedding / inference (no cloud required)

🔗 Media & Links (Planned)

• Deep indexing for links & images: web summaries, image OCR/descriptions
• Attachment content extraction: PDFs, images, audio/video key frames & text

🌐 More Platforms (Planned)

• Multi-client support: Discord, etc.

🌐 Try it Now

We provide an online version where you can experience all features of Telegram Search without self-deployment.

Note

We promise not to collect any user privacy data, you can use it with confidence

Visit: https://search.lingogram.app

🚀 Quick Start

1-Minute Start with Docker

Important

The simplest way to get started — no configuration needed. All features work with sensible defaults.

docker run -d --name telegram-search \
  -p 3333:3333 \
  -v telegram-search-data:/app/data \
  ghcr.io/groupultra/telegram-search:latest

Then open http://localhost:3333 🎉

Advanced Setup (Optional)

🔧 Environment Variables

[!TIP] All environment variables are optional. Customize only if needed.

Variable	Description
TELEGRAM_API_ID	Telegram app ID from my.telegram.org
TELEGRAM_API_HASH	Telegram app hash
DATABASE_TYPE	postgres or pglite (default: pglite)
DATABASE_URL	PostgreSQL connection string (only when DATABASE_TYPE=postgres)
EMBEDDING_API_KEY	API key for OpenAI/Ollama
EMBEDDING_BASE_URL	Custom embedding API base URL
EMBEDDING_PROVIDER	openai or ollama
EMBEDDING_MODEL	Model name
EMBEDDING_DIMENSION	Embedding dimension (e.g. 1536, 1024, 768)
PROXY_URL	Proxy URL (e.g. socks5://user:pass@host:port)

Example with PostgreSQL & embeddings:

docker run -d --name telegram-search \
  -p 3333:3333 \
  -v telegram-search-data:/app/data \
  -e TELEGRAM_API_ID=611335 \
  -e TELEGRAM_API_HASH=d524b414d21f4d37f08684c1df41ac9c \
  -e DATABASE_TYPE=postgres \
  -e DATABASE_URL=postgresql://<postgres-host>:5432/postgres \
  -e EMBEDDING_API_KEY=sk-xxxx \
  -e EMBEDDING_BASE_URL=https://api.openai.com/v1 \
  ghcr.io/groupultra/telegram-search:latest

Proxy formats:

• SOCKS5: socks5://user:pass@host:port
• SOCKS4: socks4://user:pass@host:port
• HTTP: http://user:pass@host:port
• MTProxy: mtproxy://secret@host:port

📖 Full environment variable reference: docs/ENVIRONMENT.md

Start with Docker Compose

1. Clone repository.

2. Run docker compose to start all services including the database:

docker compose up -d

3. Access http://localhost:3333 to open the search interface.

💻 Development Guide

Caution

Development requires Node.js >= 22.18 and pnpm. Make sure you have them installed.

Browser-Only Mode

git clone https://github.com/groupultra/telegram-search.git
cd telegram-search
pnpm install
cp .env.example .env
pnpm run dev

Server Mode (with Backend)

git clone https://github.com/groupultra/telegram-search.git
cd telegram-search
pnpm install
cp config/config.example.yaml config/config.yaml

# Start database (Docker)
docker compose up -d pgvector

# Start backend & frontend
pnpm run server:dev  # Terminal 1
pnpm run web:dev     # Terminal 2

📖 More development details: CONTRIBUTING.md

🏗️ Architecture

This project is a monorepo with event-driven architecture:

• apps/web: Vue 3 frontend
• apps/server: WebSocket server
• packages/client: Client adapters & stores (Pinia)
• packages/core: Event bus (EventEmitter3), services, database models (Drizzle ORM)
• packages/common: Logger & utilities

Key Technologies:

• Event-driven with CoreContext (EventEmitter3)
• Real-time communication via WebSocket
• PostgreSQL + pgvector OR PGlite (in-browser)
• Message processing pipeline: Embedding, Jieba, Link, Media, User resolvers

📖 Full architecture details, event flow, and diagrams: CONTRIBUTING.md

❓ FAQ

Do you collect any user data?

No. All data stays on your machine or server. We never collect or upload user data.

Do I need API keys to use this?

No. The application works with default settings. API keys are optional:

• Telegram API keys: Default keys work but have rate limits. Get your own for better performance.
• Embedding API keys: Only needed for semantic/natural language search.

What's the difference between browser mode and server mode?

• Browser mode (PGlite): Runs entirely in your browser, no server needed. Good for personal use.
• Server mode (PostgreSQL): Full-featured with better performance, suitable for production deployment.

Can I use my own embedding model?

Yes! Set EMBEDDING_PROVIDER to ollama and point EMBEDDING_BASE_URL to your local Ollama instance. See docs/ENVIRONMENT.md for details.

How do I backup my data?

Your data is stored in:

• Docker volume: telegram-search-data (mounted to /app/data)
• Browser mode: Browser's IndexedDB

You can export messages to CSV/JSON anytime via the UI.

📚 Documentation

• English: README.md (you're here!)
• 简体中文: README_CN.md
• 日本語: README_JA.md
• Technical Architecture: CONTRIBUTING.md
• Environment Variables: docs/ENVIRONMENT.md
• Code of Conduct: CODE_OF_CONDUCT.md
• Security: SECURITY.md

🤝 Community

• Discord: Join our Discord
• Telegram: Join our Telegram group
• DeepWiki: View documentation

🚨 Warnings

Warning

We have not issued any virtual currency, please do not be deceived.

Caution

This software can only export your own chat records for search, please do not use it for illegal purposes.

🚀 Activity