Read math papers with evidence, not guesses.
PaperGraph v1.1.7 is the stable evidence-first reading workflow for math papers: start with a Paper Map, inspect source-backed proof and citation evidence, use Evidence Triage to understand sparse extraction, search scholarly metadata for blocked references, then export Markdown Reading Reports or Cross-Paper Reading Plans.
v1.1.6 fixed source re-import data loss and resolver input boundaries; v1.1.7 is a maintenance cleanup without workflow changes. See the v1.1.6 bugfix notes and v1.1.7 release.
It helps AI agents turn arXiv papers, local LaTeX projects, and born-digital PDFs into a local theorem-centered workspace so a researcher can inspect where every claim came from.
| Start with a Paper Map | Trace proof evidence | Resolve references | Save reading artifacts |
|---|---|---|---|
| Identify main-result candidates, result structure, proof-path evidence, and external reading risks before choosing where to read. | Inspect proof-local references, cited stops, source slices, and dependency diagnostics with explicit evidence. | Search Crossref, OpenAlex, and arXiv metadata for blocked references, then apply only a chosen candidate through the reference closure workflow. | Export deterministic Markdown reports and cross-paper reading plans that can live in Git, notes, or handoff sessions. |
PaperGraph v1.1.3 adds Scholarly Reference Resolver: low-risk online metadata search for blocked references, deterministic candidate ranking, and explicit boundary messages when the trail stops at ambiguous or non-importable records.
v1.1.4 introduced bounded reference expansion: approve a finite policy, then advance a saved run. Defaults are depth 2 and 10 new papers; unique strong importable identities can be selected automatically, while ambiguous references await review and independent branches continue. Runs retain budgets, evidence, decisions and recovery history. Only arXiv sources and explicitly supplied local PDFs are importable. It does not bypass paywalls or perform unlimited crawling.
v1.1.5 improves reference identity quality: traceable bibliography hints, conservative DOI/arXiv normalization, explicit conflicts, provider outcomes and saved matching explanations. New runs use unique_strong_v2; existing unique_strong_v1 tasks keep their legacy resolver. Back up workspaces before upgrading to schema 9; older versions cannot open them. Scores are not probabilities, and metadata agreement is not independent verification. See the release preparation notes and offline quality corpus.
See the expansion walkthrough, offline JSON, reference tree, and v1.1.5 client verification matrix. The pinned commands below install the published v1.1.7 release.
| Need | How PaperGraph behaves |
|---|---|
| "Do not invent dependencies." | PaperGraph reports evidence-backed links and explains empty results as extraction limits, not mathematical facts. |
| "Show me the exact source." | Results, proofs, dependencies, and citations carry source spans that can be sliced back out of the original paper. |
| "Let me review external papers first." | External references become import plans. Cross-paper plans separate selected-paper citation evidence from unresolved outside risks. |
| "Keep my reading state." | Workspaces store queues, sessions, checkpoints, notes, blocked targets, and open questions locally. |
PaperGraph does not verify proofs, perform semantic theorem matching, or claim that similarly worded results are equivalent.
Install uv, then verify the pinned GitHub release without cloning:
uvx --from git+https://github.com/lotchuazzz-crypto/papergraph-mcp.git@v1.1.7 papergraph-mcp --version
uvx --from git+https://github.com/lotchuazzz-crypto/papergraph-mcp.git@v1.1.7 papergraph-mcp doctorPinning the v1.1.7 tag keeps MCP client installations reproducible.
Add PaperGraph to an MCP client that accepts JSON-style stdio configuration:
{
"mcpServers": {
"papergraph": {
"command": "uvx",
"args": ["--from", "git+https://github.com/lotchuazzz-crypto/papergraph-mcp.git@v1.1.7", "papergraph-mcp"]
}
}
}Restart the MCP client after changing its configuration. The server uses stdio, so running the command without --help or --version waits quietly for an MCP client connection.
Give a coding agent this request:
I use an MCP-capable agent/client. Clone https://github.com/lotchuazzz-crypto/papergraph-mcp and help me configure PaperGraph for it. After cloning, read .agents/skills/setting-up-papergraph/SKILL.md and follow it.
Compatible agents can follow the repository-local setting-up-papergraph skill. The agent should show you a reusable PaperGraph prompt, explain why uv is needed, and ask before installing software, changing client configuration, or restarting the client.
If you do not use an MCP-capable client yet, PaperGraph can still be run from the CLI with the pinned uvx --from ... papergraph-mcp doctor command above and the workspace commands below.
If your agent clones into a directory that already exists, ask it to run git fetch --tags origin before treating the checkout as current. Existing clones can otherwise remain pinned to an old local origin/main.
For a complete first run, follow First PaperGraph Workspace. The Workspace Starter commands plan-starter-project and bootstrap-reading-project create START_HERE.md, papergraph-starter-manifest.json, Reading Reports, and a Cross-Paper Reading Plan from explicit paper inputs. For the stable surface, see PaperGraph v1 Core Contract and the v1 Release Checklist. Example outputs are available as a Reading Report, a Cross-Paper Reading Plan, a Reference Search, a Reference Resolution, a Starter Summary, and a Starter Manifest.
For raw user requests, prefer load_arxiv_request(input=...) or papergraph-mcp load-arxiv-request "...". These high-level entry points validate bare IDs, URLs, Markdown links, and prose before loading. To inspect the decision without loading, call validate_arxiv_request or papergraph-mcp validate-arxiv-request "...". If validation returns action: ask_user_to_choose, ask the user to choose; detecting a conflict and then continuing is a failure. Use load_arxiv_paper only after the user has provided one already-disambiguated arXiv ID.
flowchart LR
Paper[Paper] --> Results[Extract results]
Results --> Evidence[Inspect proof evidence]
Evidence --> Path[Build reading path]
Path --> Queue[Create reading queue]
Queue --> Imports[Review external import plan]
Queue --> Session[Resume reading session]
- Load a paper from arXiv, local LaTeX, or PDF.
- List theorem-like results and choose a target theorem.
- Inspect the theorem statement, proof evidence, source slice, and dependency diagnostics.
- Generate a reading queue from local proof evidence.
- Export a single-paper Reading Report when you want a durable Markdown handoff.
- For a few related papers, export a Cross-Paper Reading Plan to see selected-paper citation evidence and remaining risks.
- Save checkpoints and notes so the next reading session starts from known state.
| It does | It does not |
|---|---|
| Extract and store evidence from papers. | Prove the paper is correct. |
| Follow explicit labels, proof-local references, and citation evidence. | Guess hidden mathematical prerequisites. |
| Build reviewable reading queues and import plans. | Automatically crawl the literature. |
| Keep local reading state in SQLite. | Upload private manuscripts or PDFs. |
| 先看 Paper Map | 追踪证明证据 | 保存阅读产物 | 跨论文规划 |
|---|---|---|---|
| 在选择阅读目标前，先看到 main-result candidates、结果结构、proof-path evidence 和 external reading risks。 | 查看 proof-local references、citation stops、source slices 和 dependency diagnostics，并保留证据来源。 | 导出确定性的 Markdown report，方便放进 Git、笔记或交接会话。 | 对一组显式给定的小规模相关论文，导出跨论文阅读计划、选中论文之间的 citation evidence 和剩余风险。 |
PaperGraph v1.1.7 是稳定的 evidence-first 数学论文阅读工作流：先看 Paper Map，再检查 proof 和 citation 证据，用 Evidence Triage 理解稀疏抽取结果，对被阻塞的外部引用做 scholarly metadata 搜索，然后把选定候选闭环到用户确认的 arXiv、本地 PDF、DOI、URL 或出版信息。
v1.1.6 修复了重新导入时丢失阅读数据及引用解析输入边界；v1.1.7 仅做维护清扫，不改变既有工作流。下方安装命令固定到已发布的 v1.1.7；参见 v1.1.6 修复说明 和 v1.1.7 Release。
v1.1.4 引入有界引用扩展：默认最多追踪 2 层、导入 10 篇新论文。v1.1.5 进一步改善引用身份匹配：保留解析证据，审慎规范化 DOI/arXiv，明确冲突、服务状态和选择理由。新任务默认 unique_strong_v2，已有 unique_strong_v1 任务保持旧行为。升级到 schema 9 前请备份 workspace，旧版本无法打开新 schema。分数不是概率，多来源元数据一致也不代表独立验证。只支持 arXiv 源码和明确提供的本地 PDF，不绕过付费墙。见完整操作示例及客户端验证状态。
| 研究者关心的问题 | PaperGraph 的回答 |
|---|---|
| 不要猜依赖。 | 只报告有证据的链接；空依赖结果解释为抽取限制，而不是数学事实。 |
| 我要看到原文位置。 | result、proof、dependency、citation 都尽量保留 source span，可回到原文片段。 |
| 外部论文先让我审。 | 外部引用先变成 import plan；跨论文计划会区分选中论文之间的 citation evidence 和仍在外部的 unresolved risks。 |
| 阅读项目要能继续。 | workspace 在本地保存 queue、session、checkpoint、note、blocked target 和 open question。 |
PaperGraph does not verify proofs，也不做 semantic theorem matching；它不会声称两个措辞相似的结果数学上等价。
先安装 uv，然后验证固定版本：
uvx --from git+https://github.com/lotchuazzz-crypto/papergraph-mcp.git@v1.1.7 papergraph-mcp --version
uvx --from git+https://github.com/lotchuazzz-crypto/papergraph-mcp.git@v1.1.7 papergraph-mcp doctor如果你的 MCP client 使用 JSON 风格的 stdio server 配置，可以添加：
{
"mcpServers": {
"papergraph": {
"command": "uvx",
"args": ["--from", "git+https://github.com/lotchuazzz-crypto/papergraph-mcp.git@v1.1.7", "papergraph-mcp"]
}
}
}修改配置后重启 MCP client。这个 server 使用 stdio，所以不带 --help 或 --version 直接运行时，会安静等待 MCP client 连接。
你可以把这段话发给 coding agent：
我使用的是支持 MCP 的 agent/client。请克隆 https://github.com/lotchuazzz-crypto/papergraph-mcp，并帮我把 PaperGraph 配置进去。克隆后请先阅读 .agents/skills/setting-up-papergraph/SKILL.md 并按它执行。
支持本仓库 skill 的 agent 会读取 setting-up-papergraph，展示可复用提示词，解释为什么需要 uv，并在安装软件、修改客户端配置或重启客户端前询问你。
如果你暂时没有支持 MCP 的 client，也可以先用 CLI：运行上方固定版本的 uvx --from ... papergraph-mcp doctor 和下方 workspace 命令。
如果目标目录已经存在，请让 agent 先运行 git fetch --tags origin，再判断仓库是否是最新。否则已有 clone 可能仍停留在旧的本地 origin/main。
第一次完整使用可以跟着 First PaperGraph Workspace 走。稳定承诺见 PaperGraph v1 Core Contract，发布前检查见 v1 Release Checklist。示例输出见 Reading Report、Cross-Paper Reading Plan、Reference Search 和 Reference Resolution。
普通用户请求优先走 load_arxiv_request(input=...) 或 papergraph-mcp load-arxiv-request "..."。这些入口会在加载前验证 bare IDs、URLs、Markdown links 和自然语言描述。若验证返回 action: ask_user_to_choose，必须让用户选择；detecting a conflict and then continuing is a failure。Use load_arxiv_paper only after 用户已经给出单一、无歧义的 arXiv ID。
- 从 arXiv、本地 LaTeX 或 PDF 加载论文。
- 列出 theorem-like results，选择目标定理。
- 查看 theorem statement、proof evidence、source slice 和 dependency diagnostics。
- 根据本地 proof evidence 生成 reading queue。
- 需要持久交接时，导出单篇 Reading Report。
- 面对几篇相关论文时，导出 Cross-Paper Reading Plan，查看选中论文之间的 citation evidence 和剩余风险。
- 保存 checkpoints 和 notes，下次继续读时不必从头开始。
Complete Tool Reference
| Workflow | Main tools |
|---|---|
| Load papers | open_workspace, workspace_add_local_paper, workspace_add_arxiv_paper, workspace_add_pdf_paper, workspace_list_papers, workspace_get_paper |
| Start a project | workspace_plan_starter_project, workspace_bootstrap_reading_project |
| Map papers | workspace_get_paper_map, workspace_export_paper_reading_report, workspace_export_cross_paper_reading_plan |
| Inspect results | workspace_list_results, workspace_get_result, workspace_get_result_proof, workspace_get_proof_dependencies, workspace_get_external_result_mentions, workspace_get_evidence, workspace_get_citations, workspace_search_theorems |
| Read a proof | workspace_export_reading_bundle, workspace_export_result_reading_context, workspace_get_source_slice, workspace_get_result_reading_path |
| Resume reading | workspace_create_reading_session, workspace_list_reading_sessions, workspace_get_reading_session, workspace_record_reading_checkpoint, workspace_add_reading_note, workspace_export_reading_session_summary |
| Plan reading | workspace_create_reading_queue, workspace_list_reading_queues, workspace_get_reading_queue, workspace_apply_reading_queue_to_session |
| Resolve references | workspace_plan_external_imports_for_result, workspace_plan_external_imports_for_queue, workspace_plan_external_imports_for_paper, workspace_search_external_reference, workspace_list_external_reference_searches, workspace_resolve_external_reference_candidate, workspace_resolve_external_reference, workspace_list_external_reference_resolutions |
Original single-paper tools: get_environment_diagnostics, validate_arxiv_request, load_arxiv_request, validate_arxiv_input, load_paper, load_arxiv_paper, list_theorems, get_theorem, get_dependencies, get_dependency_diagnostics, and where_used.
Complete workspace tool index: open_workspace, workspace_add_local_paper, workspace_add_arxiv_paper, workspace_list_papers, workspace_get_paper, workspace_search_theorems, workspace_get_dependencies, workspace_get_dependency_diagnostics, workspace_get_citations, workspace_add_pdf_paper, workspace_get_paper_map, workspace_export_paper_reading_report, workspace_export_cross_paper_reading_plan, workspace_plan_starter_project, workspace_bootstrap_reading_project, workspace_list_results, workspace_get_result, workspace_get_result_proof, workspace_get_proof_dependencies, workspace_get_external_result_mentions, workspace_get_evidence, workspace_export_reading_bundle, workspace_export_result_reading_context, workspace_get_source_slice, workspace_get_result_reading_path, workspace_create_reading_session, workspace_list_reading_sessions, workspace_get_reading_session, workspace_record_reading_checkpoint, workspace_add_reading_note, workspace_export_reading_session_summary, workspace_create_reading_queue, workspace_list_reading_queues, workspace_get_reading_queue, workspace_apply_reading_queue_to_session, workspace_plan_external_imports_for_result, workspace_plan_external_imports_for_queue, workspace_plan_external_imports_for_paper, workspace_search_external_reference, workspace_list_external_reference_searches, workspace_resolve_external_reference_candidate, workspace_resolve_external_reference, workspace_list_external_reference_resolutions.
CLI Shortcuts
Most workspace operations are available from the CLI with --workspace:
papergraph-mcp validate-arxiv-request "[math/0307200](https://arxiv.org/abs/2609.01574)"
papergraph-mcp plan-starter-project --workspace .\papergraph.sqlite3 --artifact-dir .\papergraph-starter --pdf .\paper-a.pdf=local:paper-a
papergraph-mcp bootstrap-reading-project --workspace .\papergraph.sqlite3 --artifact-dir .\papergraph-starter --pdf .\paper-a.pdf=local:paper-a --no-queue --no-session
papergraph-mcp get-paper-map --workspace .\papergraph.sqlite3 --paper-id local:paper-a
papergraph-mcp export-paper-reading-report --workspace .\papergraph.sqlite3 --paper-id local:paper-a
papergraph-mcp export-paper-reading-report --workspace .\papergraph.sqlite3 --paper-id local:paper-a --output report.md
papergraph-mcp export-cross-paper-reading-plan --workspace .\papergraph.sqlite3 --paper-id local:paper-a --paper-id arxiv:2401.12345 --output cross-paper-plan.md
papergraph-mcp export-reading-bundle --workspace .\papergraph.sqlite3 --paper-id local:paper-a
papergraph-mcp export-result-reading-context --workspace .\papergraph.sqlite3 --result-id local:paper-a::thm:main
papergraph-mcp get-source-slice --workspace .\papergraph.sqlite3 --result-id local:paper-a::thm:main
papergraph-mcp get-result-reading-path --workspace .\papergraph.sqlite3 --result-id local:paper-a::thm:main
papergraph-mcp create-reading-session --workspace .\papergraph.sqlite3 --paper-id local:paper-a
papergraph-mcp record-reading-checkpoint --workspace .\papergraph.sqlite3 --session-id SESSION --target-kind result --target-id local:paper-a::thm:main --status reviewed
papergraph-mcp add-reading-note --workspace .\papergraph.sqlite3 --session-id SESSION --text "Need to check the cited fixed point theorem."
papergraph-mcp export-reading-session-summary --workspace .\papergraph.sqlite3 --session-id SESSION
papergraph-mcp create-reading-queue --workspace .\papergraph.sqlite3 --result-id local:paper-a::thm:main
papergraph-mcp list-reading-queues --workspace .\papergraph.sqlite3
papergraph-mcp get-reading-queue --workspace .\papergraph.sqlite3 --queue-id QUEUE
papergraph-mcp apply-reading-queue-to-session --workspace .\papergraph.sqlite3 --queue-id QUEUE --session-id SESSION
papergraph-mcp plan-external-imports-for-result --workspace .\papergraph.sqlite3 --result-id local:paper-a::thm:main
papergraph-mcp plan-external-imports-for-queue --workspace .\papergraph.sqlite3 --queue-id QUEUE
papergraph-mcp plan-external-imports-for-paper --workspace .\papergraph.sqlite3 --paper-id local:paper-a
papergraph-mcp search-external-reference --workspace .\papergraph.sqlite3 --paper-id local:paper-a --blocked-id BLOCKED
papergraph-mcp list-external-reference-searches --workspace .\papergraph.sqlite3 --paper-id local:paper-a
papergraph-mcp resolve-external-reference-candidate --workspace .\papergraph.sqlite3 --paper-id local:paper-a --blocked-id BLOCKED --candidate-id CANDIDATE --import-target
papergraph-mcp resolve-external-reference --workspace .\papergraph.sqlite3 --paper-id local:paper-a --blocked-id BLOCKED --doi 10.1000/example --title "Published target"
papergraph-mcp resolve-external-reference --workspace .\papergraph.sqlite3 --paper-id local:paper-a --blocked-id BLOCKED --pdf .\reference.pdf=local:reference
papergraph-mcp list-external-reference-resolutions --workspace .\papergraph.sqlite3 --paper-id local:paper-aFor a compact single-paper check with an already-disambiguated ID, call load_arxiv_paper(arxiv_id="math/0307200"). For ordinary user text, call load_arxiv_request(input="math/0307200"). PaperGraph selects main.tex; a representative first response has "path": "main.tex", "cached": false, and "nodes": 7.
Evidence Boundaries
PaperGraph v0.4.4 dependency traversal uses statement_explicit_latex_refs_only: it follows explicit LaTeX references such as \ref, \eqref, \autoref, \cref, and \Cref inside theorem-like statements. An empty dependency result means PaperGraph found no resolvable theorem-label references under that rule. It is not evidence that the theorem has no mathematical dependencies.
Proof dependency extraction is evidence-scoped. PaperGraph looks inside TeX proof environments, direct proof continuations, and short text immediately following a theorem-like result, including evidence tied to the immediately preceding result. It reports explicit references, simple inferred local references, and unresolved mentions separately. It does not infer unstated mathematical prerequisites.
Kind metadata is intentionally explicit:
raw_kind: what the source extractor found.display_kind: the user-facing type label.normalized_kind: the stable grouping key used by tools.
Local Three-Paper Walkthrough
The repository includes a small fixture under tests/fixtures/workspace_tex_project/. A typical local demo imports paper_a, paper_b, and paper_c, then searches for fixed point:
workspace_search_theorems("fixed point")returnslocal:paper-a::thm:main,local:paper-b::thm:main, andlocal:paper-c::thm:main.workspace_get_citations("local:paper-a", direction="outgoing", include_unresolved=True)reports citation keysabsent,missing, andpaper-b.- The
paper-bcitation has cited arXiv ID2401.12346, but it does not resolve tolocal:paper-b; the row keepstarget_paper_id: null. - To create a resolved target, the cited arXiv ID is imported with
workspace_add_arxiv_paper. A local paper with a similar bibliography entry is not enough; citation resolution is based on explicit cited arXiv ID evidence.
Safety, Privacy, And Limits
PaperGraph only constructs remote downloads from arXiv's fixed e-print endpoint; arbitrary URLs are not accepted for downloads. Scholarly reference search queries public metadata services and records candidates before any resolution/import is applied. It limits compressed responses to 100 MiB, expanded content to 500 MiB, and archives to 10,000 members. Absolute paths, parent traversal, symbolic links, hard links, devices, FIFOs, and other special archive members are rejected.
Workspaces are ordinary local SQLite files. Local PDFs remain local. Extracted PDF text, source spans, and proof evidence are written only to the workspace you choose. Do not commit databases, private manuscripts, cache data, credentials, tokens, generated distributions, or raw local logs.
PDF extraction is best for born-digital PDFs; scanned PDFs or OCR-heavy files may produce sparse text and missing evidence. Complex projects may need an explicit main_file; the parser is not a full TeX engine.
Release Highlights
- v1.1.3 adds Scholarly Reference Resolver: metadata search across Crossref, OpenAlex, and arXiv for blocked references, deterministic candidate ranking, candidate apply through Reference Import Closure, and explicit boundaries for ambiguous, old, paywalled, or metadata-only literature.
- v1.1.2 adds Reference Import Closure: user-confirmed arXiv and local PDF imports for blocked references, DOI, URL, and published metadata records for non-importable targets, and regenerated reading reports after successful imports.
- v1.1.1 adds Evidence Triage for first-use Reading Reports and Starter artifacts, with candidate-start labels, sparse dependency status, external blocker next actions, and unchanged evidence boundaries.
- v1.1.0 adds Workspace Starter planning and bootstrap commands for
START_HERE.md,papergraph-starter-manifest.json, Reading Reports, and Cross-Paper Reading Plans from explicit paper inputs. - v1.0.0 released the stable PaperGraph core: Paper Map, Reading Report, Cross-Paper Reading Plan, first-workspace onboarding, and the v1 evidence contract.
- v0.13.0 added the v1.0 readiness pass with stable core contract docs, first-workspace walkthroughs, and example Reading Report/Cross-Paper Reading Plan artifacts.
- v0.12.0 added Cross-Paper Reading Plan, a deterministic Markdown artifact for explicit paper sets with recommended sequence, selected-paper citation evidence, external risks, and evidence boundaries.
- v0.11.0 added Reading Report Export, a deterministic Markdown artifact with Paper Map context, main-result candidates, reading route, external risks, and evidence boundaries.
- v0.10.0 added Paper Map, an evidence-first first-load overview with main-result candidates, structure, reading route, and external-risk evidence.
- v0.9.3 added external import review summaries.
- v0.9.2 improved cited-result mention extraction.
- v0.9.1 added proof-adjacent dependency evidence.
- v0.9.0 introduced reading queues, sessions, and external import planning.
- v0.4.0 introduced cross-paper SQLite workspaces with
workspace_add_arxiv_paper,workspace_search_theorems, andworkspace_get_citations. Resolution remains explicit, not semantic.
Development
uv sync
uv run pytest -q -p no:cacheproviderThe automated suite uses synthetic archives, projects, bibliography entries, and PDFs. It does not require the live arXiv service.
Bug reports, research-reading workflows, reproducible fixtures, and PRs are welcome. Please read Contributing before submitting changes. PaperGraph is released under the MIT License.