papers-kb

A personal academic knowledge base powered by Claude Code. Automatically searches, adds, enriches, and translates research papers using Claude Code skills (slash commands).

Skills run in Claude Code — via terminal (claude CLI) or the VS Code / JetBrains extension. Obsidian is used separately for reading, graph navigation, and manual editing of the resulting files.

Workflow

flowchart TD
    A([arXiv / Semantic Scholar\nPDF / Markdown]) --> B

    subgraph CC ["Claude Code  (terminal · VS Code · JetBrains)"]
        B["/add-paper-bulk\n/find-related-pdf\n/find-related-md"] --> C[(papers-kb)]
        C --> D["/enrich-paper\ndetailed notes + code links"]
        C --> E["/cluster-topic\nsub-topic grouping"]
        C --> F["/translate-paper\nmulti-language"]
        C --> G["/export-topic\nrequirements doc"]
        C --> H[Stop hook\nauto HISTORY.md]
    end

    C --> I([Obsidian\ngraph navigation])
    I -->|property edit| J["/sync-paper\nsync translations"]
    J --> C

Loading

What it does

• Search and add papers from arXiv and Semantic Scholar
• Enrich papers with detailed notes (Method, Results, Limitations) and code links
• Translate papers to other languages (default: Korean)
• Export topic summaries as requirements/analysis documents
• Auto-cluster papers within a topic into sub-clusters
• Track changes automatically via a Stop hook

Requirements

• Claude Code
• arxiv-mcp-server — uvx arxiv-mcp-server
• mcp-server-semantic-scholar — uvx mcp-server-semantic-scholar

Add both to your Claude Code MCP config:

{
  "mcpServers": {
    "arxiv": { "command": "uvx", "args": ["arxiv-mcp-server"] },
    "semantic-scholar": { "command": "uvx", "args": ["mcp-server-semantic-scholar"] }
  }
}

Setup

git clone git@github.com:junkyul/papers-kb.git ~/papers-kb
cd ~/papers-kb
claude          # terminal CLI

Or open ~/papers-kb in VS Code / JetBrains with the Claude Code extension installed — skills work the same way from the IDE.

Scripts assume ~/papers-kb. If you clone elsewhere, update the path constants in the .py files.

Use Cases

1. Build a topic from scratch

Add 100 papers by keyword — topic is auto-classified from CLASSIFICATION.md and each paper is saved with YAML frontmatter.

/add-paper-bulk diffusion model score matching 100개

Enrich all papers in the topic with full notes and code links:

/enrich-paper --topic diffusion-model

Once the topic grows, auto-cluster into sub-topics (e.g., "image generation", "video diffusion", "consistency models"):

/cluster-topic diffusion-model

Papers can be added at any time and will slot into the existing structure:

/add-paper flow matching rectified flow 2023-2024 10개

---

2. Explore from a draft or existing notes

Already have a draft PDF or a research memo? Extract keywords and citations automatically:

/find-related-pdf ~/papers/my-draft.pdf topic:diffusion-model 20개
/find-related-md ~/notes/survey-notes.md 15개

---

3. Translate and sync

Translate an entire topic to another language (runs as a 1-minute loop, 5 papers per cycle):

/translate-paper --topic diffusion-model --lang ko

After editing a paper's frontmatter (venue, code link, etc.) in Obsidian, sync the change to the translated file:

/sync-paper 2407.09522

---

4. Export for use elsewhere

Generate a requirements/analysis document from selected papers — useful for feeding into another project or writing a literature review:

/export-topic diffusion-model citations:100
/export-topic query-processing --output ~/my-project/related-work.md

---

5. Navigate in Obsidian, track everything automatically

Open ~/papers-kb as an Obsidian vault. Papers link to topics via [[topics/...]] wikilinks, forming a graph you can navigate visually. Sub-clusters from /cluster-topic appear as a second layer in the graph.

Edit a paper's properties in Obsidian's Properties panel, then run /sync-paper to push changes to translations.

Every time a Claude Code session ends, a Stop hook runs scripts/log-history.py and appends a diff to HISTORY.md — paper count, new topics, skill changes — automatically.

---

Obsidian

The ~/papers-kb folder works as an Obsidian vault out of the box. YAML frontmatter and [[wikilinks]] are used throughout, so papers and topics form a navigable graph.

1. Open Obsidian → Open folder as vault → select ~/papers-kb
2. Recommended community plugins: Dataview, Graph Analysis
3. Graph view: papers cluster by topic via [[topics/...]] wikilinks

Example Dataview query:

TABLE year, citations, venue
FROM "papers"
WHERE topic = "diffusion-model"
SORT citations DESC

Language

All skill output defaults to Korean. To change, edit one line in CLAUDE.md:

# Language
Respond in: English

Any language supported by Claude works.

Skills

Skill	Description
/add-paper	Search and add papers (small batch)
/add-paper-bulk	Auto-loop bulk add with citation graph expansion (2-hop)
/add-article	Add web articles with 1-hop link crawling
/find-topic	Search existing KB by keyword
/find-related	Find related papers from a KB paper via Semantic Scholar
/find-related-md	Find related papers from a local markdown file
/find-related-pdf	Find related papers from a draft PDF
/enrich-paper	Add detailed notes + code links (reads full paper)
/translate-paper	Translate paper notes to another language (default: Korean)
/sync-paper	Sync frontmatter changes from original to translated file
/export-topic	Export a topic as a requirements/analysis document
/cluster-topic	Auto-cluster papers within a topic into sub-topics
/summarize-topic	Update topic-level insights

Folder structure

papers-kb/
  papers/          paper notes (one file per paper, YAML frontmatter)
  papers/ko/       Korean translations
  articles/        web articles
  topics/          per-topic paper lists and sub-clusters
  pdfs/            downloaded PDFs
  exports/         export-topic output documents
  scripts/         automation scripts
  .claude/commands/  skill definitions
  CLASSIFICATION.md  topic classification rules
  MCP_STRATEGY.md    MCP selection strategy
  HOWTO.md           detailed usage guide (Korean)
  HISTORY.md         change log (auto-updated)

Paper file format

---
title: "Paper Title"
authors: "Author1, Author2"
year: 2024
citations: 150
arxiv_id: "2407.09522"
topic: query-processing
venue: "NeurIPS 2024"
code_official: "https://github.com/..."
---

## Summary
## Key Contributions
## Relevance
[[topics/query-processing]]

## Detailed Notes        ← added by /enrich-paper
### Method
### Experiments & Results
### Limitations & Future Work

## Code                  ← added by /enrich-paper