📜 Летопись (Letopis)

Archive and smart search engine for Telegram chat history

Raw messages in JSONL · full-text search with Russian morphology · downloader with manager

Idea

Letopis is not a bot and not a service, but a CLI tool designed so that an LLM agent (primarily Claude Code) can read your Telegram chat history and answer questions from it, just like from a regular knowledge base.

The archive is stored as plain files — .jsonl, one per chat and month, append-only. An SQLite index with full-text search (FTS5) is built on top; it understands Russian word forms: the query «хостинг» finds messages containing the word «хостингами». Voice message transcripts, file names, and poll text are also connected to the search.

$ ./tg search переезд хостинг --chat devops --from 2025-06

Engine and data are separated. This repository contains only code — the chat archives themselves, config.toml, .env, and the Telegram session live in a separate private repository, which keeps you in control of what is public and what is not. More in the Structure section.

Related MCP server: telegram-user-mcp

✨ Features

🚀 Quick start

git clone https://github.com/Toligrim/letopis.git
cd letopis
python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/pip install faster-whisper   # опционально: локальная транскрипция голосовых

Letopis is just the engine. To connect it to a specific archive, create a separate data repository and put the ./tg wrapper there:

#!/bin/sh
exec "$HOME/projects/letopis/.venv/bin/tg" "$@"

Everything then runs from the root of the data repository:

chmod +x tg
./tg login              # авторизация Telegram-сессии (телефон / код / 2FA)
./tg download --chat mychat --media all
./tg index && ./tg meta
./tg search привет

The engine finds the data root itself: when started, tg looks upward from the current directory for a folder where config.toml and archive/ are located next to each other (or this is explicitly set via the TG_ROOT environment variable).

🤖 Read-only MCP for ChatGPT

Letopis can work as a read-only MCP retrieval gateway for ChatGPT: the server uses the same data/index.db as regular search, but only returns five safe retrieval tools — archive overview, search, aggregates, message lookup, and local context. The MCP process does not sync Telegram, download files, or modify the index.

Installation and launch

Install the MCP SDK and test dependencies into the engine environment:

.venv/bin/pip install -e ".[mcp,test]"

Launch via the entrypoint:

.venv/bin/letopis-mcp

Alternative form — .venv/bin/python -m tgarchive server. Wait, actually source says .venv/bin/python -m tgarchive.mcp.server? The prompt says: "— .venv/bin/python -m tgarchive.mcp.server." Wait check the source: "Альтернативная форма — .venv/bin/python -m tgarchive.mcp.server." Yes, keep tgarchive.mcp.server. So continue.

By default the server listens on http://127.0.0.1:8765/mcp and accepts only loopback events. For production, set a stable cursor secret and index path in the process environment, for example:

export LETOPIS_MCP_DB=/srv/letopis-data/data/index.db
export LETOPIS_MCP_CURSOR_SECRET='случайный-длинный-секрет'
.venv/bin/letopis-mcp

Environment variables

The rate limit is intentionally process-global: v1 has no OAuth and no identified principals, so this is not a per-user ACL. MCP reads these variables as process configuration and does not load .env automatically.

Connecting to ChatGPT

The recommended scheme does not publish Letopis directly to the internet:

ChatGPT ↔ OpenAI Secure MCP Tunnel ↔ tunnel-client на этом хосте
                                      ↔ 127.0.0.1:8765/mcp

Specific commands and setup steps for Secure MCP Tunnel depend on the current OpenAI workspace and current OpenAI documentation. Verify them at connection time; this repository does not make up an unverified OAuth/tunnel command.

Deployment security

The MCP process needs only data/index.db and the necessary SQLite sidecar files data/index.db-wal / data/index.db-shm. It should not have access to .env, telegram.session, archive/, media, or the manifest. Run the server as a separate Unix user with minimal rights, and perform sync and indexing as a separate process with the required write access.

🗂 Structure

репозиторий с данными/
├── config.toml              # настройки: аккаунты, транскрипция, веб-порт
├── .env                     # api_id / api_hash Telegram
├── telegram.session         # сессия аккаунта (и доп. сессии из [accounts])
├── tg -> letopis/.venv/bin/tg   # обёртка-энтрипоинт
├── data/
│   └── index.db             # SQLite + FTS5 — производный, пересобирается
└── archive/
    ├── manifest.json        # какие чаты отслеживаем, каким аккаунтом, какие медиа качаем
    └── <chat_id>/
        ├── 2025-06.jsonl    # сырые сообщения этого месяца — источник истины
        ├── 2025-07.jsonl
        ├── transcripts.jsonl   # расшифровки голосовых/кружков
        ├── media_index.jsonl   # реестр скачанных файлов
        └── media/               # сами файлы

• JSONL — the source of truth. Files by month; sync only appends new messages and never touches old ones.

• index.db — the derived layer. It can be deleted and rebuilt (./tg index --rebuild) at any time without data loss.

• manifest.json — the manager. It survives index rebuilds and keeps track of which chats/topics are tracked and which media types to download for them.

This split (engine in git, open; data separate and private) allows you to freely develop and share the code without risking a leak of your conversations.

🧭 Commands

Search — the main feature for agents

Viewers — manual mode

Downloader and manager

A chat can be specified by id, alias from config.toml, part of the title, @username, or a t.me/... link. New messages are downloaded with all reactions, polls, and service events.

🎙 Voice transcription

The provider is configured in config.toml [transcription]:

| Provider | Cost | Requirements | | --- | --- | | whisper-local | free, local | faster-whisper, small model by default | | telegram | free | Telegram Premium on the account | | openai | paid (Whisper API) | OPENAI_API_KEY in `.```

Downloader and manager

A chat can be specified as an id, an alias from config.toml, part of the name, @username, or a t.me/... link. New messages are downloaded with all reactions, polls, and service events.

🎙 Voice transcription

The provider is set in config.toml [transcription]:

👥 Multiple accounts

[accounts]
default = "telegram.session"
backup  = "sessions/backup.session"

tg login --account backup authorizes a new session. The download / sync / dialogs / meta commands have the --account flag. Each chat in the manifest is tied to its own account.

🗺 Status

Next: scheduled auto-sync, image OCR, Azure Speech provider, data export.

🔒 Security

telegram.session and .env give full access to your Telegram account. Keep them in a private repository with the data, do not commit them to this repository, and never publish them anywhere.

Made so the agent remembers conversations better than you do.