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

Motor de archivado y búsqueda inteligente para el historial de los chats de Telegram

Mensajes en crudo en JSONL · búsqueda de texto completo con morfología rusa · descargador con gestor

Idea

Letopis no es un bot ni un servicio, sino una herramienta CLI pensada para que un agente LLM (principalmente Claude Code) pueda leer el historial de tus chats de Telegram y responder preguntas a partir de él, como si fuera una base de conocimientos cualquiera.

El archivo se almacena como archivos normales — .jsonl, uno por chat y mes, append-only. Sobre ellos se construye un índice SQLite con búsqueda de texto completo (FTS5), que entiende las formas de las palabras rusas: la consulta «хостинг» encuentra mensajes con la palabra «хостингами». A la búsqueda también están conectadas las transcripciones de voz, los nombres de archivo y el texto de las encuestas.

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

El motor y los datos están separados. Este repositorio contiene solo el código: los propios archivos de los chats, config.toml, .env y la sesión de Telegram viven en un repositorio privado separado, lo que te permite mantener el control sobre lo que es público y lo que no. Más información en «Estructura».

Related MCP server: telegram-user-mcp

✨ Funcionalidades

🚀 Inicio rápido

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 es solo el motor. Para conectarlo a un archivo concreto, crea un repositorio de datos separado y coloca allí la envoltura ./tg:

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

A partir de ahí, todo se ejecuta desde la raíz del repositorio con los datos:

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

El motor encuentra solo la raíz de datos: al lanzar ./tg, busca desde el directorio actual hacia arriba una carpeta donde estén config.toml y archive/ (o se le indica explícitamente con la variable de entorno TG_ROOT).

🚀 MCP de solo lectura para ChatGPT

Letopis puede funcionar como un read-only MCP retrieval gateway para ChatGPT: el servidor usa el mismo data/index.db que la búsqueda normal, pero solo expone cinco herramientas seguras de recuperación: vista general del archivo, búsqueda, agregados, recuperación de mensajes y contexto local. El proceso MCP no sincroniza Telegram, no descarga archivos ni modifica el índice.

Instalación y ejecución

Instala el SDK de MCP y las dependencias de prueba en el entorno del motor:

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

Ejecución a través de entrypoint:

.venv/bin/letopis-mcp

Forma alternativa: .venv/bin/python -m tgarchive.mcp.server. Por defecto, el servidor escucha en `http://127.0.0.1:8765/mcp» and persists only loopback addresses. Para producción, establece un secreto de cursores estable y la ruta al índice en el entorno del proceso, por ejemplo:

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

Variables de entorno

Rate limit se aplica a propósito de forma global en cada proceso: en v1 no hay OAuth ni principals identificator, por lo que no es un ACL por usuario. MCP lee estas variables como configuración del proceso y no carga automáticamente .env.

conexión a ChatGPT

El esquema recomendado no publica Letopis directamente a Internet:

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

Los comandos concretos y los pasos de configuración de Secure MCP Tunnel depends on workspace actual de OpenAI and actual documentation de OpenAI. Consúltalos al momento de realizar la conexión; este repositorio no inventa ningún comando OAuth/tunnel sin verificar.

Seguridad del despliegue

El proceso MCP solo necesita data/index.db y los correspondientes sidecar de SQLite data/index.db-wal / data/index.db-shm. No debe tener acceso a .env, telegram.session*, archive/, de los archivos multimedia o del manifest. Ejecuta el servidor con un usuario Unix separado y con el mínimo de privilegios; la sincronización y la indexación deben hacerlo por separado con вклюros los permisos de escritura necesarios.

🗂 Estructura

репозиторий с данными/
├── 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 es la fuente de verdad. Archivos por mes, sync solo añade mensajes nuevos y nunca toca los antiguos.

• index.db: capa derivada. Se puede eliminar y reconstruir (./tg index --rebuild) en cualquier momento sin perder datos.

• manifest.json: administrador. Sobrevive a losac sua de índice; sabe qué chats/temas se están siguiendo y qué tipos de medios de ahí se deseen download.

Esta separación (motor en git, abierto; los datos aparte y privados) allows develop to develop and share code without risk leak filters.

🧭 Comandos

Búsqueda: lo indispensable para el agente

Visores — modo manual

Descargador y gestor

El chat se puede indicar como id, un alias de config.toml, parte del nombre, @username o un enlace t.me/.... Los mensajes nuevos se descargan con todas las reacciones, las encuestas y los eventos de servicio.

🎙 Transcripción de voz

El proveedor se define en config.toml [transcription]:

👥 Varias cuentas

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

tg login --account backup autoriza una nueva sesión. download / sync / dialogs / meta tienen la opción --account. Cada chat del manifiesto está actado a su cuenta.

🗺 Estado

Próximo: sincronización automática, OCR de imágenes, proveedor de Azure Speech, exportación de selecciones.

🔒 Seguridad

telegram.session y .env dan acceso total a la cuenta de Telegram. Guarda estos archivos en un repositorio privado separado con los datos, no los concilia en este repositorio ni los publiques en ningún otro lugar.

Hecho para que el agente recuerde la conversación mejor que usted.