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

Идея

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

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

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

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

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

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

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-аккаунту.Держите их в отдельном приватном репозитории с данными, не коммитьте в этоти никуда не публикуйте.