Problem-driven Research Knowledge Graph Vault

中文 | English

A lightweight Markdown + Obsidian vault for building a research map

What is this?

This is a knowledge graph vault for research reading. It does not archive papers by time. Instead, it starts from the core questions in a field and connects papers, reading notes, cross-paper insights, and source-code reading records.

It is useful when:

• you are entering a new field and need to build a big picture quickly
• you have read many papers, but the relationships between them have not been retained
• you are facing a large number of VLA / embodied AI / robotics / foundation model papers and need a better way to classify and review them
• you want to visualize your research map with Obsidian Graph View

Core idea

Question -> Paper -> Insight

• Question: the open questions that a research field truly cares about
• Paper: paper cards and reading notes organized around questions
• Insight: reusable judgments distilled across papers, experiments, and projects

codes/ is an optional source-code reading branch. It is used to record code types such as VLM, LLM, and Infra, together with concrete source-code reading notes.

What can this vault do?

Feature	Description
Question-driven paper graph	Use questions/ as the entry point and attach papers to concrete research questions
Two browsing views	Use views/paper-view.md for a paper table, and use Obsidian Graph View for the relationship graph
One-command paper scaffolding	Automatically create both paper-card and paper-note files with one command
Reusable insights	Save stable judgments from multiple papers or engineering practice as independent nodes
Source-code reading notes	Use codes/types/ and codes/readings/ to manage source-code understanding
Automatic vault check	Check whether paper cards, notes, frontmatter, and links are complete with one command
Clear starter content	Quickly remove starter notes after cloning and use the repo as your own new vault

Quick start

1. Prepare the environment

Only Python 3.8+ is required. No extra dependency is needed.

python --version

2. Open the vault

Open the repository root with Obsidian. You can then use Markdown notes, Graph View, and views/paper-view.md. Demo:

3. Add a paper

python scripts/new-paper.py \
  --paper-id pi07 \
  --title "π_{0.7}: a Steerable Generalist Robotic Foundation Model with Emergent Capabilities" \
  --alphaxiv "https://www.alphaxiv.org/overview/xxxx"

Optional fields:

--year 2025 --pdf "https://arxiv.org/pdf/xxxx" --code "https://github.com/xxx/yyy"

This command creates:

papers/cards/<paper_id>.md
papers/notes/<paper_id>-note.md

Common commands

Add questions / code types / code-reading notes

Copy the corresponding template directly from templates/ and modify it.

Add an insight

python scripts/new-insight.py \
  --insight-id pretrain-not-fully-converged \
  --claim "Pretraining need not fully converge for downstream performance"

Check vault completeness

python scripts/check-vault.py

Expected output:

Vault check passed.

Clear starter content

python scripts/clear-template.py

Note types

Type	Purpose
open-question	Core questions in a research field, such as Generalization, Sim2Real Gap, and evaluation
paper-card	A quick paper index page for title, links, core contribution, and brief insight
paper-note	A detailed reading note for methods, experiment details, personal judgment, and review
insight	A stable understanding distilled from multiple papers, experiments, or engineering practice
code-type	A source-code reading category node, such as VLM, LLM, or Infra
code-reading	A concrete source-code reading note

Suggested workflow

• When entering a new direction, write questions in questions/ first instead of stacking papers.
• When reading a paper, first fill in the core contribution in paper-card, then put details in paper-note.
• When the same conclusion appears repeatedly across papers, save it as an insight.
• When source-code reading is needed, use the codes/ branch to record code types and reading notes.
• Run python scripts/check-vault.py regularly to keep the vault searchable and maintainable.