paperloom

面向文件夹的、由 LLM 维护的研究维基。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]

摘要

Paperloom 是一个小型 MCP 服务器 + CLI，为编码代理（Claude Code、Gemini CLI 等）提供文件原语，使其能够基于一个 markdown 文件文件夹维护个人研究维基——批量 PDF 摄取、搜索、笔记创建、标签——而代理负责所有实际的阅读和推理。与通用的 llm-wiki 设置或 MindBase 的全局数据文件夹不同，paperloom 的 vault 是一个自包含的目录（git init && paperloom init 即可完成），专为一次摄取 50-1000 篇论文的语料库而设计，并且它本身从不要求 LLM API 密钥——你的宿主代理已经有一个了。

Related MCP server: ScholarMCP

致谢

Paperloom 站在两个巨人的肩膀上：

• Andrej Karpathy 提供了 LLM-wiki 模式，整个项目正是该模式的实例化。

• Frank Chu 的 MindBase 证明了该模式可以成为产品，并提供了我们借鉴和扩展的 CLAUDE.md 模式约定。

Paperloom 的不同之处在于：它面向文件夹（每个知识库一个目录，无全局状态）、批量摄取优先（专为 50-1000 篇论文的语料库设计），并且本身从不要求 LLM API 密钥。

完整故事见 docs/cred.md。

快速开始

尚未发布到 PyPI——请从源码安装（见下方 安装），然后：

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

paperloom init 不会为你创建 .mcp.json——请自行添加（每个 vault 只需一次）：

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

然后将你的编码代理指向该 vault，并以 /contribute 开始，或直接询问维基内容。完整演练见 docs/quickstart.md。

它是什么 / 不是什么

它是：

• 一组文件操作 MCP 工具（search、read_page、create_note 等）以及用于批量 PDF 摄取的 CLI。

• 面向文件夹——每个 vault 都是一个自包含目录，无全局状态，无守护进程。

• 设计上零 API 密钥——宿主编码代理就是 LLM。

• 专为真实语料库构建——批量摄取、可恢复、并行 MinerU 任务、逐论文失败隔离。

它不是：

• Web UI。如果你想要一个，请将 Obsidian 指向该 vault。

• 向量数据库或语义搜索引擎。Ripgrep + 代理推理足以覆盖数百篇论文的真实使用场景；如果你好奇为什么这是有意为之，请参阅构建规范的非目标部分。

• 自己的 LLM 路由器。Ollama 插件（v0.2）是唯一“paperloom 直接调用 LLM”的路径，且为可选，仅用于无人值守任务。

• 多用户、带认证或 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

（如果你想修改 paperloom 本身，请使用 uv pip install -e . 而不是 .——参见 CONTRIBUTING.md。）

你还需要在 PATH 中安装 ripgrep——它是一个系统二进制文件，不是 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 工作（参见构建规范自身的说明），但不是主要目标。

第一个 vault（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/——摄取和维基编写是刻意分离的。

claude "/contribute sources/raw/2301.08243"

你的编码代理读取 CLAUDE.md，起草计划（要创建哪些页面、更新哪些页面），向你展示，并在批准后通过 MCP 工具写入真实的维基页面。对更多论文重复此过程，然后尝试：

claude "What does my wiki know about JEPA?"

参见 examples/ml-robotics-vault/ 获取一个完整填充的示例 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 个工具

这就是完整列表，这是有意的——参见构建规范，了解哪些是刻意不作为核心工具的（语义搜索、自动 lint 修复、任何多用户功能）以及原因。

插件

需要 9 个工具之外的工具？编写一个插件——一个暴露 register(mcp) 的 Python 模块，从三个位置加载（内置、通过 pip 入口点的第三方、或 vault 本地的 .paperloom/plugins/），名称冲突时后者覆盖前者。完整指南和参考 example_plugin.py（word_count、find_orphans）见 docs/plugins.md。

Ollama 后端

对于无人值守/定时任务（夜间 /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 vault，从磁盘重新推导索引，而不是信任 MindBase 的 index.yaml。(v0.2——尚未构建；在构建规范 §17 第 9 项中跟踪。)

可选：以可视化方式浏览你的 vault

Paperloom vault 是带有 `[[wikilinks]] 的纯 markdown，因此 Obsidian 开箱即用：

1. 打开 Obsidian → “以 vault 形式打开文件夹”→ 你的 paperloom vault 根目录。

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——设置、测试命令，以及哪些由构建规范固定、哪些可更改。欢迎提交 issue 和 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}
}