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]

TL;DR

Paperloom은 코딩 에이전트(Claude Code, Gemci CLI, ...)에게 개인 연구 위키를 마크다운 파일 폴더에서 유지할 수 있게 하는 작은 MCP 서버 + CLI입니다. 배치 PDF 인제스트, 검색, 노트 생성, 태깅 — 이런 파일 기반 기능을 제공하면서, 실제 읽기와 추론은 모두 에이전트가 담당합니다. 일반적인 llm-wiki 구성이나 MindBase의 전역 데이터 폴더와 달리, paperloom 볼트는 한 번에 50~1000편의 논문 코퍼스를 인제스트하도록 만들어진, 자족적인 하나의 디렉터리입니다 (git init && paperloom init 하면 끝). 그리고 그 자체로 LLM API 키를 요구하지 않습니다 — 호스트 에이전트가 이미 있으니까요.

Related MCP server: ScholarMCP

Credits

Paperloom은 두 분의 어깨 위에 서 있습니다:

• Andrej Karpathy — 이 프로젝트가 구현하는 LLM-wiki 패턴을 만들어 준 분.

• Frank Chu의 MindBase — 그 패턴이 제품이 될 수 있음을 보여 준 분, 그리고 우리가 차용해 확장하는 CLAUDE.md 스키마 관례를 만들어 준 분.

Paperloom은 폴더 스코프(디렉터리당 하나의 KB, 전역 상태 없음), 배치 인제스트 우선(50~1000편의 논문 코퍼스를 위해 설계), 그리고 그 자체로 LLM API 키가 필요 없다는 점에서 다릅니다.

자세하고 전체 이야기는 dws/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로 시작하거나 그냥 위키에 무엇이 있는지 물어보세요. 전체 단계별 가이스는 dws/quickstarter.md를 보세요.

무엇인것 / 무엇이 아닌것

이것은것입니다:

• 파일 조감속 도구(search, read_page, create_note, ...)의 집합과 일괄인 PDF 접수를 위한 CLI.

• 폴더 스코프 — 모든 볼트는 자족한 원개의 디렉터리, 전역 상태 없고 디먼 없음.

• 설계상의 API 키 제로 — 호스트 코딩 에이전트가 LLM.

• 실제 코스퍼스를 위해 설계 — 일괄 인제스트, 마저 집행, 병렬 MinerU 작업, 논문 단위 실패 분섭.

이것이아닌것:

• 웹 UI가 아님. 그걸 원한다면 Obsidian을 볼트에 겨냥하세요.

• 벡트 데이터베이스나 꼼꼼 검색 엔진이 아님. Ripgarp + 에이전트의 추론이 수백 개 논문에 걸린 실세계를 담당합니다; **움직이는 이유1이 좀 쓰인 궁금하다면 빌드 스펙에 “비-목표(non-goals)” 부분을 보세요.

• 그 자체의 LLM 라우터가 아님.0.2의 Ollama 플러그인만이 “paperloom이 LLM 직점 호출한다”는 유일한 경로이며, 그마저 opt-in, 핫드 metaphor 헤들리스 잡 전용입니다.

• 멀티유저, 인증, 혹은 SaaS가 아님. paperloom mcp는 stdout 전용, 클라이언트마다 개별 프로세스하나.

Install

아직 PyPI에 발행되지 않음. 이 리포를 영음(혹은 복사)한 뒤 **uv**로 설치하세요, 강팍한 pip이 아닙니다 — 직접 vercheck 햇는데: 같은 저장소를 clean. 도중의 시행착오로, 실제 확인 결과 새 pip install .은 resolution-to-deep 오류(pip의 리설버가 mineru[core]와 medium 결합 의존성 그래프를 처리하지 못해)가 생기지만, 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괴 아닌 시스템 바이너이리(bytes):

# 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-only 파싱도 되지만 성능이 크게 낮다)을 부담하러 생각하세요.

리눅스에서 주로 테스트되었습니다; 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는 첫 페이지에서의0/DOI 패턴에서 가능할 때 구해지며, 그렇지 않는 content hash로 대체됨. 이 단계 그래피 아무것도 에 속해하지 않습니다/ — 인제스트과 위키의 작성은 의도적으로 분리되어 있습니다.

claude "/contribute sources/raw/2301.08243"

의 코드의 에이전트가 CLAUDE.md를 읽고, 어떤 페이지를 작성할지 고르고, 새 계획을 끌 체로 계획을 세우고 보여드리며, 승인이 되어 거치 위키에 도구로 실제 페이지를 기록합니다. 더 논문 넣기를 원한다면 반복, 그 다음 시도:

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

세 층레이어, 세 레벨: sources/raw/는 충실하고 편집없는 재현으로, 기절 반환이 없으며; sources/research/는 에이전트의 실제 고 사고가 있는 곳이지만 항상 raw/에 대한 인용문이; sources/contributors/는 그자신의 일상록, 추가만 가능하고 다시 쓰기에는 적합하지 않습니다. 전체 페이지에 대한 전체 스펙은 docs/schema.md 참조.

그 9가지 도구

그것이 동 목록 전체이고, 의도적입니다. 의도적으로 아닌 도구(이의검색, git obs, autolint 등)가 무엇이고 그 이유가 빌드스펙에 기술되어 있습니다.

플러그인

9가지 응공 이외의 도구가 필요? register(mcp)를 노출하는 Python 모듈인 플러그인을 쓰세요. 3곳에서 로드합니다 (내장, Corntribution via pip entry points, 혹은 볼트 local .paper/loom/plugins/), 이름 충돌은 나중 것이 먼저를 덮어버립니다. 전체 가이드와 example_plugin.py (word_count, find_orphers)에 대해서는 docs/plugins.md를 보세요.

Ollama backend

headless 스크줄(촉 /rebuild-context 또는 cron에서의 /lint)에서 실행하고 싶다면, uv pip install "paperloom[ollama]" 명령이 synth 도구를 대신 — 로컬 Ollama 그것으로 Common 프롬프트를 실행하고, 어떤 키/완 전 오프라인 입니다. 말단의 단조잡한 일(grunt work)용으로 사용하; 실제 고 판단은 여전히 상호대상 에이전트 환경에서. (v0.2 — 미구현; 빌드 스펙의 §17 항목 10으로 관리됩니다.)

MindBase에서의 이전

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

sources/raw/, sourcesresearch/, sources/contributors/, context.md, README.md, logs/를 새 paperloom 볼트로 복사함과 동시에 (옮기지 않고), MindBase의 index.yaml를 신뢰하는 대신 디스크에서부터 인덱스를 재유도함. (v0.2 — 아직 미구현; 빌드 공방의 §17 항목 9로 관리 번호)).

옵션: 볼트를 눈으로 둘러보기

Paperloom 볼트는 [[wikilinks]]가 있는 칼란 마크다운이므로 Obsidian 그대로 대처 없이 작동합니다:

1. Obsidian을 열고 → “Open folder as vault” → paperloom 볼트 루트를 선택.

2. 오셔 제공하는 Dataview 플러그인을 설치할 수 — YAML 프론트매터는 Dataview 질의할 수 있습니다.

3. 그래프 보기를 Ctrl-G.

필수도, 의존성도 아닌 그냥 파일 포맷의 행복한 일치물입니다.

Roadmap

0.3세 이후 커뮤니티 기여 플러그인 계획이며, 핵심 도구 추가가 아닙니다:

• arxiv_watcher — 저장한 논문의 arXiv 발생을 지켜봄.

• marp_export — 종합 페이지를 Marp 슬라이드 덱로 변환.

• graph_export — [[wikilink]] 그래프를 GraphViz/JSON으로 내보냄.

• citekey_lint — 초안 아티팩트의 \cite{...} 참조 검증.

핵심부 — 그 9개 도구, CLI, 플러그인 시스템, 스키마 — v0.1 시점 완결됐다고 봅니다. CHANGELOG.md를 참조하세요.

기여

CONTRIBUTING.md 참조하세요 — 설치방법, 테스트 명령, 그리고 빌드 뒤에 고정되어 있는 변경 불가 요소는 무엇이고, 바꿀 수 있는 것은 무엇인지. 이슈와 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}
}