paperloom

Исследовательская вики уровня папки, поддерживаемая LLM. Паттерн llm-wiki Карпати — для научных статей.

$ 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 — это небольшой MCP-сервер + CLI, который даёт кодинг-агенту (Claude Code, Gemini CLI, ...) файловые примитивы для ведения персональной исследовательской вики из папки с markdown-файлами: пакетный импорт PDF, поиск, создание заметок, тегирование. Всю собственно работу по чтению и обдумыванию выполняет агент. В отличие от типовой настройки llm-wiki или глобальной папки данных MindBase, хранилище paperloom — это одна самодостаточная директория (git init && paperloom init — и готово), рассчитанная на пакетный импорт корпусов из 50–1000 статей. Собственный ключ LLM API ему не нужен — у вашего основного агента он уже есть.

Related MCP server: agtmem-mcp

Благодарности

Paperloom стоит на плечах двоих:

• Andrej Karpathy — за паттерн LLM-wiki, который воплощает весь этот проект.

• MindBase Фрэнка Чу — за то, что доказал: из паттерна можно сделать продукт, а также за соглашения о схеме CLAUDE.md, которые мы заимствуем и расширяем.

Paperloom отличается тем, что он ограничен папкой (одна база знаний на директорию, без глобального состояния), изначально рассчитан на пакетный импорт (создан для корпусов из 50–1000 статей) и не требует собственного ключа LLM API.

Полная история — в docs/credits.md.

Быстрый старт

Ещё не опубликовано на PyPI — установите из исходников (см. Установка ниже), затем:

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

paperloom init не создаёт .mcp.json за вас — добавьте его сами (один раз на хранилище):

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

Затем укажите вашему кодинг-агенту на хранилище и начните с /contribute или просто спросите, что есть в вики. Полное руководство — в docs/quickstart.md.

Что это такое / чем не является

Это:

• Набор MCP-инструментов для работы с файлами (search, read_page, create_note, ...) плюс CLI для пакетного импорта PDF.

• Ограничен папкой — каждое хранилище это самодостаточная директория, без глобального состояния и без демона.

• Ноль ключей API по построению — LLM выступает ваш основной кодинг-агент.

• Создан для реальных корпусов — пакетный импорт, возобновляемые параллельные задания MinerU, изоляция сбоев по каждой статье.

Это не:

• Веб-интерфейс. Если хотите, укажите Obsidian на хранилище.

• Векторная база данных или семантический поиск. Ripgrep + рассуждения агента закрывают реальные сценарии вплоть до сотен статей; если любопытно, почему это осознанный выбор, см. не-цели в билд-спеке.

• Собственный LLM-роутер. Плагин Ollama (v0.2) — единственный путь, где «paperloom напрямую вызывает LLM», и он опционален и предназначен только для headless-задач.

• Многопользовательский, с аутентификацией или SaaS. paperloom mcp работает только через stdio, один процесс на клиента.

Установка

Ещё не опубликовано на PyPI. Склонируйте (или скопируйте) этот репозиторий и установите с помощью uv, а не обычного pip — проверено лично: свежий pip install . действительно падает с ошибкой resolution-too-deep (резолвер pip не справляется с объединённым графом зависимостей mineru[core] + fastmcp), тогда как uv pip install . спокойно резолвит тот же самый граф за несколько минут.

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 . вместо ., если хотите дорабатывать сам paperloom — см. CONTRIBUTING.md.)

Вам также понадобится ripgrep в PATH — это системный бинарник, а не pip-пакет:

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

Необязательные дополнения:

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] (собственно локальный PDF-парсер, автоматически подтягиваемый как основная зависимость) тяжёлый — он ставит PyTorch, а при первом реальном разборе PDF скачивает несколько гигабайт весов моделей. Если нужен локальный разбор PDF, этого не избежать; заложите диск и время (и, в идеале, GPU — на одном CPU разбор работает, но заметно медленнее) на первый настоящий запуск paperloom ingest.

Протестировано в первую очередь на Linux; Windows работает через WSL2 (см. собственные заметки в билд-спеке), но не является основной целью.

Первое хранилище (5 минут)

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

Это копирует внутрь шаблон scientific-paper-vault: CLAUDE.md (схема — см. ниже), пустые context.md/index.md и каркас sources//artifacts//logs/. Он также записывает .paperloom/config.yaml и выполняет git init, если вы ещё этого не делали.

paperloom ingest ~/Downloads/some-papers/

Каждый PDF разбирается MinerU в sources/raw/<paper-id>/paper.md + meta.json. Идентификаторы по возможности определяются по паттерну arXiv/DOI на первой странице, а иначе используется хэш содержимого. Этот шаг никогда не трогает sources/research/ — импорт и написание вики намеренно разделены.

claude "/contribute sources/raw/2301.08243"

Ваш кодинг-агент читает CLAUDE.md, составляет план (какие страницы создать, какие обновить), показывает его вам и после одобрения пишет настоящие вики-страницы через MCP-инструменты. Повторите для остальных статей, а затем попробуйте:

claude "What does my wiki know about JEPA?"

Полностью заполненный пример хранилища, который можно посмотреть, а не собирать с нуля, — в examples/ml-robotics-vault/.

Архитектура

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

Три слоя, три уровня доверия: sources/raw/ — точная и никогда не редактируемая транскрипция; sources/research/ — место, где находятся реальные суждения агента, всегда ссылающиеся на raw/; sources/contributors/ — ваш личный ежедневный журнал, в который можно дописывать, но нельзя переписывать. Полный справочник по структуре страниц — в docs/schema.md.

9 инструментов

Это весь список, и он намеренно такой — о том, что сознательно не входит в базовый набор инструментов (семантический поиск, автофиксы при линтинге, всё многопользовательское) и почему, см. в билд-спеке.

Плагины

Нужен инструмент сверх этих девяти? Напишите плагин — Python-модуль, предоставляющий register(mcp). Он загружается из трёх мест (встроенного, стороннего через pip entry points или локального для хранилища в .paperloom/plugins/), при этом более поздние источники переопределяют более ранние при коллизии имён. Полное руководство и справочный example_plugin.py (word_count, find_orphans) — в docs/plugins.md.

Бэкенд Ollama

Для headless-задач и задач по расписанию (ночной /rebuild-context, /lint по cron), когда сессию активно не ведёт основной агент, uv pip install "paperloom[ollama]" добавляет инструмент synth, который прогоняет промпт через локальную модель Ollama — без API-ключа, полностью офлайн. Используйте его для механической рутины; по-настоящему решения по-прежнему принимает интерактивный основной агент. (v0.2 — ещё не реализовано; отслеживается как пункт 10 §17 в билд-спеке.)

Миграция из MindBase

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

Копирует (никогда не перемещает) sources/raw/, sources/research/, sources/contributors/, context.md, README.md и logs/ в новое хранилище paperloom, заново строя индексы по данным на диске, а не доверяя index.yaml от MindBase. (v0.2 — ещё не реализовано; отслеживается как пункт 9 §17 в билд-спеке.)

Опционально: просматривайте хранилище визуально

Хранилища paperloom — это обычный markdown с [[wikilinks]], поэтому Obsidian работает с ними сразу из коробки:

1. Откройте Obsidian → «Открыть папку как хранилище» → корень вашего хранилища paperloom.

2. По желанию установите плагин Dataview — YAML frontmatter можно запрашивать через Dataview.

3. Ctrl-G — для просмотра графа.

Не обязательно и не является зависимостью — просто приятный побочный эффект формата файлов.

Дорожная карта

Запланированные плагины (v0.3+, может добавлять сообщество), а не новые базовые инструменты:

• arxiv_watcher — опрашивает arXiv в поисках новых статей по сохранённым запросам.

• marp_export — превращает страницу-синтез в слайд-колоду Marp.

• graph_export — экспортирует граф [[wikilink]] в GraphViz/JSON.

• citekey_lint — проверяет ссылки \cite{...} в черновых артефактах.

Ядро (9 инструментов, CLI, система плагинов, схема) считается готовым начиная с v0.1 — см. CHANGELOG.md.

Участие

См. CONTRIBUTING.md — настройка, команды тестов, что зафиксировано билд-спеком, а что открыто для изменений. Issues и PR приветствуются, особенно плагины.

Лицензия

Apache-2.0.

Цитирование

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