paperloom

Wiki de investigación mantenida por LLM, limitada a una carpeta. El patrón llm-wiki de Karpathy, para artículos científicos.

$ mkdir my-research && cd my-research
$ paperloom init
Vault created at /home/you/my-research

$ paperloom ingest ~/Downloads/papers/
Ingesting ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 12/12
12 ingested, 0 skipped, 0 failed (of 12)

$ claude "/contribute the I-JEPA paper"
[Claude Code reads sources/raw/2301.08243/paper.md, drafts a plan,
 writes sources/research/2301.08243-assran-i-jepa.md via the MCP tools]

TL;DR

Paperloom es un pequeño servidor MCP + CLI que proporciona a un agente de codificación (Claude Code, Gemini CLI, ...) las primitivas de archivo para mantener una wiki de investigación personal a partir de una carpeta de archivos markdown — ingesta de PDF por lotes, búsqueda, creación de notas, etiquetado — mientras que el agente aporta toda la lectura y el razonamiento reales. A diferencia de una configuración genérica de llm-wiki o de la carpeta de datos global de MindBase, un vault de paperloom es un directorio autocontenido (git init && paperloom init y listo) construido en torno a la ingesta de corpus de 50-1000 artículos a la vez, y nunca requiere una clave de API de LLM propia — tu agente anfitrión ya tiene una.

Related MCP server: ScholarMCP

Créditos

Paperloom se apoya en dos hombros:

• Andrej Karpathy por el patrón LLM-wiki que este proyecto entero instancia.

• MindBase de Frank Chu por demostrar que el patrón podía ser un producto, y por las convenciones de esquema de CLAUDE.md que tomamos prestadas y ampliamos.

Paperloom se diferencia por estar limitado a una carpeta (una KB por directorio, sin estado global), por ser de ingesta por lotes primero (diseñado para corpus de 50-1000 artículos) y por no requerir nunca una clave de API de LLM propia.

Consulta docs/credits.md para la historia completa.

Inicio rápido

Aún no está en PyPI — instala desde el código fuente (consulta Instalación más abajo), luego:

mkdir my-vault && cd my-vault
paperloom init
paperloom ingest ~/Downloads/papers/

paperloom init no crea .mcp.json por ti — añádelo tú mismo (una vez, por vault):

cat > .mcp.json << 'EOF'
{ "mcpServers": { "paperloom": { "command": "paperloom", "args": ["mcp"] } } }
EOF

Luego apunta tu agente de codificación al vault y empieza con /contribute o simplemente pregúntale qué hay en la wiki. Consulta docs/quickstart.md para el recorrido completo.

Qué es / qué no es

Es:

• Un conjunto de herramientas MCP de manipulación de archivos (search, read_page, create_note, ...) más una CLI para la ingesta de PDF por lotes.

• Limitado a una carpeta — cada vault es un directorio autocontenido, sin estado global, sin demonio.

• Cero claves de API por diseño — el agente de codificación anfitrión es el LLM.

• Diseñado para corpus reales — ingesta por lotes, reanudable, trabajos MinerU en paralelo, aislamiento de fallos por artículo.

No es:

• Una interfaz web. Apunta Obsidian al vault si quieres una.

• Una base de datos vectorial o un motor de búsqueda semántica. Ripgrep + razonamiento del agente cubre el uso real hasta cientos de artículos; consulta los no-objetivos de la especificación de construcción si tienes curiosidad por qué esto es deliberado.

• Su propio enrutador de LLM. El plugin de Ollama (v0.2) es la única vía de "paperloom llama a un LLM directamente", y es opcional, solo para trabajos sin cabeza.

• Multiusuario, con autenticación o SaaS. paperloom mcp es solo stdio, un proceso por cliente.

Instalación

Aún no publicado en PyPI. Clona (o copia) este repositorio, luego instala con uv, no con pip simple — verificado directamente: una instalación limpia de pip install . falla de verdad con un error resolution-too-deep (el resolvedor de pip no puede manejar el grafo de dependencias combinado de mineru[core] + fastmcp juntos), mientras que uv pip install . resuelve el mismo grafo limpiamente en unos minutos.

git clone https://github.com/Alpsource/paperloom
cd paperloom

curl -LsSf https://astral.sh/uv/install.sh | sh   # if you don't have uv yet
uv venv
uv pip install .
source .venv/bin/activate

(uv pip install -e . en lugar de . si quieres hackear paperloom en sí — consulta CONTRIBUTING.md.)

También necesitas ripgrep en PATH — es un binario del sistema, no un paquete pip:

# Debian/Ubuntu
sudo apt install ripgrep
# macOS
brew install ripgrep
# Fedora
sudo dnf install ripgrep

Extras opcionales:

uv pip install "paperloom[ollama]"   # offline synthesis via a local Ollama model
uv pip install "paperloom[grobid]"   # bibliography extraction via GROBID
uv pip install "paperloom[dev]"      # pytest, ruff, mypy, pre-commit, mkdocs-material, pip-audit

mineru[core] (el parser local de PDF real, incluido automáticamente como dependencia principal) es pesado — instala PyTorch y descarga varios GB de pesos de modelo la primera vez que realmente parsea un PDF. No hay forma de evitarlo si quieres parseo local de PDF; presupuesta el espacio en disco y el tiempo (e idealmente, una GPU — el parseo solo con CPU funciona pero es mucho más lento) para esa primera ejecución real de paperloom ingest.

Probado principalmente en Linux; Windows funciona mediante WSL2 (consulta las notas de la especificación de construcción) pero no es el objetivo principal.

Primer vault (5 minutos)

mkdir my-research && cd my-research
paperloom init

Esto copia la plantilla scientific-paper-vault: CLAUDE.md (el esquema — ver más abajo), context.md/index.md vacíos, y el esqueleto sources//artifacts//logs/. También escribe .paperloom/config.yaml y ejecuta git init si aún no lo has hecho.

paperloom ingest ~/Downloads/some-papers/

Cada PDF es parseado por MinerU en sources/raw/<paper-id>/paper.md + meta.json. Los IDs se detectan a partir del patrón arXiv/DOI en la primera página cuando es posible, recurriendo a un hash de contenido. Este paso nunca toca sources/research/ — la ingesta y la escritura de la wiki están deliberadamente separadas.

claude "/contribute sources/raw/2301.08243"

Tu agente de codificación lee CLAUDE.md, redacta un plan (qué páginas crear, cuáles actualizar), te lo muestra y, tras la aprobación, escribe páginas wiki reales mediante las herramientas MCP. Repite para más artículos, luego prueba:

claude "What does my wiki know about JEPA?"

Consulta examples/ml-robotics-vault/ para un vault de ejemplo completamente poblado que puedes explorar en lugar de construir uno desde cero.

Arquitectura

graph LR
    PDF[Original PDF] -->|paperloom ingest, MinerU| RAW
    subgraph RAW["sources/raw/<paper-id>/  (immutable)"]
        direction TB
        R1[paper.pdf]
        R2[paper.md]
        R3[meta.json]
    end
    RAW -->|"/contribute — host agent reads, writes"| RESEARCH
    subgraph RESEARCH["sources/research/  (agent-owned)"]
        direction TB
        W1[paper pages]
        W2[method pages]
        W3[dataset / concept / synthesis pages]
    end
    USER[You] -->|daily notes| CONTRIB["sources/contributors/<you>/"]
    CONTRIB -.->|"/contribute"| RESEARCH

Tres capas, tres niveles de confianza: sources/raw/ es una transcripción fiel y nunca editada; sources/research/ es donde vive el juicio real del agente, siempre citando de vuelta a raw/; sources/contributors/ es tu propio registro diario, al que se añade pero nunca se reescribe. Consulta docs/schema.md para la referencia completa de la forma de las páginas.

Las 9 herramientas

Esa es la lista completa, a propósito — consulta la especificación de construcción para ver qué no es deliberadamente una herramienta principal (búsqueda semántica, correcciones automáticas de lint, cualquier cosa multiusuario) y por qué.

Plugins

¿Necesitas una herramienta más allá de las 9? Escribe un plugin — un módulo de Python que exponga register(mcp), cargado desde tres lugares (integrado, de terceros mediante entry points de pip, o local al vault en .paperloom/plugins/) con los posteriores anulando a los anteriores en caso de colisión de nombres. Consulta docs/plugins.md para la guía completa y el example_plugin.py de referencia (word_count, find_orphans).

Backend de Ollama

Para trabajos sin cabeza o programados (reconstrucción nocturna de /rebuild-context, un /lint con cron) donde ningún agente anfitrión está conduciendo activamente la sesión, uv pip install "paperloom[ollama]" añade una herramienta synth que ejecuta un prompt a través de un modelo local de Ollama — sin clave de API, totalmente offline. Úsala para trabajo mecánico; el agente anfitrión interactivo sigue siendo donde ocurre el juicio real. (v0.2 — aún no construido; registrado como §17 elemento 10 en la especificación de construcción.)

Migrar desde MindBase

paperloom migrate-from-mindbase ~/mindbase-data/projects/my-research/

Copia (nunca mueve) sources/raw/, sources/research/, sources/contributors/, context.md, README.md y logs/ a un nuevo vault de paperloom, rederivando los índices desde el disco en lugar de confiar en el index.yaml de MindBase. (v0.2 — aún no construido; registrado como §17 elemento 9 en la especificación de construcción.)

Opcional: explora tu vault visualmente

Los vaults de paperloom son markdown plano con [[wikilinks]], así que Obsidian funciona con uno sin configuración:

1. Abre Obsidian → "Abrir carpeta como vault" → la raíz de tu vault de paperloom.

2. Opcionalmente instala el plugin Dataview — el frontmatter YAML es consultable con Dataview.

3. Ctrl-G para la vista de grafo.

No es necesario, ni se depende de ello — solo un feliz accidente del formato de archivo.

Hoja de ruta

Plugins planificados (v0.3+, contribuibles por la comunidad), no adiciones a las herramientas principales:

• arxiv_watcher — consulta arXiv en busca de nuevos artículos que coincidan con consultas guardadas.

• marp_export — convierte una página de síntesis en una presentación de diapositivas Marp.

• graph_export — exporta el grafo [[wikilink]] como GraphViz/JSON.

• citekey_lint — valida las referencias \cite{...} en artefactos de borrador.

El núcleo (las 9 herramientas, la CLI, el sistema de plugins, el esquema) se considera terminado a partir de v0.1 — consulta CHANGELOG.md.

Contribuciones

Consulta CONTRIBUTING.md — configuración, comandos de prueba, y qué está fijado por la especificación de construcción vs. abierto a cambios. Se aceptan issues y PRs, especialmente de plugins.

Licencia

Apache-2.0.

Cita

@software{paperloom,
  title  = {Paperloom: a folder-scoped, LLM-maintained research wiki},
  author = {{paperloom contributors}},
  year   = {2026},
  url    = {https://github.com/Alpsource/paperloom}
}