Telegram Search
Effortlessly export, back up, and fuzzy search your Telegram chat history, with vector semantic search and AI summaries.
Evidence shows CLI design follows least privilege: only requests selected chat categories, not contacts or file export permissions; sync requires explicit --takeout and user consent; stdout only outputs JSON, logs to stderr; export excludes media binaries, session, vectors, or keys. But no code-level verification, dependency security relies on CI and provenance checks, no dependency audit results. External effects: sync writes to local PGlite, but no rollback mechanism. Source attribution only via GitHub repo and license, publisher unverified.
README and CLI docs consistent, package.json scripts match documented commands, but no specific failure message examples. Dependency availability: uses pnpm and lockfile, CI has build tests, but no dependency availability guarantee.
Targets individual users and Agent scenarios, provides CLI and Docker deployment, supports multiple databases and storage. Capability boundaries clear: only export and search, no AI summarization unless configured. Trigger precision: CLI commands clear, but no automated trigger mechanism. Environment fit good, supports multiple deployment methods.
Information architecture clear, README provides quick start and detailed docs links. Install notes detailed, including Docker Compose and Docker Image. Naming stable, version number clear. Examples and FAQ provided, but known limitations not explicitly listed. License AGPL-3.0, full text present. Version changelog not provided, maintenance responsibility unclear.
Output JSON and JSONL, easy for program processing. Marginal value high, solves Telegram Chinese search pain point. Cost-benefit reasonable, open source free, but requires self-deployment.
Feature claims in README lack test evidence, CI has tests but no coverage report. Cross-source corroboration limited, relies on repo itself. Fact-inference separation unclear, some features are roadmap not implemented.
- Publisher identity unverified, supply chain risk should be assessed.
- No dependency audit or vulnerability scan results provided, check dependency security before deployment.
- Sync writes to local database, but no rollback mechanism, backup before operation.
- Some advanced features (e.g., AI summarization) require user-configured API, be aware of data privacy.
What does this agent do, and when should you use it?
Telegram Search is an open-source tool for exporting, backing up, and searching Telegram chat histories. It offers a web interface, a Telegram bot, and a local-first CLI (Agent mode). Messages are automatically tokenized and vector-embedded during export, enabling multilingual fuzzy matching and image semantic search. Deployment options include Docker Compose or pure browser mode. The project also provides RAG-based Q&A, unread message summaries, and bot-driven search.
Telegram Search fetches user-authorized chat history via the Telegram API, persists messages to PGlite or PostgreSQL, and generates vector embeddings and token indexes for each message. The web interface (default port 3333) allows searching, browsing, and exporting messages. The CLI tool supports commands like configure, login, chats list, sync, and export, outputting JSON. Additionally, a Telegram bot enables search and deep-link navigation. AI embeddings enable image semantic search.
- Users who need to find historical information in Telegram chats but find native search lacking for Chinese or other languages.
- Individuals or teams needing to back up Telegram chats and export date-filtered JSONL files.
- Users who want to converse with an AI based on their chat history to get RAG-based answers.
- Active users who want a one-click summary of unread messages to quickly catch up on group or channel activity.
- Developers who want to integrate Telegram messages with vector databases for knowledge graph building or further analysis.
What are this agent's strengths and limitations?
- Supports PGlite and PostgreSQL, offering flexible data storage options.
- Built-in vector embeddings and fuzzy search provide accurate multilingual retrieval.
- Three interaction modes: web UI, CLI, and Telegram bot.
- Image semantic search enables text-to-image queries.
- AI features include unread message summaries and RAG-based Q&A.
- Requires users to supply Telegram API ID and Hash, involving third-party credential setup.
- Depends on external AI embedding models and LLM APIs, incurring potential costs and privacy concerns.
- Deployment requires Docker or Node.js, posing a technical barrier.
- CLI sync operations are strictly gated by user authorization, adding complexity.
- Media storage depends on MinIO, increasing infrastructure management overhead.
How do you install or deploy this agent?
- Clone the repo:
git clone https://github.com/groupultra/telegram-search.git; 2. Install dependencies:pnpm install; 3. Copy env:cp .env.example .env; 4. Use Docker Compose: download docker-compose.yml, .env.example, and init.sql, then rundocker compose -f docker-compose.yml up -d. Or use Docker image:docker run -d --name telegram-search -p 3333:3333 ghcr.io/groupultra/telegram-search:latest. For development, runpnpm run dev(browser-only) orpnpm run server:devandpnpm run web:dev(server mode).
How do you use this agent?
- Access the web UI (e.g., http://localhost:3333) and log in with your Telegram API ID and Hash. 2. Authorize and start syncing messages. 3. Use the search bar for keyword or semantic vector search. 4. For CLI, first build the packages:
pnpm run build:packages && pnpm -F @tg-search/cli build. Then configure a profile:pnpm cli --profile work profile configure --apiId 123456 --apiHash abcdef, log in:pnpm cli --profile work auth login, list chats, sync with explicit takeout, and export data.