paperloom

Ordnerbezogenes, LLM-gepflegtes Forschungswiki. Karpathys llm-wiki-Muster, für wissenschaftliche Artikel.

$ 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]

Kurzfassung

Paperloom ist ein kleiner MCP-Server + CLI, der einem Coding-Agenten (Claude Code, Gemini CLI, ...) die Datei-Basisoperationen bereitstellt, um ein persönliches Forschung-Wiki aus einem Ordner voller Markdown-Dateien zu pflegen – Stapel-PDF-Import, Suche, Notizenerstellung, Verschlagwortung – während der Agent die tatsächliche Lese- und Denkarbeit übernimmt. Anders als eine generische llm-wiki-Einrichtung oder MindBase’s global Ordnerdatenordner ist eine Paperloom-Vault ein einzelnes in sich geschlossenes Verzeichnis (git init && paperloom init – fertig), das darauf ausgelegt ist, Korpora von 50 bis 1000 Papieren in einem Zug aufzunehmen, und es verlangt nie einen eigenen LLM-API-Schlüssel – der Hostagent hat bereits einen.

Related MCP server: ScholarMCP

Danksagungen

Paperloom stützt sich auf zwei Schultern:

• Andrej Karpathy für das LLM-Wiki-Muster, das dieses Projekt vollständig umsetzt.

• Frank Chus MindBase für den Beweis, dass das Muster ein Produkt sein konnte, sowie für die CLAUDE.md-Schema-Konventionen, die wir übernehmen und erweitern.

Paperloom unterscheidet sich dadurch, ordnergebunden zu sein (eine KB pro Verzeichnis, kein globaler Zustand), Stapel-Import zuerst (entwickelt für Korpora von 50–1000 Papers) und keinen eigenen LLM-API-Schlüssel zu benötigen.

Volle Ausführungen in docs/credits.md.

Schnellstart

Noch nicht auf PyPI – aus dem Quellcode installieren (siehe Installation unten), danach:

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

paperloom init erzeugt nicht .mcp.json für dich – ergänze sie selbst (einmalig, pro Vault):

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

Dann richtest deinen Coding-Agent auf die Vault aus und starte mit /contribute oder frage einfach, was im Wiki steht. Siehe den vollständigen Leitfaden in docs/quickstart.md.

Was es ist / was es nicht ist

Es ist:

• Ein Set aus Dateibearbeitungs-MCP-Tools (search, read_page, create_note, ...) plus eine CLI für den Stapel-PDF-Import.

• Ordnerbezogen – jede Vault ist ein selbstständiges Verzeichnis, kein globaler Zustand, kein Dämon.

• Von Grund auf ohne eigenen API-Schlüssel konstruiert – der Host-Coding-Agent ist die LLM.

• Gebaut für echte Korpora – Stapel-Import, fortsetzbar, parallele MinerU-Jobs, Fehlerisolation pro PDF.

Es ist nicht:

• Eine Web-Oberfläche. Richt Obsidian auf deine Vault, falls du eine haben möchtest.

• Eine Vektor-Datenbank oder semantische Suchmaschine. Ripgrep plus Agent-Urteilsvermögen deckt realen Einsatz bis zu Hunderten Papieren ab; die genauen Gründe dafür stehen in den Nicht-Zielen der Build-Spezifikation.

• Ein eigener LLM-Router. Der Ollama-Plugin (v0.2) ist der einzige Pfad, bei dem Paperloom direkt eine LLM zusätzlich ruft, und diese ist wahlfrei (opt‑in) und nur für Headless-Jobs.

• Multi‑User, authenticate oder SaaS. paperloom mcp ist ausschließlich stdio‑fähig, ein Prozess pro Client.

Installation

Noch nicht auf PyPI veröffentlicht. Das Repo klonen (oder kopieren) und dann mit uv installieren, nicht mit einfachem pip – direkt verifiziert: *pip install .schlägt tatsächlich mitresolution-too-deepfehl (der Pip-Resolver schafft den kombinierten Abhängigkeitsgraph vonmineru[core]+fastmcpnicht)``` komint, währenduv pip install .` den identischen Graph in wenigen Minuten sauber löst.

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 . statt ., wenn du selbst an Paperloom herumbauen möchtest – siehe CONTRIBUTING.md).

Außerdem doodst du ripgrep in PATH – das ist ein Systembinary, kein Pip-Paket:

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

Optionale Erweiterungen:

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] (der eigentliche lokale PDF‑Parser, wird automatisch als Kernabhängigkeit eingezogen) ist schwergewichtig – er installiert PyTorch und lädt beim ersten tatsächlichen Parsen eines PDFs einige GB an Modellgewichten herunter. Wenn du lokales PDF‑Parsing willst, komset du darum nicht herum; plane Plattenb bedarf, Zeit (idealerweise auch eine GPU – reines CPU‑Parsing funktioniert, ist aber deutlich langsamer) für den ersten echten paperloom ingest‑Lauf ein.

Primär auf Linux getestet; Windows funktioniert über WSL2 (siehe die Hinweise der Build‑Spezifikation), ist aber nicht das Hauptziel.

Erste Vault (5 Minuten)

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

Dadurch wird das Template scientific-paper-vault übernommen: CLAUDE.md (das Schema – siehe unten), leere context.md/index.md sowie das Grundgerüst von sources//artifacts//logs/. Zusätzlich wird .paperloom/config.yaml geschrieben und git init ausgeführt, falls noch nicht geschehen.

paperloom ingest ~/Downloads/some-papers/

Jedes PDF wird von MinerU in sources/raw/<paper-id>/paper.lock.md und meta.json geparst. IDs werden, wenn möglich, aus dem arXiv/DOI-Muster auf der ersten Seite erkannt; fallback auf einen Inhalts‑Hash. Dieser Schritt berührt niemals sources/research/ – Import und Wiki‑Schreiben sind bewusst getrennt.

claude "/contribute sources/raw/2301.08243"

Dein Coding-Agent liest CLAUDE.md, entwirft einen Plan (welche Seite welches unterschrieben), zeigt ihn dir, und nach Freigabe schreibt echte Wiki-Seiten über die MCP‑ Tools. Wiederhole für weitere Paper und dann:

claude "What does my wiki know about JEPA?"

Siehe examples/ml-robotics-vault/ für eine vollständig befüllte Beispiel-Vault, statt von Grund auf eine neue anzulegen.

Architektur

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

Drei Ebenen, drei Vertretensstufen: sources/raw/ ist eine treue, niemals bearbeitende Abschrift; sources/research/ ist der Ort für echtes Agent-Urteiler, das stets auf raw/ zurückverweist; sources/contributors/ ist dein tägliches Erlebnisprotokoll, ergänzt aber nie überschrieben. Für vollständige Seiten‑Referenz siehe docs/schema.md.

Die 9 Werkzeuge

Das ist die komplette Liste, bewusst – Einblick in die Build‑Spezifikation warum bewusst kein Kern‑Werkzeug ist, findest du und warum.

Plugins

Braucht du ein Werkzeug über die 9 hinaus? Schreib ein Plugin – ein Python‑Modul, register(mcp) bereitstellt, geladen aus drei Stellen (built-in, Drittanbieter über pip‑‑Points, oder Vault‑lokal in .paperloom/plugins/), wobei bei Namenskonflikten die jeweils späteren gewinnen. Komplette Anleitung und Referenzplich in docs/plugins.md mit example_plugin.py (word_count, find_orphans).

Ollama-Backend

Für unbeaufsichtigte/ geplante Jobs (nächtliches /rebuild-context, per Cron gestartetes /lint), wenn kein Host-Agent die Session führt, fügt uv pip install "paperloom[ollama]" ein Tool synth hinzu, das einen Prompt über ein lokales Ollama-Model ausführt – keine API‑Schlüssel, komplett offline. Nur für mechanische Pflichtarbeiten nutzen; wesentliche Entscheidungen bleiben weiter Aktivität des interaktiven Host‑Agenten. (v0.2 – noch nicht gebaut; in der Build‑Spec als §17, Punkt 10 erfasst.)

Migration von MindBase

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

Übernimmt (nia durchschiebt) sources/raw/, sources/research/, sources/contributors/, context.md, README.md und logs/ in eine neue Paper‑Vault, wobei die Indizes ausgehend vom Datenträger neu abgeleitet werden statt MindBase’s index.yaml zu vertrauen. (v0.2 – noch nicht gebaut; in der Build‑Spec als §17, Punkt 9 erfasst.)

Optional: deine Vault visuell durchstöbern

Paperloom-Vaulten sind reine Markdown-‑Dateien mit [[wikilinks]], sodass Obsidian sofort auf einer Vault funktioniert:

1. Öffne Obsidian → „Ordner als Vault öffnen“ → Dein Paperloom-Vault-Wurzelverzeichnis.

2. Optional das Dataview-Plugin installieren – Das YAML-Frontmatter lässt sich per Dataview abfragen.

3. Ctrl‑G für die Grafi‑Ansicht.

Nicht verlangt, nicht darauf – freundlicher Nebeneffekt des Dateiformats.

Roadmap

Geplante Plugins (v0.3+, Community‑Beiträge möglich), keine Kern-Erweiterungen:

• arxiv_watcher – arXiv nach neuen Papers in gespeicherten Suche abfragen.

• marp_export – Synthese-Seite in ein Marp-Folien-Set umwandeln.

• graph_export – Den [[wikilink]]‑Graph als GraphViz/JSON exportieren.

• citekey_lint – \cite{...}‑References in Entwurfs‑Artefakten validieren.

Der Kern (die 9 Werkzeuge, die CLI, jedes Plugin‑System, das Schema) ist mit v0.1 abgeschlossen – siehe CHANGELOG.md.

Mitwirken

Siehe CONTRIBUTING.md – Einstieg, Test‑Commands und was durch die Build-Spezifikation fixiert vore Späich.4. Issues und PRs sind willkommen, insbesondere neue Plugins.

Lizenz

Apache‑2.0.

Zitieren

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