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

Engine für das Archiv und die intelligente Suche in Telegram-Chat-Verläufen

Rohe Nachrichten in JSONL · Volltextsuche mit russischer Morphologie · Downloader mit Manager

Idee

Летопись ist kein Bot und kein Dienst, sondern ein CLI-Werkzeug, das genau dafür gebaut ist, dass ein LLM-Agent (vor allem Claude Code) den Verlauf Ihrer Telegram-Chats lesen und daraus Fragen beantworten kann – wie aus einer normalen Wissensbasis.

Das Archiv wird als normale Dateien gespeichert – .jsonl, eine Datei pro Chat und Monat, append-only. Darüber wird ein SQLite-Index mit Volltextsuche (FTS5) aufgebaut, der russische Wortformen versteht: Die Abfrage „хостинг“ findet auch Nachrichten mit dem Wort „хостингами“. In die Suche fließen außerdem Sprachnachrichten-Transkripte, Dateinamen und der Text von Umfragen ein.

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

Engine und Daten sind getrennt. Dieses Repository enthält nur den Code – die Chat-Archive selbst, config.toml, .env und die Telegram-Session liegen in einem separaten privaten Repository. Das behält die Kontrolle darüber, was öffentlich ist und was nicht. Details im Abschnitt „Struktur“.

Related MCP server: telegram-user-mcp

✨ Funktionen

🚀 Schnellstart

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

Летопись ist nur die Engine. Um einen konkreten Chatter anzuschließen, legen Sie ein eigenes Daten-Repository an und legen Sie dort den Wrapper ./tg ab:

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

Danach läuft alles aus dem Wurzelverzeichnis des Daten-Repository:

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

Die Engine findet das Daten-Wurzelverzeichnis selbst: Beim Start sucht tg von dem aktuellen Verzeichnis aus nach oben einer Dokumentation, in der config.toml und archive/ seitlich liegen (oder das wird explicity über die Umgebungsvariable TG_ROOT gesetzt).

🤖 Read-only MCP für ChatGPT

Letopis kann als Read-only-MCP-Retrieval-Gateway für ChatGPT ausgeführt werden: Der Server verwendet die gleiche data/index.db wie die normale Search, stellt aber nur fünf sichere Retrieval-Werkzeuge bereit – Archivübersicht, Suche, Aggregates, Message-Auswahl und lokalen Context. Der MCP-Prozess synchronisiert Telegram nicht, lädt keine Dateien herunter und verändert den Index nicht.

Installation und Start

Install the MCP-SDK und die Test-Abhängigkeiten in die Umgebung der Engine:

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

Start über den Entrypoint:

.venv/bin/letopis-mcp

Alternative Forme — .venv/bin/python -m tgarchive.mcp.server. Standardmäßig horcht der Server auf http://127.0.0.1:8765/mcp und akzeptiert nur Loopback-Adressen. Gast für den Produktion mit Betrieb, setzen Sie ein stabiles Cursor-Secretschloss secret und ihn den Index-Pfad in der Prozess-Umgebung an, z.B.:

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

Umgebungsvariablen

Rate Limit ist absichtlich pro Prozess global gehalten: in v1 gibt es kein OAuth und keine identifizierten Principals – es ist also keine Per-User-ACL. Der MCP liest diese Variablen als Prozesskonfiguration und lädt .env nicht automatisch.

Anbindung an ChatGPT

Empfohlenes Schema veröffentlicht Letopis nicht direkt ins Internet:

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

Die konkreten Befehle und Schritte für den Secure MCP Tunnel hängen vom aktuellen OpenAI-Workspace und der aktuellen OpenAI-Dokumentation ab. Bitte zur Zeit der Verbindung deutlich ansehen; dieses Bildschirm erfindet keine unbekannte OAuth-/Tunnel-Befehl.

Sicherheit des Deployment

Der DHCP-Prozess braucht nur data/index.db und die SQLite-seitigen Neben-Dateien data/index.db-wal / data/index.db-shm. .env, telegram.session*, archive/, Medien bzw. Manifest dürfen nicht zugänglich sein. Führen Führen Sie den Server unter einem eigenen Unix-Benutzer mit minimalen Rechten aus; Synchronisierung und Indizierung laufen als separater Prozess mit bestimmten Schreibrechten.

🗂 Struktur

репозиторий с данными/
├── 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 – Quelle der Wahrheit. Monatsdateien; sync appendets nur neue Nachrichten, bestehende Gewässer werden nie angefasst.

• index.db – eine separate Ebene. Sie kann jederzeit gelöscht bearbeitet werden (./tg index --rebuild), ohne Datenverlust.

• manifest.json – der Manager. Er lebensindexierte Neuaufbau; speichert, welcheChats/Topicstrackers werden und welche Medientypen für sie heruntergeladen werden.

Diese Trennung (Engine in Git, offen → Daten getrennt, privat) egal, es ermöglicht, den Code freely weiterzuentwickeln und zu teilen, ohne das Risiko eines Datenlecks in den Chatverläufen.

🧭 Befehle

Suchbefehle – das Wesentliche für Agenten

Projekt-Liste – manuelle Betriebsart

Downloader und Manager

Ein Chat kann als id, als Alias aus config.toml, als Teilname, @username oder Link t.me/... angegeben werden. Neue Nachrichten werden mit allen Reaktionen, Umfragen und Service-Ereignissen heruntergeladen.

🎙 Transkription von Sprachnachrichten

Der Provider wird in config.toml [transcription] festgelegt:

👥 Mehrere Konten

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

tg login --account backup autorisiert eine neue Sitzung. download / sync / dialogs / meta haben jeweils das Flag --account. Jeder Titel im Manifest ist seinem Konto zugeordnet.

🗺Status

Als Nächstes: Auto-Sync nach Zeitplan, OCR von Bildern, Azure-Speech-Provider, Export von Auswahlen.

🔒 Sicherheit

telegram.session und .env geben vollen Zugriff auf das Telegram-Konto. Bewahren Sie sie in einem separaten privaten Repository mit den Daten auf; committen Sie sie nicht in dieses Repository und veröffentlichen Sie sie irgendwo.

Entwickelt, damit ein Agent die Unterhaltung besser merken kann als man selbst.