Papernook
Biblioteca académica auto-alojada filesystem-first para captura, anotación y lectura con IA privada
¿Qué es Papernook?
Papernook es una biblioteca de documentos académicos auto-alojada que prioriza el sistema de archivos como fuente de verdad. Permite capturar PDFs desde arXiv y editoriales mediante extensiones oficiales para Safari (Mac App Store) y Chrome Web Store, anotar directamente en los PDFs con Apple Pencil o ratón, y consultar con IA configurable (Claude Code, Codex, API local).
La arquitectura combina Next.js con Python/Node.js, usando SQLite FTS5 como acelerador de búsqueda reconstruible. Las anotaciones se escriben directamente en los PDFs para máxima portabilidad, las conversaciones se almacenan como archivos JSONL simples, y el índice puede eliminarse sin perder la biblioteca.
Características principales
- Persistencia filesystem-first: Anotaciones en PDFs nativos, conversaciones como JSONL, SQLite FTS5 reconstruible
- IA configurable: Claude Code, Codex, API local sin dependencia obligatoria
- Extensiones oficiales: Safari (Mac App Store) y Chrome Web Store para captura directa desde arXiv
- WebDAV opcional: Sincronización multi-dispositivo
- Perfiles separados: Chats, tokens de captura y conexiones Zotero por lector
- Enlaces revocables: Compartir lecturas con acceso visual solo
Arquitectura técnica
| Componente | Tecnología | Función |
|---|---|---|
| Frontend | Next.js + TypeScript | Lectura web con anotaciones en tiempo real |
| Backend | Python/Node.js | API, procesamiento de PDFs, IA |
| Búsqueda | SQLite FTS5 | Índice reconstruible desde archivos |
| Persistencia | Sistema de archivos | Fuentes de verdad: PDFs, JSONL |
| IA | Claude/Codex/API local | Análisis contextualizado por documento |
Instalación y despliegue
Método 1: Script oficial (recomendado)
curl -fsSL https://raw.githubusercontent.com/affromero/papernook/main/scripts/install.sh | bash
# Clona el repo, detecta Codex/Claude, escribe .env, docker compose upPara instalación reproducible con release tag:
git clone --branch v0.3.0 --depth 1 https://github.com/affromero/papernook.git
cd papernook
./scripts/install.shMétodo 2: Docker Compose
Utilizar tags de release (ej. v0.3.0) para instalaciones reproducibles. Docker mounts solo el archivo de credenciales del proveedor seleccionado; ver .env.example para CODEX_AUTH_FILE y CLAUDE_AUTH_FILE.
Método 3: Actualización
papernook update # newest release tag: back up, rebuild, check health
papernook update --check # what an update would move to, changing nothing
papernook update --main # follow development branch instead of releasesRequisitos del sistema
- Servidor propio: Máquina controlada para backend completo
- Puerto 3000: Libre y accesible
- Variables de entorno: Configuración en .env (proveedor IA, puertos, WebDAV)
- Herramientas locales: Codex/Claude CLI detectados automáticamente o API externa
- Docker opcional: Para despliegue containerizado con mounts de credenciales
Ciclo de lectura
- Captura: Abrir PDF en arXiv o página editorial. La extensión envía navegación al servidor, que descarga el paper, pregunta a la IA por tema, tags y resumen, y lo archiva.
- Anotar: Resaltar y dibujar en el navegador. El ink se escribe en el PDF mismo, así que cualquier lector abre el archivo con o sin Papernook.
- Consultar: El chat está al lado del paper y responde desde él. Sus conversaciones son archivos JSONL junto al PDF, no filas en una base de datos ajena.
- Practicar: Convertir respuestas en ejercicios PDF listos para Apple Pencil, añadir márgenes o páginas en blanco sin desplazar el ink existente.
- Compartir: Enviar lectura anotada revocable. Snapshots de conversación explícitos e inmutables, desactivados por defecto.
Integraciones
| Navegador | Instalación | Estado |
|---|---|---|
| Safari | Mac App Store | live |
| Chrome | Chrome Web Store | live |
Ambos navegadores ejecutan el mismo código fuente de extension/. Para builds no publicados, npm run build:chrome produce un zip cargable.
Seguridad
- Licencia MIT: Código abierto y modificable
- CI automatizado: GitHub Actions con CodeQL y gitleaks
- Dependabot: Actualización automática de dependencias
- .gitleaks.toml: Protección contra fugas de secretos
- Secrets management: .env.example con mounts por proveedor
Alternativas reales
Zotero + plugins IA: Gestión bibliográfica robusta pero sin anotaciones persistentes en PDFs nativos ni chat contextualizado.
Obsidian + PDF plugins: Portabilidad excelente pero requiere configuración manual de cada documento y no ofrece captura automatizada desde arXiv.
ReadCube / ResearchRabbit: Descubrimiento de papers bueno, pero sin capacidad de anotación persistente en el PDF original ni despliegue auto-alojado completo.
Preguntas frecuentes
- ¿Puedo eliminar el índice SQLite sin perder mis documentos?
- Sí. El filesystem es la fuente de verdad; borrar el índice y reconstruirlo desde los archivos no afecta a PDFs ni anotaciones.
- ¿Cómo actualizo Papernook?
- Ejecutar papernook update (respalda automáticamente con scripts/backup.sh). Para desarrollo: papernook update --main. Verificar papernook status antes de actualizar.
- ¿Necesito Docker para usarlo?
- No. El script install.sh detecta Codex/Claude, escribe .env y levanta el servicio. Docker Compose es opcional para despliegues multi-contenedor.
- ¿Puedo cambiar de proveedor de IA?
- Sí. Configurar CLAUDE_AUTH_FILE o CODEX_AUTH_FILE en .env, apuntando a API local, Claude Code CLI, Codex CLI o cualquier servidor OpenAI-compatible.
- ¿Cómo sincronizo entre dispositivos?
- Opcional: configurar WebDAV para acceso multi-dispositivo. Las anotaciones en PDFs son portables sin sincronización adicional.