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

Telegram チャット履歴のアーカイブとスマート検索のエンジン

JSONL の生メッセージ · ロシア語の形態素解析対応の全文検索 · ダウンローダー＋マネージャー

コンセプト

Летопись はボットでもサービスでもなく、CLIツールです。LLMエージェント（主に Claude Code）が、あなたの Telegram チャット履歴を読み込み、通常のナレッジベースのようにその内容に基づいて質問に答えられるように設計されています。

アーカイブは通常のファイルとして保存されます。.jsonl 形式で、チャットごと・月ごとに1ファイル、append-only です。その上には、ロシア語の語形変化を理解する全文検索（FTS5）の SQLite インデックスが構築されています。たとえば「хостинг」という検索クエリで「хостингами」という語を含むメッセージも見つかります。検索対象には音声メッセージの文字起こし、ファイル名、アンケートの本文も含まれます。

$ ./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 で明示的に指定できます）。

🤖 ChatGPT 向け読み取り専用 MCP

Letopis は ChatGPT の読み取り専用 MCP retrieval gateway として動作できます。サーバーは通常の検索と同じ data/index.db を使いますが、公開するのは安全な取得系ツール（アーカイブの概要・検索・集計・メッセージ抽出・ローカルコンテキスト）の5つのみです。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 アドレスのみを受け付けます。本番環境では、プロセス環境に安定したカーソルシークレットとインデックスへのパスを指定してください。例:

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

環境変数

レート制限は意図的にプロセス単位でglobal（グローバル）になっています。v1 には OAuth 識別されたプリンシプルがないため、ユーザーごとの ACL ではありません。MCP はこれらの変数をプロセス設定として読み取り、.env を自動的に読み込むことはありません。

ChatGPT への接続

推奨される構成では、Letopis をインターネットに直接公開しません。

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

Secure MCP Tunnel の具体的なコマンドや設定手順は、その時点の OpenAI ワークスペースと OpenAI 公式ドキュメントによって異なります。接続時に確認してください。このリポジトリは、未検証の OAuth トンネルコマンドを独自に作り出すことはありません。

デプロイのセキュリティ

MCP プロセスに必要なのは data/index.db と、必要な SQLite sidecar ファイルである data/index.db-wal と data/index.db-shm だけです。MCP プロセスから .env、telegram.session*、archive/、メディア、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 アカウントへの完全なアクセスを提供します。これらはデータとともに別のプライベートリポジトリに保存し、このリポジトリにはコミットしないでください。また、どこにも公開しないでください。

エージェントがあなた自身よりも会話をよく記憶しているように作られました。