Telegram Search
Effortlessly export, back up, and fuzzy search your Telegram chat history, with vector semantic search and AI summaries.
- Source repo
- groupultra/telegram-search
- Stars
- ★ 4.1k
- Last updated
- 1d ago
- License
- AGPL-3.0
- Primary language
- TypeScript
- FA score
- 58/100 · Major gaps
At a glance
- How it runs
- Works with
- Platform-specific
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Users who need to find historical information in Telegram chats but find native search lacking for Chinese or other languages.
- Not a fit if
- Users unwilling to register a Telegram API ID and Hash
- Individuals avoiding Docker, database, or MinIO infrastructure
- Source review
- 58/100 · Major gaps
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.
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.
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 does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Telegram Search This agent | 58 · Major gaps | Self-hosted serviceFree + model costs | ★ 4.1k | 1d ago | TypeScript | — |
| Teable - AI Spreadsheet for Business | 53 · Major gaps | Self-hosted serviceFreemium | ★ 22k | 3d ago | TypeScript | — |
| CocoIndex | 49 · Major gaps | Library / SDKFree + model costs | ★ 12k | 1d ago | Rust | — |
| Mnemosyne | 59 · Major gaps | CLIFree | ★ 3.5k | today | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
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.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
What's Changed * chore(homebrew): update CLI to v1.5.0 by @luoling8192 in https://github.com/groupultra/telegram-search/pull/692 * feat(server): add scoped remote access control by @luoling8192 in https://github.com/groupultra/telegram-search/pull/681 Full Changelog: https://github.com/groupultra/telegram-search/compare/v1.5.0...v1.6.0View on GitHub ↗ -
Release notes excerpt
Add short-lived attachment URLs for consumers that cannot send an Authorization header, including image analysis tools. - tg-search media url exchanges authenticated access to one attachment for an opaque URL that expires after five minutes. Anonymous GET/HEAD returns the original bytes; explicit local and Telegram sources are supported. - Tickets bind the account, attachment identity, size and byte budget. Bearer rotation invalidates issued links. Download capacity, deadlines and safe error responses bound resource use. …View on GitHub ↗ -
Release notes excerpt
Distribution status CLI and Homebrew v1.4.0 are published and independently verified. The Docker v1.4.0 image is not published: the [multi-architecture workflow](https://github.com/groupultra/telegram-search/actions/runs/38889264635) reached its 15-minute limit during ARM64 Web compilation. This remains tracked in [#682](https://github.com/groupultra/telegram-search/issues/682). The Web deployment workflow succeeded; anonymous access from the verification environment returned HTTP 403, so authenticated business flows remain unverified. Upgrade notes …View on GitHub ↗