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

Движок архива и умного поиска по истории Telegram-чатов

Сырые сообщения в JSONL · полнотекстовый поиск с русской морфологией · качалка с менеджером

Идея

Летопись — это не бот и не сервис, а CLI-инструмент, заточенный под то, чтобы LLM-агент (в первую очередь Claude Code) мог читать историю ваших Telegram-чатов и отвечать по ней на вопросы, как по обычной базе знаний.

Архив хранится как обычные файлы — .jsonl, по одному на чат и месяц, append-only. Поверх них строится индекс SQLite с полнотекстовым поиском (FTS5), который понимает русские словоформы: запрос «хостинг» находит сообщения со словом «хостингами». К поиску подключены расшифровки голосовых, имена файлов и текст опросов.

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

Движок и данные разделены. Этот репозиторий содержит только код — сами архивы чатов, config.toml, .env и сессия Telegram живут в отдельном приватном репозитории, который держит вас в контроле над тем, что публично, а что нет. Подробнее — в разделе «Устройство».

Related MCP server: telegram-user-mcp

✨ Возможности

🚀 Быстрый старт

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   # опционально: локальная транскрипция голосовых

Летопись — это только движок. Чтобы подключить его к конкретному архиву, создайте отдельный репозиторий с данными и положите туда обёртку ./tg:

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

Дальше всё запускается из корня репозитория с данными:

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

Движок сам находит корень с данными: при запуске tg ищет от текущей директории вверх папку, где рядом лежат config.toml и archive/ (либо это явно задаётся переменной окружения TG_ROOT).

🤖 Read-only MCP для ChatGPT

Letopis может работать как read-only MCP retrieval gateway для ChatGPT: сервер использует тот же data/index.db, что и обычный поиск, но отдаёт только пять безопасных retrieval-инструментов — обзор архива, поиск, агрегаты, выборку сообщений и локальный контекст. MCP-процесс не синхронизирует Telegram, не скачивает файлы и не меняет индекс.

Установка и запуск

Установите MCP SDK и тестовые зависимости в окружение движка:

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

Запуск через entrypoint:

.venv/bin/letopis-mcp

Альтернативная форма — .venv/bin/python -m tgarchive.mcp.server. По умолчанию сервер слушает http://127.0.0.1:8765/mcp и принимает только loopback-адреса. Для production задайте стабильный секрет курсоров и путь к индексу в окружении процесса, например:

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

Переменные окружения

Rate limit намеренно глобальный для одного процесса: в v1 нет OAuth и идентифицированных principals, поэтому это не per-user ACL. MCP читает эти переменные как конфигурацию процесса и не загружает .env автоматически.

Подключение к ChatGPT

Рекомендуемая схема не публикует Letopis в интернет напрямую:

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

Конкретные команды и шаги настройки Secure MCP Tunnel зависят от текущего OpenAI workspace и актуальной документации OpenAI. Уточните их на момент подключения; этот репозиторий не выдумывает непроверенную OAuth/tunnel-команду.

Безопасность deployment

MCP-процессу нужны только data/index.db и необходимые SQLite sidecar-файлы data/index.db-wal / data/index.db-shm. Ему не должны быть доступны .env, telegram.session*, archive/, media или manifest. Запускайте сервер под отдельным Unix-пользователем с минимальными правами, а синхронизацию и индексацию выполняйте отдельным процессом с нужными правами записи.

🗂 Устройство

репозиторий с данными/
├── 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 — источник истины. Файлы по месяцам, sync только дописывает новые сообщения, старые никогда не трогает.

• index.db — производный слой. Можно удалить и пересобрать (./tg index --rebuild) в любой момент без потери данных.

• manifest.json — менеджер. Переживает пересборку индекса; хранит, какие чаты/топики отслеживаются и какие типы медиа для них качать.

Такое разделение (движок в git, открыто · данные — отдельно, приватно) позволяет свободно развивать и делиться кодом, не рискуя утечкой переписки.

🧭 Команды

Поиск — основное для агента

Просмотрщики — ручной режим

Качалка и менеджер

Чат можно указывать как id, алиас из config.toml, часть названия, @username или ссылку t.me/.... Новые сообщения скачиваются со всеми реакциями, опросами и сервисными событиями.

🎙 Транскрипция голосовых

Провайдер задаётся в config.toml [transcription]:

👥 Несколько аккаунтов

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

tg login --account backup авторизует новую сессию. У download / sync / dialogs / meta есть флаг --account. Каждый чат в манифесте закреплён за своим аккаунтом.

🗺 Статус

Дальше: автосинк по расписанию, OCR картинок, Azure Speech-провайдер, экспорт выборок.

🔒 Безопасность

telegram.session и .env дают полный доступ к Telegram-аккаунту. Держите их в отдельном приватном репозитории с данными, не коммитьте в этот и никуда не публикуйте.

Сделано для того, чтобы агент помнил переписку лучше, чем вы сами.