phd_kb_starter

A one-command installer for Andrej Karpathy's LLM-Powered Personal Knowledge Base workflow, adapted for Claude Code.

This repo creates a scaffolded directory tree + templated CLAUDE.md compile/lint rules + example wiki notes that together form a functioning Karpathy-style research knowledge base. You use it with Claude Code as the agent runtime and Obsidian as the viewer/frontend. There is no daemon, no server, no fancy UI — just a folder structure, a rule file, and an agent that knows how to read them.

The design is a minimal implementation of Karpathy (2026) — LLM Knowledge Bases. See examples/literature_note.md for the full 8-stage pipeline and UPGRADING.md for how to evolve the rules as your workflow matures.

---

Installation

Requirements

• bash (macOS / Linux — Windows via WSL)
• sed, awk, find, mkdir (standard on any Unix system)
• Strongly recommended: Obsidian (the viewer), Claude Code (the agent)
• Optional for PDF ingest: uv + pymupdf (see setup step below)

Quick start

git clone https://github.com/YOU/phd_kb_starter.git    # or download the zip
cd phd_kb_starter
chmod +x install.sh
./install.sh                                            # interactive, defaults to ~/knowledge_base

Or non-interactive:

./install.sh ~/Desktop/my_research_kb

The installer asks for:

• target directory
• vault name (used in Obsidian and MAP.md header)
• your name and role (used for CLAUDE.md context)
• primary research language(s) — English, Chinese, or both
• primary research focus (optional, free text)

It then creates the directory tree, writes CLAUDE.md and MAP.md with your parameters substituted, copies example notes (disable with --no-examples), and prints a checklist of manual setup steps.

---

What gets created

<target>/
├── CLAUDE.md                    # Compile/lint rules (the agent's "constitution")
├── MAP.md                       # Hand-written root index
├── 00_inbox/                    # Raw material (never edit, only append)
│   ├── README.md
│   ├── papers/
│   ├── articles/
│   ├── clipper/
│   ├── repos/
│   ├── datasets/
│   ├── images/
│   └── quick_notes/
├── 01_literature_notes/         # Atomic notes, one per source
│   ├── papers/                  # Academic (citable in formal writing)
│   ├── tweets/                  # X/Twitter threads (context)
│   ├── news/                    # Tech media, blog posts
│   └── social/                  # LinkedIn, Reddit, HN
├── 02_topics/                   # Survey-style topic aggregations
├── 03_methods/                  # Econometric / ML methods
├── 04_variables/                # Constructs and their measurements
├── 05_mechanisms/               # Causal / theoretical mechanisms
├── 06_writing_templates/        # Output: paper drafts, slides, figures
├── 07_advisor_feedback/         # Comments + responses
├── 08_projects/                 # Active research projects
├── 09_weekly_review/            # Lint reports
└── .tool_templates/             # Hidden: Zotero/Clipper templates, not in graph view

With --no-examples omitted, the installer also seeds:

• 01_literature_notes/tweets/Karpathy2026_llm-knowledge-bases.md — the canonical Karpathy tweet thread, as a complete example of what a well-written literature note looks like
• 02_topics/llm_knowledge_base_workflow.md — a topic node linked to the example note

You can delete these once your own content arrives, or keep them as a permanent design reference.

---

Post-install setup (estimated 15 minutes)

The installer prints these as a checklist. Detailed instructions for each step are in docs/:

1. Open as Obsidian vault — docs/setup_obsidian.md

2. Configure Web Clipper — docs/setup_webclipper.md

3. Set Graph view filter — covered in Obsidian doc above

4. Configure Zotero for paper ingest — docs/setup_zotero.md

5. Install pymupdf for PDF extraction:

   # if you have uv:
   uv tool install pymupdf
   # or with pip:
   pip install pymupdf

6. First compile: open the vault in Claude Code and say compile inbox.

---

Using the wiki (daily / weekly / monthly rhythm)

Daily (~5 min)

• See something interesting? Web-clip it (⌥⇧O), drag a PDF in, or jot a quick_note. Zero evaluation, just capture.

Weekly (~30 min — Sunday evening recommended)

1. Tell Claude Code compile inbox — it processes everything new since last run
2. Tell Claude Code lint wiki — it generates a health report in 09_weekly_review/
3. Read the lint report (5 min) — note stubs to expand, gaps to ingest next week
4. Open Obsidian Graph view (1 min) — visual check on structure

Monthly (~1 hour)

1. Re-read My synthesis sections of your literature notes — has your thinking changed?
2. Update project READMEs in 08_projects/
3. Ask Claude a "wiki audit" question: "wiki 现在的形状反映了我的研究焦点吗?"

Per-paper / per-talk

1. Before starting: ask wiki "what do I know about X?" — Claude answers from notes
2. During writing: ask wiki to draft a section using specific literature nodes
3. After: file the drafts into 06_writing_templates/; Karpathy's "self-improving loop"

---

Core design principles

These are in CLAUDE.md but worth repeating here since they shape everything:

1. LLM writes the wiki, human reads it. You don't edit wiki files manually — you edit the rules (CLAUDE.md), and the next compile applies them.
2. MAP.md is the retrieval layer, not RAG. The hand-curated index keeps the LLM oriented without vector search. Works up to ~100 articles on current context windows.
3. Never delete from 00_inbox/. Raw material is the source of truth. Downstream wiki notes can be rewritten freely, but source files are permanent.
4. Bidirectional backlinks. Every wiki link is mirrored in the target's backlinks: frontmatter field. Lint catches missed pairs.
5. Citation-safe structure. Only 01_literature_notes/papers/ contents are ever cited in formal academic writing. Tweets, news, and social are context.

---

When this is NOT the right tool

• If you just want a full-featured research assistant, use Feynman — it's a proper CLI agent with built-in paper search, peer review simulation, and experiment replication. This starter is deliberately minimal and relies on you driving Claude Code manually.
• If you need real-time collaboration, this is single-user. Multiple contributors would need to coordinate edits out-of-band.
• If your workflow is already in Notion / Roam / Logseq and working, don't switch. The value here is the agent-writable markdown + CLAUDE.md rule layer, not the file format.

---

Credits

The workflow design is entirely Karpathy's (April 2026 X thread + llm-wiki gist). This starter is a minimal Claude-Code-shaped implementation of his description, with the addition of:

• Explicit sub-directory structure for source-type separation in 01_literature_notes/
• Hard citation-safety rule
• Auto-routing of clipper files by URL domain during compile
• Structured frontmatter schema with bidirectional backlinks enforced by lint

License

MIT. See LICENSE.