AutoGineer
Generated banner for DeepPaperNote
Generated logo for DeepPaperNote

DeepPaperNote

Agent plugin

First committed by 917Dhj

Published in 917Dhj/DeepPaperNote. Publisher page

1,348 GitHub stars

What it is

Turn one dense paper into an Obsidian note worth keeping: read the way its field reads it, linked to the papers already in your vault, and aimed at your own research. Agent skills for Claude Code, Codex, Cursor, and any agent that supports skills.
— the description by 917Dhj

AutoGineer overview, from the brain’s own files

DeepPaperNote is an agent-based skill designed to streamline the academic reading process by converting complex research papers into durable, high-quality Obsidian notes. It functions as an expert reader that extracts core information, figures, tables, and formulas, organizing them into a structured format tailored to the specific type of paper (e.g., method, survey, benchmark). The system ensures accuracy by grounding conclusions directly in the source text and performing independent quality checks before saving. It integrates seamlessly into an existing Obsidian vault, linking new notes to related research and allowing users to maintain a growing, interconnected academic wiki. The tool supports various input formats including DOIs, arXiv IDs, and local PDFs, and offers optional enhancements like Zotero integration and OCR for scanned documents.

How it works

Memory model: Not stated

AutoGineer overview, from the brain’s own files

The tool operates as a skill for AI agents like Claude Code or Codex. Upon receiving a request with a paper identifier or file, the agent reads the document, extracts relevant content, and processes figures and tables. It then generates a structured Markdown note with sections for core information, methodology, evidence, and takeaways. The note is saved into the user's Obsidian vault, typically within domain-specific folders, and includes structured properties for filtering. Companion skills are available to manage research memory, organize the library, and build a glossary of terms.

Folders
FolderRoleFiles
.githubagent-config3
assetsattachments5
docsdocs1
scriptsscripts1
skillsagent-instructions108
teststests50
.claude-pluginfolder2
.codex-pluginfolder1
evalsfolder73

Requirements

Runtimes: Python >=3.10

API keys (by name): SEMANTIC_SCHOLAR_API_KEY

Works with: Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Kiro, OpenCode, Amp, Cline, JetBrains Junie, Devin (ex-Windsurf)

Set it up

  1. Not scanned by AutoGineerThe author’s README also describes installing it as a Claude Code plugin marketplace. Read its install section: AutoGineer did not scan that path. https://github.com/917Dhj/DeepPaperNote/blob/9670b1bffbd7732caf19acafac076ff6730bd714/README.md#1-install

  2. First committed by 917Dhj. Published in 917Dhj/DeepPaperNote. Licence: MIT License.

Usage

AutoGineer overview, from the brain’s own files

  • Generate a deep-reading note for a specific paper using its title, DOI, or arXiv ID.
  • Automatically link new paper notes to existing research in an Obsidian vault.
  • Build and maintain a research memory that tracks personal research directions.
  • Organize an existing paper library by fixing domain categories and tags.
  • Create a glossary of key concepts extracted from research papers.
  • Check the environment and dependencies for the agent skill.
“Generate a deep-reading note for this paper: [arXiv ID]”
The agent reads the paper, extracts key findings and figures, and saves a structured Markdown note into the user's Obsidian vault.
“Organize my paper library”
The agent sorts papers into domain categories and fixes domain tags within the Obsidian vault.
“Build my research memory”
The agent records the user's research directions to tailor future note takeaways.
“Build glossary notes for this paper”
The agent identifies key terms in the paper and creates reusable term notes linked back to the paper text.

Documentation by 917Dhj

<div align="center">

DeepPaperNote

Turn one complex paper into an Obsidian note you will actually want to keep.

English | 简体中文

Image: Homepage Image: Release Image: License Image: Agents Image: Output

</div>

Image: DeepPaperNote Hero

<p align="center"> <em>Read one paper deeply. Add one durable page to your academic wiki.</em> </p>

When you study an important paper, the hard part is rarely the reading. It is turning what you understood into a note you can still use later. Finding the source, matching figures to the text, copying numbers over, and tracing the method often take the better part of a day. And the papers you have read end up scattered, with nothing connecting one to another.

DeepPaperNote is an agent skill that runs in Claude Code, Codex, and any other agent that supports skills. Hand it a paper, and it reads the full text, writes an illustrated deep-reading note, saves it into your Obsidian vault, and links it to the other papers you have read. Every paper you read grows your academic wiki a little.

  • 🚀 One sentence, one note. No prompts to learn, no templates to set up. Say "Generate a deep-reading note for this paper" with a title, DOI, arXiv ID, or PDF, and it finds the paper, reads it in full, extracts the figures, and saves the note into your vault.

  • 🎓 Reads like a domain expert. From CS and AI to medicine, psychology, and the humanities, from new methods and benchmarks to surveys and clinical trials, your papers can all go to DeepPaperNote. Each of 10 paper types gets its own way of reading, drawn from more than 50 reviewer guidelines and reporting standards such as the NeurIPS review criteria and CONSORT, and tested on 34 real papers.

  • 🎯 Accurate and complete. Every conclusion traces back to the paper, numbers come straight from its text and tables, and every main experiment is covered. When the paper does not report something, the note says so instead of guessing. Before saving, every note goes through an independent review and a strict quality check, and when the full text cannot be read, it never makes one up.

  • 🖼️ Figures, tables, and formulas in the text. Figures and tables are cropped from the PDF and placed right where the note discusses them, and key formulas render in Obsidian. No more flipping back to the PDF.

  • 🧠 A vault that knows you better the more you use it. Each note links to related papers in your vault and goes into the domain folders you already use. Record your research directions, and each note's Takeaways tell you what the paper means for your own work.

📰 News

  • [v3.0.0] 🎓 Notes read each paper by its type: 10 paper types each get their own way of reading and note structure, every figure is visually reviewed before it enters the note, and an independent quality review runs before saving. Release notes

  • [v3.0.0] 🧠 Every note joins your vault: notes gain Takeaways and Connections sections and carry structured properties, and two new skills, research-memory and organize-wiki, tailor the takeaways to your research directions and keep your domain folders in order.

  • [v2.3.1] 🔌 Added support for DeepPaperNote Connector: papers you save from your browser can get their notes in the same paper directory. Release notes

News lists only the three most recent user-facing milestones. See the changelog and GitHub Releases for the full history.

🚀 Quick Start

1. Install

Claude Code: install from the plugin marketplace

claude plugin marketplace add 917Dhj/DeepPaperNote
claude plugin install deeppapernote@deeppapernote

Codex and other agents that support skills: install with the skills CLI

npx skills add 917Dhj/DeepPaperNote

The plugin installs all four skills at once. The skills CLI lets you choose which skills to install and which agents receive them. To try it out, deeppapernote alone is enough; see below for what the other three do.

2. Install the PDF dependency
python3 -m pip install PyMuPDF

Python 3.10 or newer is required. If you use uv, run uv pip install PyMuPDF in the Python environment DeepPaperNote will use.

3. Read a paper

Tell your agent in one sentence, with the paper's title, DOI, URL, arXiv ID, or local PDF:

Generate a deep-reading note for this paper: <paper>
Turn this paper into an Obsidian note: <paper>

You can also call it with the slash command /deeppapernote <paper>.

The first time, it asks you two things: whether notes should be in English or Chinese, and whether to save them in the current workspace or your Obsidian vault. It remembers your answers and does not ask again. To use a different language or location for one paper, just say so in the request. For environment variables and other settings, see User Configuration.

4. Update to a new version

Claude Code:

claude plugin marketplace update deeppapernote
claude plugin update deeppapernote@deeppapernote

Restart Claude Code to apply the update.

skills CLI:

npx skills update

👀 What a Note Looks Like

Image: A DeepPaperNote deep-reading note for Attention Is All You Need

Every note has three parts: the opening and closing are the same for every paper, and the body in between follows the paper's type.

PartSections
OpeningCore Information · Abstract · Contributions · One-Sentence Summary
BodyMethod paper: Background and Problem → Limitations of Prior Work → Key Idea and Challenges → Method → Experimental Evidence → Deep Analysis<br>Benchmark: Evaluation Gap → Task and Design Goals → Construction and Quality Control → Evaluation Framework → Findings → What It Really Measures<br>Survey: Scope and Search → Taxonomy → Directions → Consensus, Disagreement, and Gaps<br>…10 paper types in all
ClosingLimitations · Takeaways · Connections · My Notes

The closing sections are where the note meets your vault:

  • Takeaways: Transferable Ideas and Next Steps, covering which of the paper's ideas carry over to other problems and what to do after reading it. Once you set up research memory, this part is written against your own research directions.

  • Connections: links to related paper notes in your vault, and the key prior work you need to understand this paper.

  • My Notes: yours to write in, and kept exactly as it is when the note is regenerated.

<details> <summary><b>What appears in your vault after saving</b></summary>

Each paper gets its own folder, and figures and tables are named after their labels in the paper:

<your papers folder>/
└── NLP/                       ← domain folder, reusing the ones you already have
    └── Attention_Is_All_You_Need/
        ├── Attention_Is_All_You_Need.en.md
        └── images/
            ├── figure_1.png
            └── table_2.png

Each note opens with structured properties you can query and filter with Obsidian Bases, for example to list every benchmark paper you have read, or everything you read this month:

paper_type: benchmark_or_dataset
methods: [...]
datasets: [...]
tasks: [...]
read_date: 2026-11-08

</details>

🧩 From Paper to Wiki

DeepPaperNote reads each paper deeply and saves it well. The other three skills are optional companions that look after your vault as a whole.

SkillWhat it does for youHow to call it
deeppapernoteCore. Deep-reads one paper and saves an illustrated note into your vault, linked to the other papers you have read."Generate a deep-reading note for this paper: <paper>"<br>or /deeppapernote
research-memoryKeeps a research memory for you: it records the research directions you are working on and follows them as you read. With it, DeepPaperNote writes each note's Takeaways against your directions, so the next note knows you better."Build my research memory"<br>or /research-memory
organize-wikiOrganizes your vault: it sorts out the domain categories, moves papers filed under the wrong domain, and fixes their domain tags. The categories it settles become what DeepPaperNote follows when it files new papers."Organize my paper library"<br>or /organize-wiki
paper-glossaryBuilds a glossary for your vault: it turns a paper's key concepts into reusable term notes and links them back into the paper's text. The same term in different papers points to the same term note."Build glossary notes for this paper"<br>or /paper-glossary

A good rhythm: read a few papers with DeepPaperNote first; once your vault has some notes, build a research memory; when the papers pile up and the categories start to drift, organize the vault.

✅ Notes You Can Trust

  • A deep read, not a summary. Every note answers all the core questions of its paper type, and states plainly where the paper does not report something.

  • Grounded in the paper. Conclusions and numbers in the note come from the paper itself, with nothing invented or guessed.

  • No full text, no note. If only the abstract is available, it stops and asks you for the paper instead of handing over a note that only looks complete.

  • Every figure is checked. Each figure and table is visually reviewed before it enters the note; a crop that is incomplete or does not match the text stays out.

  • A final check before saving. An independent review checks the note for errors and omissions, and the note is fixed before it is saved.

  • Your existing notes are safe. An existing note is never silently overwritten, and regenerating a note keeps its My Notes section exactly as it is.

More than words: we run regression tests on 34 real papers covering all 10 paper types, and in a blind evaluation on 6 sample papers with our internal rubric, the average score rose from 73.6 to 84.2 (out of 100) after the type-specific redesign.

🔧 Optional Enhancements

DeepPaperNote reads ordinary digital PDFs without any of these. Add them as you need:

EnhancementWhat it does for youHow to turn it on
DeepPaperNote ConnectorSaves a paper from your browser into your Obsidian paper library in one click, so its note can later be written in the same folderInstall the browser extension; it currently supports Chrome on macOS
ZoteroUses the item and PDF already in your Zotero library, with no searching or downloading againIn Zotero 7, open Settings → Advanced and check "Allow other applications on this computer to communicate with Zotero"; it is used automatically from then on
Semantic Scholar API keyFinds the right title, authors, and venue even for papers that are hard to identifySet the environment variable SEMANTIC_SCHOLAR_API_KEY
OCRRecovers the text of scanned or poor-quality PDFsInstall Tesseract and pytesseract

For any of these, you can also ask your agent to check your environment and set it up for you.

🛠️ Troubleshooting

When something goes wrong, the easiest fix is to ask your agent:

  • Installed, but it does not work: say "Check DeepPaperNote's environment." It tells you what is missing, covering Python and PyMuPDF, your Obsidian settings, and optional enhancements such as Zotero and OCR.

  • A note stopped partway or was not saved: say "Where did this DeepPaperNote run stop?" It tells you where it got stuck, what is missing, and what to do next.

Intermediate files are kept under ~/.deeppapernote/runs/, one directory per paper, and are not cleaned up automatically. Delete them by hand if they take up too much space.

If that does not solve it, please open an issue.

🧭 Inspirations

DeepPaperNote was influenced by projects that take paper reading, evidence extraction, and note generation seriously, especially:

🤝 Contributing

Pull requests should target develop, not main. Before submitting, run the tests and lint locally:

python3 -m pip install -e '.[dev]'
python3 -m pytest -q -n auto
python3 -m ruff check skills tests

The workflow is defined in skills/deeppapernote/SKILL.md. Changes that may affect note quality should be evaluated with evals/regression-workflow.md and evals/note-quality-rubric.md.

Star History

Image: Star History Chart

<p align="center"> <em>Thanks for reading, using, and supporting DeepPaperNote. May your paper-reading days be a little clearer, calmer, and more rewarding.</em> </p>

<p align="center"> <a href="./LICENSE">MIT License</a> &copy; <a href="https://github.com/917Dhj">917Dhj</a> </p>

CHANGELOG.md

Changelog

This file tracks notable release-level changes to DeepPaperNote.

It is not intended to record every small edit, wording tweak, or internal refactor. Add an entry here when the project meaningfully changes for users, for example:

  • a new capability is added

  • a new workflow becomes officially supported

  • a new integration or interface is introduced

  • a release changes how users install, run, or rely on the skill

Unreleased

v3.0.0

DeepPaperNote now reads each paper by its type, and every note joins your vault.

Added

  • Reading by paper type. Each paper is read as one of ten types: method, system, theory, position, benchmark or dataset, discovery empirical, human-subjects empirical, survey or review, qualitative empirical, and humanities argument. The type decides the note's middle sections, the core questions it must answer, and its workflow table. The questions draw on reviewer guidelines and reporting standards such as those of NeurIPS, ICLR, ACL, CONSORT, and PRISMA.

  • Takeaways follows Limitations, with Transferable Ideas and Next Steps.

  • My Notes now belongs to you: a new note holds only a guidance line, and regenerating the note keeps whatever you wrote there.

  • Connections replaces References. It links the note to related paper notes already in your vault, whether the paper cites them or not, and lists the key prior work instead of copying the bibliography.

  • Structured frontmatter on every note (paper_type, methods, datasets, tasks, read_date, and more). The keys stay in English in both languages, so one Obsidian Bases view can query every note.

  • research-memory is a new companion skill that keeps a note of your research directions. DeepPaperNote reads it to tailor each note's Takeaways to your research.

  • organize-wiki is a new companion skill that organizes the paper library with you. It agrees on the domain folders and writes them as <Vault>/DeepPaperNote/domains.md. After you confirm a preview, it moves misfiled paper folders, fixes papers/ tags, and rewrites path links. Every reorganization is logged and the last one can be undone.

  • DeepPaperNote can now be installed as a Claude Code plugin from the repository's own marketplace, with claude plugin marketplace add 917Dhj/DeepPaperNote. The skills CLI (npx skills add) remains the agent-neutral route.

  • Visual Review. Every figure and table candidate is reviewed visually before it enters the note, and one that does not hold up is left out with a recorded reason.

  • run_state.py status reports a run's progress, missing artifacts, and next step, without changing anything.

Changed

  • Notes are written as one story for a reader from an adjacent field, and the final review checks that story along with the answers to the core questions.

  • The final quality review is now a required gate: Formal Save refuses a note that has not passed it.

  • The agent now chooses each new paper's domain folder after reading what the existing domains hold, or the user's convention in <Vault>/DeepPaperNote/domains.md. It reuses an existing domain by default and creates a new one only with a stated reason, which the final report repeats. The keyword table domain_rules.yaml is removed.

  • A saved note carries exactly one papers/<domain> tag, and it must name the folder the note is saved in.

  • Images saved in the vault are named after their label in the paper, such as figure_1.png.

  • When a glossary library shares the vault, DeepPaperNote suggests running paper-glossary on the paper after saving.

  • Regenerating a note replaces a re-cropped image of the same name instead of refusing the save.

Fixed

  • Figure and table extraction, now checked against a 34-paper regression corpus: captions are read from the page layout; crops stay in their column and keep every table row; bilingual table captions and figures printed under their caption crop correctly; footnote marks no longer end up in captions.

  • Title detection no longer mistakes a journal header or a split subtitle for the title, and keeps lead-ins such as Position:.

  • A PDF whose text cannot be read now stops the run instead of producing a note.

  • Script output no longer fails on Windows consoles with encodings such as cp1252.

  • paper-glossary now links terms written in backticks.

  • The Chinese style check no longer counts formulas and backticked names.

Upgrade notes

  • Notes saved by earlier versions keep their old structure until you regenerate them. When a regenerated note keeps an old 我的笔记 section, the save report says it may hold text the model wrote, so you can check it.

  • domain_rules.yaml is removed. To shape how papers are filed, use organize-wiki, which writes <Vault>/DeepPaperNote/domains.md.

Internal

  • The pipeline runs in separate acquire and prepare phases, common.py is split by responsibility, and CI runs ruff and the parallel test suite on Linux, macOS, and Windows.

Documentation

  • Rewrote both READMEs around what users get from DeepPaperNote.

v2.3.1

Improved

  • Papers collected with DeepPaperNote Connector can now be read and saved as notes in the same Obsidian paper directory.

  • DeepPaperNote can reuse PDFs already in the Vault and follow an explicitly requested arXiv version, reducing repeated downloads.

  • Different PDF versions of one paper can have separate notes and figures in the same directory, while existing notes, filenames, and links are preserved.

  • When it is unclear which paper directory or PDF to use, DeepPaperNote asks the user to choose.

Fixed

  • Fixed reading and saving archived PDFs with newer PyMuPDF releases.

Documentation

  • Added a dedicated DeepPaperNote Connector introduction and installation link to the English and Chinese READMEs.

  • Refreshed the README illustration and added installation guidance for uv users.

v2.3.0

Added

  • Added end-to-end English output through User Configuration or --language en, including localized note schemas, paper-type planning contracts, figure callouts, grounding, final-note linting, and Formal Save validation.

  • Added one device-local config.json for language and save preferences, with first-use/repair inspection, confirmed migration, atomic persistence, and run-scoped overrides.

  • Added Vault-wide Save Target Admission backed by the original PDF SHA-256 and a hidden paper-directory sidecar, so source-identical language variants share one directory and same-language overwrites require explicit hash-bound confirmation.

Changed

  • Complete valid Run Overrides now satisfy Configuration Readiness without reading ~/.deeppapernote/config.json; incomplete overrides continue through the existing User Configuration fallback and validation flow.

  • Obsidian notes now use language-specific filenames, and Windows sidecars receive the native Hidden file attribute in addition to their dot-prefixed name.

  • Successful runs now report the saved note path and domain, validation results, figure and table counts, warning count, and final note integrity check.

Fixed

  • Formal Save now preserves LF line endings on Windows instead of applying platform-specific newline conversion.

Contributors

v2.2.0

Improved

  • Figures and tables are now cropped to the scientific visual body, keeping axes, legends, panel labels, table headers, and other internal labels while excluding external captions and surrounding paper prose.

  • Selected visual assets are rendered at 300 dpi and reviewed with full-page context before insertion, improving readability and reducing incomplete or mismatched crops.

  • Recoverable crop-boundary problems can receive one bounded correction and a fresh review instead of immediately losing an otherwise useful figure or table.

Fixed

  • Unreviewed, incomplete, malformed, or outdated visual approvals now fail closed instead of allowing an unreliable image into the final note.

  • Formal Save now verifies that the image copied into the paper-local images/ folder is exactly the asset that passed visual review.

v2.1.1

Added

  • Added a built-in, read-only Zotero Local API integration with local attachment discovery, explicit auto / off / required resolution policies, and environment diagnostics.

Fixed

  • Enforced a canonical paper-identity boundary across metadata collection, PDF acquisition, evidence extraction, and synthesis so conflicting or ambiguous identities fail closed.

Contributors

  • Added the Zotero Local API integration from PR #13 by @KumamuKuma.

v2.1.0

Added

  • Added paper-glossary as an optional companion skill. It builds reusable Obsidian terminology notes from saved DeepPaperNote source artifacts, previews a reviewed shortlist before writing, and can link selected terms back to an explicitly supplied paper note.

  • Added a canonical single-paper Source Corpus so downstream reading stages use the complete validated raw text and source manifest instead of relying on truncated candidate chunks.

  • Added explicit paper-identity verification and bounded repair before PDF acquisition. Ambiguous or mismatched identities now fail closed instead of silently continuing with the wrong paper.

  • Added a reproducible note-quality regression workflow, evaluator prompt, and rubric under evals/ for contributor validation.

Changed

  • Converted the repository to a dual-stack Claude Code and Codex plugin layout with the canonical skill under skills/deeppapernote/.

  • Simplified installation guidance to the interactive repository command npx skills add 917Dhj/DeepPaperNote, which lets users choose skills and target agents.

  • Reused acquisition artifacts across pipeline stages to avoid repeating successful paper resolution, metadata, and PDF work.

  • Formalized Obsidian save behavior: workspace output requires explicit user choice, failed vault saves no longer switch destinations silently, and final note and image paths must stay inside the authorized save target.

  • Aligned figure and table decisions with the generated writing contract so planned insertions and retained placeholders remain consistent through final save.

Fixed

  • Improved PDF acquisition failures and lint feedback so blocked stages report actionable causes instead of producing incomplete-looking success states.

  • Fixed Windows-style Obsidian subdirectories so Research/Papers is not duplicated in saved note paths.

  • Cross-platform (Windows) path and encoding robustness: read files with utf-8-sig so a UTF-8 BOM (as written by PowerShell/Notepad) no longer crashes JSON loading or corrupts saved notes; tolerate CRLF line endings in note linting; and compare/emit paths without assuming / so the vault folder and Markdown image links resolve correctly on Windows. No behavior change on Linux/macOS.

  • Rejected Windows-rooted workspace output paths that could escape the configured workspace save boundary on non-Windows hosts.

  • Hardened glossary selection, link-stem handling, and confidence validation so invalid or stale glossary artifacts fail before modifying Obsidian notes.

Contributors

  • Added the paper-glossary companion skill and its selection workflow from PRs #8 and #11 by jiang4wqy.

  • Incorporated the paper-fetching and lint-feedback improvements from PR #3 by Zebang Cheng.

  • Incorporated the Windows Obsidian path normalization fix from PR #4 by KumamuKuma.

  • Incorporated the Windows path/encoding robustness fix from PR #5 by jiang4wqy.

v2.0.0

  • Strengthened note-depth planning with source-grounded central claims, claim boundaries, limiting-result coverage, mechanism-to-result mapping, comparative positioning, reusable takeaways, follow-up questions, and a separate final analytical quality review before readability polish.

  • Expanded benchmark/dataset and clinical paper guidance to cover sample statistics, data access, privacy constraints, and reproducibility boundaries when the paper reports them.

v1.1.1

Small patch release that fixes existing logic gaps.

Fixed

  • Tightened final-note linting so retained figure/table placeholders must use the standard [!figure] callout format.

  • Strengthened table crop quality checks so crops contaminated by running prose or other figure/table captions fail closed.

Notes

  • This remains a stable release.

  • The release asset continues to ship as a clean manually installable DeepPaperNote.zip.

v1.1.0

Minor stable release with a major figure/table extraction quality upgrade.

Added

  • Added figure-level PDF asset extraction that renders caption-anchored page regions instead of relying only on raw xref image objects.

  • Added richer figure_assets metadata for extracted figures and tables, including labels, captions, extraction kind, and visual quality signals.

  • Added visual quality gates so weak crops can fail closed and remain placeholders instead of being treated as insertion-ready images.

  • Added figure_assets to the synthesis bundle so model-side review can inspect richer figure/table candidates.

  • Added regression tests for figure asset candidates, placeholder-first planning, label normalization, and visual quality rejection.

Changed

  • Improved extraction for complete figures, vector-heavy papers, fragmented LaTeX tables, and caption-on-bottom tables.

  • Preserved DeepPaperNote's placeholder-first behavior: extracted figure assets are exposed as candidates, not automatic note insertions.

  • Strengthened figure-placement and final-writing guidance around visual quality review and candidate handling.

Contributors

  • Incorporated the figure-level extraction work from PR #1 by KuangjuX, with follow-up changes to keep insertion semantics placeholder-first.

Notes

  • This remains a stable release.

  • The release asset continues to ship as a clean manually installable DeepPaperNote.zip.

v1.0.1

Patch release after v1.0.0.

Changed

  • Added YAML frontmatter and wikilink rules for Obsidian-native features.

  • Fixed lint_note.py compatibility with YAML frontmatter.

  • Added tests for frontmatter stripping and frontmatter-aware lint compatibility.

  • Fixed wikilink target resolution with a lookup-first, fail-closed approach.

  • Removed unused image assets that were no longer referenced by the README files.

Notes

  • This remains a stable release.

  • The release asset continues to ship as a clean manually installable DeepPaperNote.zip.

v1.0.0

First stable release of DeepPaperNote.

Changed

  • Reframed DeepPaperNote as a pure cross-agent skill for Claude Code, Codex, Cursor, Copilot, Gemini CLI, and other Agent Skills-compatible environments.

  • Kept the root SKILL.md as the single canonical skill entrypoint.

  • Updated installation guidance for npx skills add 917Dhj/DeepPaperNote -a codex and npx skills add 917Dhj/DeepPaperNote -a claude-code.

  • Removed experimental onboarding/setup pseudo-surfaces and the temporary Claude plugin wrapper structure.

  • Added AGENTS.md and CLAUDE.md for repo-level agent guidance.

  • Added explicit Python >=3.10 interpreter guidance for agents running bundled scripts.

Preserved

  • The evidence-first deep-reading pipeline.

  • Obsidian-first output behavior.

  • Figure/table placeholder-first policy.

  • Lint gate and final readability review.

v0.3.2-alpha

Fifth public alpha release of DeepPaperNote.

Changed

  • Strengthened local_pdf -> enrich_metadata so Zotero-style attachment filenames no longer dominate metadata resolution.

  • Added local PDF metadata hints that prefer embedded PDF title, DOI, arXiv identifiers, and first-page title signals before falling back to cleaned filenames.

  • Added local-PDF-only title correction so high-confidence external matches can replace noisy attachment-style titles without changing the global merge policy.

  • Tightened candidate scoring so published venue/DOI records are preferred over preprint-style matches when both are available.

  • Normalized common PDF ligatures such as fi and fl during text extraction so titles and other extracted strings are cleaner and more stable.

Packaging

  • Rebuilt the release zip from the latest main branch state for v0.3.2-alpha.

Notes

  • This is still an alpha release.

  • Chinese remains the only fully supported output language.

  • Figure replacement is still conservative and placeholder-first when image confidence is insufficient.

v0.3.1-alpha

Fourth public alpha release of DeepPaperNote.

Changed

  • Changed the default Obsidian paper root from 20_Research/Papers to Research/Papers.

  • Aligned runtime path resolution, save behavior, and tests with the new default paper root so new notes land in the updated location consistently.

Packaging

  • Rebuilt the release zip from the latest main branch state for v0.3.1-alpha.

Notes

  • This is still an alpha release.

  • Chinese remains the only fully supported output language.

  • Figure replacement is still conservative and placeholder-first when image confidence is insufficient.

v0.3.0-alpha

Third public alpha release of DeepPaperNote.

Changed

  • Added a dedicated 创新点 section near the front of the note and strengthened the front-matter contract.

  • Added explicit ### 机制流程 guidance for method and system papers so the execution chain is reconstructed more clearly.

  • Strengthened ablation handling so notes are more likely to capture failed settings, weaker variants, and trade-offs rather than only best-case results.

  • Renamed the opening abstract block to 原文摘要翻译 and tightened the contract so it is treated as a Chinese translation of the original abstract rather than a newly written summary.

  • Tightened the 核心信息 block into a fixed metadata zone and explicitly forbade analysis or judgment from leaking into it.

  • Added a required final_readability_review stage after script lint to improve fluency, remove stiff phrasing, and reduce unnecessary English leftovers.

  • Added a dedicated math syntax gate to catch common Obsidian / MathJax rendering failures before final save.

  • Strengthened the overall workflow contract so the model is less likely to silently skip required stages, downgrade output behavior, or claim completion too early.

  • Tightened Obsidian save rules and fixed the duplicated paper-slug directory bug during note writing.

Packaging

  • Added a release zip asset for v0.3.0-alpha and narrowed the release package to omit README files, license/changelog docs, and showcase media.

Notes

  • This is still an alpha release.

  • Chinese remains the only fully supported output language.

  • Figure replacement is still conservative and placeholder-first when image confidence is insufficient.

v0.2.0-alpha

Second public alpha release of DeepPaperNote.

Changed

  • Strengthened the note-writing contract so technical papers are pushed closer to replication-oriented reading notes rather than polished summary rewrites.

  • Added explicit short note planning before final note generation.

  • Added equation-aware output guidance so key formulas can be preserved in LaTeX when they are central to understanding the method.

  • Added stricter final self-review requirements for key numbers, method explanation depth, and technical completeness.

  • Added stronger formatting checks for suspicious mid-sentence line breaks and math accidentally rendered as code.

  • Updated the abstract section contract to keep both the original abstract and a Chinese translation.

  • Made the Chinese README the default GitHub homepage and clarified that Chinese is currently the only fully supported note language.

Documentation

  • Split the English README into README.en.md while keeping the Chinese README as the default repository homepage.

  • Updated homepage messaging to better emphasize replication-oriented technical note quality.

Notes

  • This is still an alpha release.

  • Chinese remains the only fully supported output language at this stage.

  • High-confidence figure replacement remains conservative; placeholder-first behavior is still preferred when image certainty is low.

v0.1.0-alpha

First public alpha release of DeepPaperNote.

Added

  • Initial public Codex skill workflow for generating a deep-reading note from one paper.

  • Model-facing synthesis bundle pipeline with deterministic evidence gathering.

  • Placeholder-first figure planning and Obsidian folder-per-paper output structure.

  • Zotero-first helper workflow for local-library-first paper resolution.

  • Workspace fallback output when no Obsidian vault is configured.

  • OCR fallback for low-text PDF pages.

  • Domain-aware note routing that prefers existing vault domains before creating new ones.

  • Minimal automated test suite and GitHub Actions CI.

  • Setup-assistant entry points such as /deeppapernote doctor and /deeppapernote start.

Documentation

  • Bilingual project README (README.md and README.zh-CN.md).

  • MIT license and initial project metadata via pyproject.toml.

Changed

  • Standardized figure placeholders to a stable callout format.

  • Shifted the architecture toward model-first paper understanding.

  • Moved image output into paper-local images/ folders.

Notes

  • This is an alpha release.

  • Figure replacement quality still depends on extraction quality and semantic matching confidence.

  • Some environments may expose different python3 interpreters across sessions; doctor now reports the active interpreter explicitly.

253 files · 245 not served here

Advantages

  • Provides type-specific reading structures based on over 50 reviewer guidelines and reporting standards. evidence: README.md
  • Ensures accuracy by grounding all conclusions and data in the original paper text. evidence: README.md
  • Maintains a persistent, interconnected academic wiki by linking new notes to existing vault content. evidence: README.md
  • Supports visual content by cropping and embedding figures and tables directly into the generated notes. evidence: README.md

Limitations

  • Requires Python 3.10 or newer and specific dependencies like PyMuPDF to function. evidence: README.md
  • Does not generate notes if the full text of the paper is unavailable. evidence: README.md
  • Intermediate run files are not automatically cleaned up and may consume disk space. evidence: README.md

Security

Risk level: Low risk

This brain runs

Agent instructions that run or fetch something (32)

  • AGENTS.md: install the core runtime dependency with `python3 -m pip install PyMuPDF`
  • AGENTS.md: install the local development environment with `python3 -m pip install -e '.[dev]'`
  • AGENTS.md: run the test suite, companion skills included, with `python3 -m pytest -q -n auto`
  • AGENTS.md: run the lint CI enforces with `python3 -m ruff check skills tests`
  • AGENTS.md: when checking environment-related problems, use `python3 skills/deeppapernote/scripts/check_environment.py`
  • AGENTS.md: after changing extraction or figure selection, run the local paper corpus with `python3 -m pytest -q -m corpus`, as described in `evals/paper-corpus.md`
  • AGENTS.md: run the test suite and the lint from Working Commands
  • skills/deeppapernote/SKILL.md: Each run handles one paper.
  • skills/deeppapernote/SKILL.md: Run the steps in order.
  • skills/deeppapernote/SKILL.md: `references/run-state.md` explains how to bind the artifacts you write.
  • skills/deeppapernote/SKILL.md: **Configuration Readiness.** Resolve Run Overrides from the explicit request, CLI, and process environment.
  • skills/deeppapernote/SKILL.md: **Save Target Admission.** In Obsidian mode, run `scripts/write_obsidian_note.py --preflight` with the resolved title, `--language`, Vault, `--source-manifest`, and `--output <run_directory>/<run_prefix>_admission.json`.
  • skills/deeppapernote/SKILL.md: **Formal Save.** Run `scripts/write_obsidian_note.py` with `--content-file`, `--plan-file`, `--lint-json`, `--grounding-lint-json`, `--source-manifest`, `--figure-decisions`, `--final-quality-review`, `--final-readability-review`, the admitted `--domain` and `--new-domain-reason`, and a …[+89 chars]
  • skills/deeppapernote/SKILL.md: A normal request finishes in one run: text, figure decisions, image materialization, and save.
  • skills/deeppapernote/SKILL.md: When a run stops early, name the current stage and the remaining stages.
  • skills/deeppapernote/SKILL.md: After a successful Formal Save, report in the user's conversation language, and derive every claim from current-run artifacts;
  • skills/deeppapernote/SKILL.md: `SKILL.md` and the synthesis bundle carry a normal run.
  • skills/deeppapernote/SKILL.md: | Reference | When | |---|---| | `references/user-configuration.md` | Configuration Readiness | | `references/paper-archive.md` | existing Obsidian directories, local PDF versions, Connector handoff | | `references/domain-routing.md` | choosing the domain folder, the `papers/` tag, the …[+924 chars]
  • skills/deeppapernote/SKILL.md: When `python3` is older, use another interpreter of 3.10 or newer, such as `python3.12`, for the whole run;
  • skills/deeppapernote/SKILL.md: Run `scripts/check_environment.py` only when a concrete dependency or integration problem blocks a step, and explain the required dependencies, optional enhancements, and downgrade behavior directly.
  • skills/organize-wiki/SKILL.md: To undo the last reorganization, run `python3 scripts/organize.py undo --latest`, report what it restored or the conflicts it lists, and stop.
  • skills/organize-wiki/SKILL.md: Run `python3 scripts/scan_library.py --output <tmp>/scan.json`.
  • skills/organize-wiki/SKILL.md: Run `python3 scripts/organize.py preview --plan <plan.json>`.
  • skills/organize-wiki/SKILL.md: After the user confirms, run `python3 scripts/organize.py apply --plan <plan.json> --expected-digest <plan_digest>`.
  • skills/paper-glossary/SKILL.md: **Run deterministic proposal** from the effective body.
  • skills/paper-glossary/SKILL.md: Run library **inventory** from that triage artifact;
  • skills/paper-glossary/SKILL.md: **Run one writer invocation** against the **configured glossary directory**;
  • skills/research-memory/SKILL.md: Run `python3 scripts/aggregate_reading.py --output <tmp>/aggregate.json`.
  • skills/research-memory/SKILL.md: Keep `memory.sha256` from this run;
  • skills/research-memory/SKILL.md: Run the writer with `--create <content.json> --expected-sha256 absent --language <aggregate language> --dry-run`, and show the user `text` in full.
  • skills/research-memory/SKILL.md: Run it with `--update <changes.json> --expected-sha256 <memory.sha256> --dry-run`, and show the user `diff`.
  • skills/research-memory/SKILL.md: After the user confirms, run the same command without `--dry-run`.
  • Low risk: network-instructions (AGENTS.md:67)

Attribution and licence

First committed by
GitHub avatar of 917Dhj917Dhj
Declared authors
  • 917Dhj (declared in .claude-plugin/plugin.json)
  • dingdingcar (declared in pyproject.toml)
Publisher
HJ Ding (Community)
Source
917Dhj/DeepPaperNote · commit 9670b1b
Licence
MIT License (files served here)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Contributors
917Dhj, KuangjuX

AutoGineer is not affiliated with or endorsed by 917Dhj.

Install from source

245 of its files are not served here, so there is no ZIP. 917Dhj/DeepPaperNote at 9670b1b