PKB Starter

One command to rule your knowledge. /pkb <anything> — throw in a URL, file, or idea. The LLM organizes everything.

Current version: v0.8.0-starter | 🆕 MinerU Phase 2: PDF OCR + layout analysis + LaTeX formulas | OUTPUT.md: output format spec | Obsidian MCP: native Obsidian integration

Languages: English | 简体中文

PKB Starter is a Claude Code plugin + project template that gives you a local, LLM-maintained personal knowledge base in minutes. Based on Karpathy's LLM Wiki concept.

What It Does

You: /project:pkb https://karpathy.bearblog.dev/llm-wiki/
PKB: [auto-collects → extracts → classifies → creates wiki page → links concepts → git commits]
     Done. 2 wiki pages created. Health: [OK]

Features

🚀 One command: /pkb <anything> — fully automatic ingest
🧠 LLM-organized: AI classifies, links, and maintains your knowledge
📄 Rich collection: Web pages, PDFs, DOCX, PPTX, GitHub repos, videos — PDF via MinerU Phase 2 OCR + layout analysis
🔗 Obsidian-compatible: [[wikilink]] graph + native Obsidian MCP integration, open wiki/ as vault
🔒 Local-first, no cloud sync, no telemetry; when using Claude Code for organization, content that enters model context is handled per the model provider's data usage policies
🩺 Self-healing: Health checks find broken links, stale content, orphans
🔍 Hybrid search: BM25 + vector RRF + Cross-encoder retrieval pipeline
💾 Git-native: Every change is a commit, full rollback support

Quick Install

git clone https://github.com/Clockworkhg/pkb-starter.git
cd pkb-starter
python scripts/install.py "D:\MyKB"
cd "D:\MyKB"
pip install -r requirements.txt
claude

Path is up to you: D:\MyKB is an example. Install anywhere — E:\KnowledgeBase, C:\Users\...\Documents\PKB, F:\ResearchKB, etc. The first positional argument to install.py is your chosen target directory. ASCII paths are recommended to avoid encoding issues with Python, Git, and shell tools.

In Claude Code (project mode):

/project:help                        # See all commands
/project:pkb https://example.com     # Start collecting

Note: Commands use /project:<name> format. Bare /pkb is only available if pkb-starter is installed as a Claude Code plugin. See TROUBLESHOOTING.md if commands aren't found.

Full Quick Start →

Architecture

raw/          Immutable raw materials (web collections, PDFs, files)
wiki/         LLM-maintained structured knowledge (Markdown + [[wikilinks]])
skills/       Agent automation rules (12 built-in, expandable to 44+)
tools/        Python helper scripts (web_pack, import, sanitize, etc.)

Design Deep Dive →

Commands

Command	What It Does
`/project:pkb <anything>`	Smart entry — auto-detects type and processes
`/project:web <url>`	Collect web content to raw/webpacks
`/project:inbox`	Process pending files
`/project:ask <question>`	Search your knowledge base (project-local)
`/project:ask-pkb <question>`	🌐 Global knowledge query (any project)
`python tools/scansci_bridge.py download <DOI>`	📄 Multi-source paper download (13 sources)
`/project:lint`	Health check
`/project:save`	Git commit with auto doc update
`/project:rollback`	View/rollback git history
`/project:sanitize`	Privacy scan
`/project:skills`	Manage optional skill packs
`/project:update`	Update system files from pkb-starter

Usage with Obsidian

PKB's wiki/ directory is a standard Obsidian vault — open it directly as your vault folder. All wiki pages use [[wikilinks]] for cross-referencing, giving you a rich knowledge graph out of the box.

Getting Started

Download Obsidian (free, Windows/Mac/Linux)
Open Obsidian → "Open folder as vault" → select your PKB's wiki/ directory
The graph view will show your knowledge connections automatically

Example Scenarios

Researcher — Literature Review

# Collect papers and web resources
/project:pkb https://arxiv.org/abs/1706.03762   # "Attention Is All You Need"
/project:pkb ~/Downloads/transformer-survey.pdf
/project:pkb https://karpathy.bearblog.dev/llm-wiki/

Then in Obsidian:

Open graph view (Ctrl+G) — see papers, concepts, and sources linked automatically
Click any node to navigate to that wiki page
Use [[ autocomplete to link new ideas as you write
Search across all your knowledge with Ctrl+Shift+F

Student — Course Notes

/project:pkb ~/Notes/CS229-lecture01.pdf        # Lecture slides
/project:pkb https://ocw.mit.edu/course/notes    # Course page
/project:pkb ~/Downloads/assignment-solution.pdf  # Your work

Then in Obsidian:

Each lecture becomes a wiki page linked to core concepts
The local graph (Ctrl+G → "Local graph") shows only this course's connections
Use tags (#cs229, #exam) in wiki frontmatter to organize by topic
Canvas (Ctrl+P → "New canvas") to arrange concepts spatially

Developer — Project Documentation

/project:pkb https://github.com/oven-sh/bun       # Repo research
/project:pkb ~/Projects/design-doc.md             # Your work
/project:pkb https://docs.python.org/3/whatsnew/   # Reference

Then in Obsidian:

Project notes appear alongside referenced documentation
[[wikilinks]] connect your design decisions to their sources
Daily Notes plugin → log development progress linked to wiki pages
Dataview plugin → query all pages tagged #project-x or #decision

Writer — Topic Research

/project:pkb https://en.wikipedia.org/wiki/Knowledge_graph
/project:pkb https://blog.research.google/2023/05/
/project:pkb ~/Downloads/interview-notes.md

Then in Obsidian:

Use Outline pane to see the structure of long wiki pages
Split panes (Ctrl+Click) — read source on one side, draft on the other
Bookmarks plugin → pin frequently referenced concept pages
The graph shows gaps: clusters with few connections = topics to research deeper

Recommended Plugins

These Obsidian community plugins pair well with PKB's auto-generated wiki:

Plugin	Why
Dataview	Query wiki pages by tag, date, or metadata
Calendar	Navigate daily notes linked to wiki concepts
Excalidraw	Sketch diagrams alongside concept pages
Omnisearch	Faster full-text search across your wiki
Tag Wrangler	Rename/merge tags across all wiki pages at once

Tip: PKB auto-commits every change. If you edit wiki pages in Obsidian while Claude Code is running, save the file — PKB's /save or auto-commit hooks will pick up your changes in the next cycle.

Obsidian →

Optional Skills

PKB Starter ships with zero external dependencies. Extend it with optional skill packs from a catalog of 43 entries across 9 tracked external repositories (plus z-skills as user-approved local install):

# During installation
python scripts/install.py "D:\MyKB" --profile student    # 8 skills — academic essentials
python scripts/install.py "D:\MyKB" --profile developer  # 7 skills — docs + projects
python scripts/install.py "D:\MyKB" --profile research   # 12 skills — full pipeline
python scripts/install.py "D:\MyKB" --interactive-skills # pick from 42 entries

# Anytime after installation
python scripts/skill_manager.py --target "D:\MyKB" --list
python scripts/skill_manager.py --target "D:\MyKB" --install-profile student
python scripts/skill_manager.py --target "D:\MyKB" --install deep-research-skills

Or from Claude Code:

/project:skills                       # See status
/project:skills --list                # Browse catalog
/project:skills --describe <id>       # Learn about a skill
/project:skills --install-profile student
/project:skills --audit

Every skill shows its description, risk level, and requirements before installation. Third-party skills are cloned to skills/_vendor/ — never auto-executed, never auto-configured. Start with Core, add skills as needed.

See the full catalog: python scripts/skill_manager.py --target "D:\MyKB" --list

Optional Skills Guide →

Who Is This For?

Researchers: Collect papers, build literature maps, auto-generate citations
Developers: Document projects, collect code references, maintain design decisions
Writers: Research topics, organize sources, build concept maps
Students: Course notes, paper analysis, exam prep
Anyone who wants a "second brain" that maintains itself

What PKB Is NOT

NOT a cloud service — everything is local files on your disk
NOT a note-taking app — use Obsidian for that; PKB is the auto-organizer
NOT a search engine — it searches YOUR knowledge, not the web
NOT a backup tool — use proper backups; PKB uses git for versioning

Web Collector (v3.1)

PKB Starter ships with web_pack v3.1 (tools/web_pack.py) that handles:

Public web page fetching (requests + BeautifulSoup)
Content quality scoring (triggers dynamic fallback when needed)
Optional Playwright Chromium DOM rendering (--render)
XHR/Fetch network response extraction (--render)
Three-way content selection: HTTP static / Playwright DOM / Playwright Network
Content extraction (title, body, links, images)
Markdown conversion (markdownify)
GitHub blob/raw URL handling
Standard output structure (README, manifest, inventories)

Playwright (optional)

For JavaScript-heavy sites where static extraction yields insufficient content:

pip install -r tools/requirements-playwright.txt
playwright install chromium

python tools/web_pack.py --url "<URL>" --render              # Enable browser fallback
python tools/web_pack.py --url "<URL>" --render --headed     # Visible browser (manual login)
python tools/web_pack.py --url "<URL>" --render --debug-network  # Sanitized diagnostics

Flag	Behavior
`--render`	Enables Playwright only when static extraction quality is insufficient
`--headed`	Visible Chromium window (auto-enables `--render`)
`--debug-network`	Sanitized network diagnostics (no body/headers/cookies saved)

Playwright is optional — static site users do not need it
Chromium is NOT auto-downloaded with pip; playwright install chromium is separate
Uses a PKB-dedicated browser profile, not your daily Chrome profile
Safe mode does not persist login state
Does NOT bypass login, CAPTCHA, or access controls
App-only pages may still be uncollectable

MarkItDown (optional)

For local document ingestion (PDF, DOCX, PPTX, XLSX, XLS):

pip install -r tools/requirements-markitdown.txt

MarkItDown is optional — PKB falls back to LLM direct read when not installed
Legacy .doc files return an explicit unsupported status (use Word/LibreOffice to convert)
OCR is not enabled by default (Phase 2+)
Conversion cache in .pkb-cache/ (gitignored)

Z-Web-Pack (optional local install): Users may optionally install z-web-pack as an alternative collector backend. PKB Starter does NOT distribute z-skills or z-web-pack code. The user must:

Explicitly opt in: /project:skills --install z-skills
Audit license: /project:skills --audit z-skills
Enable adapter: /project:skills --enable z-web-pack-local
Use: /project:web --collector z-web-pack <url>

See Z_WEB_PACK_PARITY.md for capability comparison and the z-skills compatibility module.

Updating

PKB Starter tracks its version in pkb.config.json. When you update pkb-starter from GitHub, your installed KB can be upgraded without reinstalling.

Recommended — use the sync tool installed in your KB:

cd "D:\MyKB"
python tools/sync_to_starter.py --target "D:\pkb-starter" --dry-run     # Preview
python tools/sync_to_starter.py --target "D:\pkb-starter" --force       # Apply changes
python tools/sync_to_starter.py --target "D:\pkb-starter" --validate    # Check coverage only

Or in Claude Code:

/project:sync-to-starter                  # Dry-run by default
/project:sync-to-starter --force          # Apply changes

Alternative — for users with a local pkb-starter clone:

python tools/sync_to_starter.py --target "D:\pkb-starter"

Advanced — direct update_pkb.py:

python scripts/update_pkb.py "D:\MyKB" --dry-run

Every update creates a timestamped backup in .pkb_backup/. User data (raw/, wiki/, _INBOX/, skills/_vendor/, .pkb_local/) is never touched. Config fields (language, install_path, starter_repo_url) are always preserved.

Update Guide →

Privacy

Local-first, no cloud sync, no telemetry — files stay on your machine
When using Claude Code for organization, content that enters model context is handled per the model provider's data usage policies
Sensitive info detection (API keys, tokens, PII)
.gitignore with comprehensive security rules
Security Guide →

Requirements

Claude Code (with Claude API access)
Python 3.9+
Git
Optional: Obsidian (for visual browsing)

Documentation

Doc	Content
QUICKSTART.md	5-minute setup
DESIGN.md	Architecture deep dive
SECURITY.md	Privacy & safety
Z_WEB_PACK_PARITY.md	web_pack capabilities
TROUBLESHOOTING.md	Common issues
OPTIONAL_SKILLS.md	Optional skill packs
UPDATING.md	Update and migration guide
SCHOLARLY_METADATA.md	Scholarly metadata enrichment
EXAMPLES.md	Usage examples

Scholarly Metadata Enrichment

PKB Starter now detects scholarly literature automatically and enriches wiki pages with structured metadata:

Auto-detection: Recognizes academic papers via explicit declarations, DOI/ISSN identifiers, journal names, and citation patterns
Metadata enrichment: Crossref + optional OpenAlex (work metrics, source rankings)
Local journal registry: User-imported CSSCI, PKU Core, AMI, CSCD, and custom datasets
Citation formatting: GB/T 7714 numeric/author-date (verified fallback), APA 7 (citeproc-py), BibTeX, RIS, CSL-JSON
Batch processing: Scan, dry-run, write, --only-missing, --resume with job recovery
Literature filtering: Structured multi-criteria selection (ranking scheme, year, citations, DOI)

Enabled by default in /pkb. Configure via pkb.config.json:

{"scholarly": {"enabled": true, "auto_enrich_on_pkb": true}}

See SCHOLARLY_METADATA.md for full documentation.

Version History

v0.8.0-starter: Current. MinerU Phase 2 (PDF OCR + layout analysis + LaTeX formulas), OUTPUT.md output format specification, Obsidian MCP native integration, manifest coverage auto-validation, sync pipeline hardening (3 path leak fixes + 7 coverage gaps), core tools: mineru_extract / cnki_setup / runtime_detect / chrome_mcp_scraper.
v0.7.0-alpha: Meta-methodology optimization. OUTPUT.md, run_log.jsonl audit trail, failure_log.md structured recording, Plan-as-Contract (/pkb Step 0), pkb_retrieve hybrid search integration (/ask), hot.md smart refresh with weighted scoring, structured [ROUTE] hook output format.
v0.6.15-starter: Anti-degradation system (15 hook fixes + E2E tests), global bridge engine v1.0, sync pipeline binary handling + sanitize fix, Obsidian vault migration, manifest integrity (120 mappings / 0 dup).
v0.6.14-starter: Hybrid retrieval engine (BM25 + vector RRF + cross-encoder), batch paper metadata (batch_english_papers), CNKI batch download + WebVPN, agent-skills-catalog v2 (~132 skills), expanded .gitignore security rules.
v0.6.13-alpha: /install guided setup + install_skills v0.4.0: categorized reports, built-in skill detection, post-install verification, CNKI/Zotero awareness.
v0.6.11-alpha: Global Knowledge Bridge: /ask-pkb skill for cross-project wiki queries, intelligent path detection (PKB_ROOT env var → auto-detect → config), v0.6.9→v0.6.11 migration guide, full documentation sweep.
v0.6.10-alpha: Code review hardening: P0 crash fixes (SourceStatus import, DOI encoding, null primary_location, JSON decode errors), P1 data integrity (CRLF write, journal_rankings compatibility, cache safety), P2 determinism (stable CSL IDs, detection_threshold config, locked preservation, author name formatting), P3 observability. web_pack non-JSON response hardening.
v0.6.8-alpha: Adds scholarly metadata enrichment: literature detection, Crossref/OpenAlex metadata, local journal-ranking registry, GB/T 7714 and APA citations, /pkb integration, batch resume, and structured literature filtering.
v0.6.7-alpha: Adds MarkItDown document ingestion and web_pack v3.1 Playwright dynamic-content fallback.

Contributing

Contributions welcome! Areas we'd love help with:

Additional content type classifiers
More source format support
Platform-specific install scripts
Documentation improvements

License

MIT — see LICENSE

Built on the idea that knowledge management should be 1% human effort, 99% AI organization.

Name		Name	Last commit message	Last commit date
Latest commit History 62 Commits
.claude-plugin		.claude-plugin
.claude/commands		.claude/commands
.github		.github
docs		docs
examples		examples
migrations		migrations
scripts		scripts
skills		skills
skills_registry		skills_registry
template		template
zh-CN		zh-CN
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
COMMANDS.md		COMMANDS.md
FRESH_INSTALL_HOTFIX_CHECK.md		FRESH_INSTALL_HOTFIX_CHECK.md
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
pkb.ps1		pkb.ps1
requirements.txt		requirements.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

PKB Starter

What It Does

Features

Quick Install

Architecture

Commands

Usage with Obsidian

Getting Started

Example Scenarios

Recommended Plugins

Optional Skills

Who Is This For?

What PKB Is NOT

Web Collector (v3.1)

Playwright (optional)

MarkItDown (optional)

Updating

Privacy

Requirements

Documentation

Scholarly Metadata Enrichment

Version History

Contributing

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

PKB Starter

What It Does

Features

Quick Install

Architecture

Commands

Usage with Obsidian

Getting Started

Example Scenarios

Recommended Plugins

Optional Skills

Who Is This For?

What PKB Is NOT

Web Collector (v3.1)

Playwright (optional)

MarkItDown (optional)

Updating

Privacy

Requirements

Documentation

Scholarly Metadata Enrichment

Version History

Contributing

License

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages