paperloom

フォルダ単位で管理するLLMメンテナンス型リサーチWiki。Karpathyの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、...）に、マークダウンファイルのフォルダから個人用リサーチWikiを 維持するためのファイルプリミティブを提供する — バッチPDF取り込み、検索、 ノート作成、タグ付け — 実際の読み取りと推論はすべてエージェントが担う。 一般的なllm-wikiセットアップやMindBaseのグローバルデータフォルダとは異なり、 paperloomボールトは自己完結型の単一ディレクトリ（git init && paperloom initで完了）であり、 50〜1000件の論文を一度に取り込むコーパスを前提に設計され、独自のLLM APIキーを 一切必要としない — ホストエージェントがすでに持っているからだ。

Related MCP server: ScholarMCP

Credits

Paperloomは二つの巨人の肩の上に立つ：

• Andrej Karpathy — このプロジェクト全体が具現化するLLM-wikiパターンの提唱者。

• Frank ChuのMindBase — このパターンが製品になり得ることを証明し、私たちが借用・拡張するCLAUDE.mdスキーマ規約を提供してくれた。

Paperloomが異なる点は、フォルダ単位であること（ディレクトリごとに1つのKB、グローバル状態なし）、バッチ取り込み優先であること（50〜1000件の論文コーパス向けに設計）、そして独自のLLM APIキーを一切必要としないこと。

完全なストーリーはdocs/credits.mdを参照。

Quickstart

まだPyPIには未公開 — ソースからインストール（Installを参照）、 その後：

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で始めるか、 Wikiに何があるか尋ねるだけでよい。完全なウォークスルーは docs/quickstart.mdを参照。

これは何か / 何でないか

これは：

• ファイル操作MCPツール群（search、read_page、create_note、...）＋バッチPDF取り込み用CLI。

• フォルダ単位 — 各ボールトは自己完結型ディレクトリで、グローバル状態もデーモンもなし。

• 設計上ゼロAPIキー — ホストコーディングエージェントがLLMそのもの。

• 実コーパス向け — バッチ取り込み、再開可能、並列MinerUジョブ、論文ごとの障害分離。

これは違う：

• Web UIではない。Obsidianをボールトに 向ければそれで済む。

• ベクトルデータベースやセマンティック検索エンジンではない。ripgrep＋エージェントの推論で 数百件の論文までの実用はカバーできる。これが意図的である理由はビルドスペックの 非目標を参照。

• 独自のLLMルーターではない。Ollamaプラグイン（v0.2）だけが「paperloomが直接LLMを呼ぶ」 唯一の経路で、オプトイン、ヘッドレスジョブ専用。

• マルチユーザー、認証付き、SaaSではない。paperloom mcpはstdioのみ、クライアントごとに 1プロセス。

Install

まだ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

（paperloom自体をハックする場合は.の代わりにuv pip install -e . — 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を解析する際に数GBのモデル重みを ダウンロードする。ローカルPDF解析を望むならこれを回避する方法はない。 最初の実際のpaperloom ingest実行にはディスク容量と時間（理想的にはGPUも — CPUのみの解析でも動作するが大幅に遅い）を予算化しておくこと。

主に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に解析される。 IDは可能な場合、最初のページのarXiv/DOIパターンから検出され、フォールバックとして コンテンツハッシュが使われる。このステップはsources/research/には一切触れない — 取り込みとWiki執筆は意図的に分離されている。

claude "/contribute sources/raw/2301.08243"

コーディングエージェントがCLAUDE.mdを読み、計画（どのページを作成するか、 どのページを更新するか）を起草し、それをあなたに提示し、承認されるとMCPツール経由で 実際のWikiページを書く。さらに論文を追加して繰り返し、次に試す：

claude "What does my wiki know about JEPA?"

完全にデータが入ったサンプルボールトは examples/ml-robotics-vault/を参照 — ゼロから作る代わりに閲覧できる。

Architecture

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

3つのレイヤー、3つの信頼レベル：sources/raw/は忠実で決して編集されない転写。 sources/research/はエージェントの実際の判断が置かれる場所で、常にraw/を引用する。 sources/contributors/はあなた自身の日々のログで、追記のみで書き換えはされない。 完全なページ形状リファレンスはdocs/schema.mdを参照。

9つのツール

これが意図的に全リストだ — 何が意図的にコアツールでないか（セマンティック検索、 自動lint修正、マルチユーザー関連）とその理由はビルドスペックを参照。

Plugins

9つ以外のツールが必要？プラグインを書けばいい — register(mcp)を公開する Pythonモジュールで、3つの場所からロードされる（組み込み、pipエントリポイント経由の サードパーティ、またはボールトローカルの.paperloom/plugins/）。名前の衝突時は 後者が前者を上書きする。完全なガイドとリファレンスのexample_plugin.py （word_count、find_orphans）はdocs/plugins.mdを参照。

Ollama backend

ヘッドレス／スケジュールジョブ（夜間の/rebuild-context、cronの/lint）で、 ホストエージェントがセッションを積極的に駆動していない場合向けに、 uv pip install "paperloom[ollama]"でsynthツールが追加される — プロンプトを ローカルのOllamaモデルに通すもので、APIキー不要、完全オフライン。機械的な雑務に 使うこと。実際の判断は依然としてインタラクティブなホストエージェントが行う。 （v0.2 — 未構築。ビルドスペックの§17項目10として追跡中。）

MindBaseからの移行

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

sources/raw/、sources/research/、sources/contributors/、context.md、 README.md、logs/を新しいpaperloomボールトにコピー（移動ではない）し、 MindBaseのindex.yamlを信頼せずディスクからインデックスを再導出する。 （v0.2 — 未構築。ビルドスペックの§17項目9として追跡中。）

オプション：ボールトを視覚的に閲覧する

Paperloomボールトは[[wikilinks]]付きのプレーンマークダウンなので、 Obsidianがそのまま動作する：

1. Obsidianを開く → 「フォルダをボールトとして開く」→ paperloomボールトのルートを選択。

2. オプションでDataviewプラグインをインストール — YAML frontmatterはDataviewでクエリ可能。

3. Ctrl-Gでグラフビュー。

必須でも依存でもない — ファイル形式の嬉しい偶然だ。

Roadmap

計画中のプラグイン（v0.3以降、コミュニティ貢献可能）。コアツールの追加ではない：

• arxiv_watcher — 保存したクエリに一致する新しい論文をarXivからポーリング。

• marp_export — シンセシスページをMarpスライドデッキに変換。

• graph_export — [[wikilink]]グラフをGraphViz/JSONとしてエクスポート。

• citekey_lint — ドラフト成果物内の\cite{...}参照を検証。

コア（9つのツール、CLI、プラグインシステム、スキーマ）はv0.1時点で完了とみなす — CHANGELOG.mdを参照。

Contributing

CONTRIBUTING.mdを参照 — セットアップ、テストコマンド、 ビルドスペックで固定されているものと変更可能なもの。IssueとPR歓迎、特にプラグイン。

License

Apache-2.0。

Citation

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