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

Telegram 채팅 내역의 아카이브 및 스마트 검색 엔진

JSONL 원본 메시지 · 러시아어 형태소를 이해하는 전문 텍스트 검색 · 다운로더 및 매니저

아이디어

Letopis는 봇이나 서비스가 아니라 CLI 도구입니다. LLM 에이전트(특히 Claude Code)가 Telegram 채팅 내역을 읽고, 일반적인 지식 베이스처럼 그 내용으로 질문에 답할 수 있도록 설계되었습니다.

아카이브는 일반 파일 — .jsonl로 저장됩니다. 채팅과 월별로 하나씩, append-only입니다. 그 위에 SQLite FTS5 전문(full-text) 검색 인덱스가 구성되며, 이 인덱스는 러시아어 형태를 인식합니다. «хостинг»: 라는 검색어로 «хостиHGOM»라는 단어를 포함한 메시지를 찾아냅니다. 음성 메시지의 텍스트, 파일 이름, 투표 텍스트도 검색에 연결됩니다.

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

Letopis는 엔진만 제공합니다. 특정한 아카이브에 연결하려면 **별도의 데이터 저장소(repository)**를 만들고 거기에 ./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 for ChatGPT

Letopis는 ChatGPT용 read-only MCP retrieval gateway로 작동할 수 있습니다. 서버는 일반 검색과 같은 data/index.db를 사용하지만, 오직 안전한 retrieval 관련 도구 — 아카이브 목록 검색, 검색, 집계, 메시지 선택, 로컬 컨텍스트만 제공합니다. MCP 프로세스는 Telegram 동기화, 파일 다운로드, 색인 수정을 하지 않습니다.

설치 및 실행

MCP SDK와 테스트 의존성을 엔진 환경에 설치하세요:

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

엔트리포인트를 통해 실행합니다:

.venv/bin/letopis-mcp

대안: .venv/bin/python -m tgarchive.mcp.server. 기본적으로 서버는 http://127.0.0.1:8765/mcp를 수신하고 루프백 주소만 허용합니다. 프로덕션에서는 프로세스 환경에 안정적인 커서 시크릿과 인덱스 경로를 지정해야 합니다. 예를 들어:

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

환경 변수

속도 제한은 의도적으로 프로세스 단위 전역입니다. 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 설정 방법은 현재 OpenA workspace 및 최신 OpenAI 문서에 따라 달라집니다. 접속 시점에 확인하세요. 이 저장소는 확인되지 않은 OAuth/tunnel 명령을 추측하여 만들지 않습니다.

배포 보안

MCP 프로세스에는 data/index.db와 필수 SQLite sidecar 파일 data/index.db-wal / data/index.db-shm만 필요합니다. 그 프로세스에는 .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 저장소로 공개 · 데이터는 별도의 비공개)를 통해 대화 기록 누출의 위험 없이 코드를 자유롭게 개발하고 공유할 수 있습니다.

🧭 명령어

검색 — 주요 기능

Viewer — 수동 모드

다운로더 및 관리자

채팅은 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 계정에 대한 완전한 접근 권한을 제공합니다. 이 파일들을 별도의 비공개 리포지토리에 데이터와 함께 보관하고, 이곳에 커밋하거나 어디에도 공개하지 마십시오.

대화를 기억하는 비밀보다 더 잘 기억하도록 만들어졌습니다.