🌐 Live Demo & Product Page · 中文版 README
Your LLM is not a chatbot. It's a persistent wiki maintainer.
An open-source framework for building a personal knowledge base where you curate sources and ask questions, while Claude Code handles all the bookkeeping — summarizing, cross-referencing, filing, quality control, and maintenance.
One interactive script. Five Claude Code skills. Zero databases. Just plain markdown files that compound over time.
Inspired by Andrej Karpathy's LLM Wiki pattern and the Obsidian local-first philosophy.
Traditional note-taking is broken:
- You write something down → forget where it is → never find it again
- Each conversation with an LLM produces insights → they vanish when the chat closes
- You accumulate hundreds of files → no cross-references, no quality control, no structure
This project fixes that by treating knowledge management as a compilation process:
Key insight from Karpathy: The LLM doesn't just answer questions — it maintains a persistent wiki. Every piece of knowledge gets compiled into interconnected pages, not dumped into isolated files.
Your Wiki/
├── CLAUDE.md # Constitution — schema, rules, workflows
├── README.md # Human-readable description
├── log.md # Append-only operation timeline
│
├── raw/ # Layer 1: Raw Sources (IMMUTABLE)
│ ├── research/ │ Human-owned. Write once, never modify.
│ │ ├── papers/ │ Conversation extracts, paper notes,
│ │ ├── notes/ │ articles, book notes, clipped web pages.
│ │ └── tools/ │
│ ├── reading/ │
│ └── assets/ │ Images, PDFs, attachments
│
├── wiki/ # Layer 2: Compiled Knowledge (LLM-OWNED)
│ ├── index.md │ Master catalog — LLM's entry point
│ ├── entities/ │ People, tools, journals, projects
│ ├── concepts/ │ Methods, theories, terms, principles
│ ├── topics/ │ Guides, norms, best practices
│ └── syntheses/ │ Archived query answers, analyses
│
└── meta/ # Layer 3: Diagnostics
└── reports/ │ Lint reports, health checks
The core rule: raw/ is history (immutable), wiki/ is truth (always current), log.md is the operation log (append-only).
Analyzes a conversation or file and compiles it into the wiki network. A single ingest typically touches 5-15 wiki pages — creating/updating entity pages, concept pages, topic pages, and weaving [[wikilinks]] between them.
Depth control: shallow (quick index) → deep (default, full extraction) → exhaustive (section-by-section with experiment data). Domain-specific checklists auto-apply based on content type (research papers, writing guides, tools).
You: ingest this conversation
Claude:
1. Analyzes content → identifies entities, concepts, topics
2. Stores raw record in raw/ (immutable)
3. Creates or updates 5-15 wiki pages
4. Weaves [[wikilinks]] for cross-references
5. Updates wiki/index.md and log.md
6. Reports what was touched
Batch mode (5+ files): Groups files by wiki-page dependencies and dispatches to parallel sub-Agents — each with its own context window — then merges results. Avoids context compaction during large imports.
What can you ingest?
| Input | How | Example |
|---|---|---|
| Current conversation | "ingest this conversation" | After a paper revision session |
| External file | "ingest this file: /path/to/notes.md" | Paper reading notes from Zotero |
| Batch files | "ingest all .md files in /path/" | Migrating old notes |
| Pasted content | Just paste + "ingest this" | Web article, email, etc. |
Answers questions based on your own accumulated knowledge, not generic LLM knowledge. Every claim cites a [[wikilink]] source. Valuable answers can be archived as synthesis pages.
You: what does my wiki say about clean code principles?
Claude:
1. Searches index + grep wiki/ for relevant pages
2. Reads and synthesizes from your pages
3. Returns answer with [[wikilink]] citations
4. Asks: "Archive this as a synthesis page?"
8 hard-coded deterministic rules + soft LLM analysis. Outputs structured reports to meta/reports/.
| # | Rule | What It Checks |
|---|---|---|
| 1 | Dead links | Every [[wikilink]] points to an existing file |
| 2 | Orphan pages | Every page has ≥1 inbound link |
| 3 | Frontmatter completeness | 7 required YAML fields present |
| 4 | Tag consistency | All tags in approved list |
| 5 | Source traceability | Entity/concept pages cite ≥1 raw source |
| 6 | Index sync | wiki/index.md matches actual files |
| 7 | File naming | Files follow naming conventions |
| 8 | Stale detection | Flags 90+ day old pages with newer sources |
Why hard-coded rules? Pure LLM judgment is unreliable for quality control — the LLM "forgets" to check certain rules. These 8 rules are deterministic and execute completely every time. Soft analysis (contradictions, thin pages, missing links) supplements them.
Designed for first-time setup or importing from other note systems (Notion, Obsidian, Roam, plain markdown). Scans a directory, auto-classifies each file, and bulk-creates raw records + wiki pages.
Three depth modes: catalog (definition only, 100+ files) → standard (default, per-checklist extraction) → deep (full analysis). Processes file #1 first for sample approval before continuing the batch.
You: migrate notes from ~/old-notes/
Claude:
1. Scans directory → found 23 markdown files
2. Shows classification plan for approval
3. Processes file #1 → sample approval → parallel sub-Agents for the rest
4. Reports: 23 files → 18 new wiki pages + 4 updated
5. Recommends: run lint, these 3 pages need more detail
Export wiki/ as a browsable static site. Quartz is the recommended default — it's purpose-built for Obsidian vaults and requires zero content conversion (native [[wikilinks]], KaTeX, graph view, backlinks).
One-command Quartz install:
bash scripts/setup-quartz.sh
cd site && npx quartz build --directory ../wiki --serve --watch --port 4321
# Open http://localhost:4321
# Edits in Obsidian auto-rebuild & refresh — no manual steps needed.Also supports MkDocs Material (formal doc-site aesthetic) and simple standalone HTML via the wiki-export skill:
You: export wiki as website
Claude:
1. Asks format preference (Quartz / MkDocs / Simple HTML)
2. For Quartz: runs scripts/setup-quartz.sh (recommended)
3. For others: converts [[wikilinks]] → standard links, generates nav/search
4. Shows deploy options (GitHub Pages, Netlify, Vercel, Cloudflare Pages)
See Quartz Static Site Setup below for details.
| Type | What It Stores | File Location | Example |
|---|---|---|---|
| Entity | Named things: people, tools, journals, projects | wiki/entities/ |
React.md, IEEE-TWC.md, Zotero.md |
| Concept | Ideas, methods, principles, patterns | wiki/concepts/ |
DRY.md, MARL.md, Clean-Code.md |
| Topic | Guides, norms, accumulated best practices | wiki/topics/ |
Git-Workflow.md, Code-Review-Guide.md |
| Synthesis | Archived query answers, comparison analyses | wiki/syntheses/ |
2026-04-10-X-vs-Y-comparison.md |
Every page has:
- YAML frontmatter: type, domain, created, updated, sources, tags, aliases
- Structured sections: Overview/Definition → Details → Common Pitfalls → Related
[[wikilink]]cross-references: bidirectional, first-mention-per-page
| Tool | Required? | Purpose |
|---|---|---|
| Claude Code | Required | The LLM engine that runs all operations |
| Obsidian | Recommended | IDE for browsing wiki (graph view, wikilinks) |
| Git | Recommended | Version control, track knowledge evolution |
| bash / zsh | Required | For the setup script |
git clone https://github.com/ZLHad/personal-knowledge-wiki.git
cd personal-knowledge-wiki
bash scripts/setup.shThe script is fully interactive with English / 中文 language support — it asks questions and builds everything for you:
Language / 语言选择:
1. English (default)
2. 中文
Choose [1/2]: 1
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 1/5: Wiki Location
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Where to create the wiki? ~/Documents/My Knowledge
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 2/5: Configure Your Domains
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Domain 1: research
Sub-categories: papers, notes, tools
Domain 2: reading
Sub-categories: books, articles
Domain 3: (enter to finish)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 3/5: Creating Wiki Structure
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[✓] raw/ (immutable sources)
[✓] wiki/ (LLM-maintained compiled knowledge)
[✓] meta/ (lint reports, diagnostics)
[✓] CLAUDE.md (wiki schema)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 4/5: Installing Claude Code Skills
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[✓] wiki-ingest → ~/.claude/skills/wiki-ingest
[✓] wiki-lint → ~/.claude/skills/wiki-lint
[✓] wiki-query → ~/.claude/skills/wiki-query
[✓] wiki-migrate → ~/.claude/skills/wiki-migrate
[✓] wiki-export → ~/.claude/skills/wiki-export
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 5/5: Obsidian Configuration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[✓] Minimal theme installed
[✓] 7 plugins downloaded and registered
[✓] Templater templates installed (4 page types)
[✓] Dataview dashboard
[✓] Claude Code project settings
# 1. Open your wiki folder in Obsidian as a vault
# 2. Enable community plugins: Settings → Community plugins → Turn off Safe Mode → Enable all
# 3. Start Claude Code (from ANY directory!)
claude
# 4. Have a productive conversation, then:
> ingest this conversation
# 5. Query your accumulated knowledge:
> search wiki: what do I know about X?
# 6. Run a health check:
> lint wikiIf you prefer to set things up yourself:
- Copy
templates/CLAUDE.mdto your wiki directory, replace{{placeholders}}with your values - Create directory structure:
raw/,wiki/{entities,concepts,topics,syntheses},meta/reports/ - Copy
templates/index.md→wiki/index.md,templates/log.md→log.md - Copy
skills/contents to~/.claude/skills/, replace{{WIKI_PATH}}in each SKILL.md - (Optional) Configure Obsidian vault manually
Once your wiki has content, you probably want a prettier web version — for personal reading on mobile, sharing with collaborators, or publishing as a public knowledge base.
Quartz is the recommended static site generator because it's purpose-built for Obsidian vaults:
| Feature | Quartz |
|---|---|
[[wikilinks]] rendering |
✅ Native (zero conversion) |
LaTeX formulas ($...$, $$...$$) |
✅ KaTeX built-in |
| Chinese content / filenames | ✅ UTF-8 support |
| Graph view | ✅ Interactive |
| Backlinks | ✅ Auto-generated |
| Hover popover previews | ✅ Built-in |
| Full-text search | ✅ FlexSearch |
| Dark mode | ✅ One-click toggle |
| Responsive (mobile) | ✅ Out of the box |
- Node.js v20+ (install)
- Your
wiki/directory must have content (runscripts/setup.shfirst if empty)
bash scripts/setup-quartz.shThe script:
- Clones Quartz into
site/(automatically gitignored) - Removes Quartz's demo content and own git history
- Installs npm dependencies (~5-10 seconds)
- Pre-configures
quartz.config.tswith sensible defaults:pageTitle: "My Knowledge Wiki" (edit to taste)baseUrl:localhost:4321(for local preview)ignorePatterns: excludesdashboard.md(Dataview blocks can't render in Quartz)
Zero wiki modification — Quartz reads your wiki via the --directory ../wiki flag, no copying or symlinking.
cd site
npx quartz build --directory ../wiki --serve --watch --port 4321Open http://localhost:4321 in your browser.
Flag breakdown:
--directory ../wiki— read content from your wiki/ directory (no copying)--serve— run the local dev server--watch— auto-rebuild on file changes (incremental, typically ~200ms per change)--port 4321— custom port (default is 8080)
Update workflow: Edit any wiki/*.md file in Obsidian → save → Quartz detects the change, does an incremental rebuild (~200ms), and your browser auto-refreshes. Zero manual steps.
Leave this server running while you work in Obsidian. Stop it with Ctrl+C when done.
On first load, verify:
- Homepage renders
wiki/index.mdas a catalog - LaTeX formulas render correctly (not raw
$$) - Wikilinks like
[[MARL]]are clickable and navigate correctly - Graph view shows node cluster (bottom-right or sidebar)
- Hover previews appear on wikilinks
- Search (Cmd/Ctrl+K) returns results
- Dark mode toggle works
- dashboard.md is NOT in sidebar (correctly excluded)
- raw/ is NOT in sidebar (never exposed)
Edit site/quartz.config.ts:
configuration: {
pageTitle: "Your Knowledge Base", // site title
locale: "en-US", // "zh-CN" for Chinese
baseUrl: "yourname.github.io/wiki", // deployment URL
ignorePatterns: [ // files to exclude
"private", "templates", ".obsidian", "dashboard.md"
],
theme: {
typography: {
header: "Schibsted Grotesk", // font pairings
body: "Source Sans Pro",
code: "IBM Plex Mono",
},
colors: { /* light/dark palette */ },
},
}Once Quartz is installed, how do changes in Obsidian reach the rendered site?
| Scenario | When to use | What happens on edit |
|---|---|---|
| A. Hot reload (recommended for writing) | You're actively editing wiki | Server running with --watch → file change detected → incremental rebuild (~200ms) → browser auto-refreshes. Zero manual steps. |
| B. On-demand preview | Occasional check | Start server temporarily: cd site && npx quartz build --directory ../wiki --serve --port 4321. Rebuild is full (~5s) but one-shot. Ctrl+C when done. |
| C. Deployed site | Public/shared | Commit wiki changes → git push → CI rebuilds and deploys (1-2 min). Details below. |
Scenario A is the default daily workflow — leave the dev server running in a terminal tab while you work in Obsidian, and every save is reflected in the browser within a second.
| Platform | How | Best for |
|---|---|---|
| GitHub Pages | cd site && npx quartz sync (pushes to gh-pages branch) |
Public repos, simplest setup |
| Cloudflare Pages | Connect git repo, set build command: cd site && npx quartz build --directory ../wiki, output: site/public |
Private repos, fastest CDN, generous free tier |
| Netlify / Vercel | Same as Cloudflare — connect repo, set build cmd and output dir | Private repos, good CI/CD ecosystem |
Deployed update workflow (Cloudflare/Netlify/Vercel):
1. Edit wiki/xxx.md in Obsidian → save
2. git add wiki/ && git commit -m "update: xxx" && git push
↓ (automatic)
3. Platform detects push → runs build command → deploys
↓ (1-2 minutes)
4. Public URL reflects the change
No manual quartz build needed — the platform handles it. If you have obsidian-git plugin, you can even commit-and-push from within Obsidian.
For private repos, Cloudflare Pages and Vercel support private git sources with public deployment.
If you want to start fresh:
rm -rf site/
bash scripts/setup-quartz.shLeaves zero trace (since site/ is gitignored). Your wiki/ is never touched.
| Problem | Solution |
|---|---|
Found 0 input files from content |
Don't use symlinks — use --directory ../wiki flag instead |
Invalid URL in 404 plugin |
Set baseUrl to a non-empty string (e.g., "localhost:4321") |
LaTeX-incompatible: Unicode text ... in math mode |
Warning only — check if you have Chinese characters inside $...$; escape them or use \text{...} |
| Port 4321 conflict | Use --port 3000 or any other free port |
npm install fails on native deps |
Try npm install --ignore-scripts |
| Chinese filenames show as URL-encoded | Normal — Quartz preserves UTF-8 but URLs are percent-encoded. Renders correctly in sidebar and search. |
You: (finish discussing a code review with Claude)
You: ingest this conversation
Claude: Analyzing conversation...
- Type: technical discussion
- Entities: ESLint, Prettier, VS Code
- Concepts: linting pipeline, auto-formatting
- Topics: Code Review Guide
Confirm? (y)
Claude: Ingest complete!
Raw record: raw/work/tools/2026-04-07-eslint-prettier-setup.md
Pages touched: 7 (3 new + 4 updated)
New: [[ESLint]], [[Prettier]], [[Linting-Pipeline]]
Updated: [[VS-Code]], [[Code-Review-Guide]], ...
You: search wiki: what are my code review best practices?
Claude: Based on your wiki:
From [[Code-Review-Guide]]:
- Always run [[ESLint]] before submitting...
- Check for [[DRY]] violations in new code...
From [[Clean-Code]]:
- Functions should do one thing...
Archive this as a synthesis page? (y/n)
You: lint wiki
Claude: Wiki Lint Report - 2026-04-07
| Check | Status | Issues |
|--------------------|--------|--------|
| 1. Dead links | PASS | 0 |
| 2. Orphan pages | FAIL | 2 |
| 3. Frontmatter | PASS | 0 |
...
Overall: 7/8 passed, 1 warning
Auto-fix orphan pages? (y/n)
All five skills are installed to ~/.claude/skills/ with your wiki path hardcoded. You can trigger them from any project directory:
# Working on a React project
cd ~/projects/my-app
claude
> ingest this conversation # → saves to your wiki, not the React project
# Working on a paper
cd ~/papers/my-paper
claude
> search wiki: how to write related work? # → queries your wiki| Operation | Trigger Phrases |
|---|---|
| Ingest | "ingest this conversation", "save to wiki", "extract knowledge", "wiki ingest", "update knowledge base" |
| Query | "search wiki", "wiki query", "check knowledge base", "what does my wiki say about", "look up in wiki" |
| Lint | "lint wiki", "wiki health check", "wiki diagnostics", "check wiki" |
| Migrate | "migrate notes", "import notes", "batch import", "migrate from Notion" |
| Export | "export wiki", "publish wiki", "build wiki site", "generate static site" |
As your interests grow, you can add new knowledge domains at any time:
You: add a "programming" category to the knowledge base
Claude: (automatically modifies three places)
1. CLAUDE.md — adds raw/programming/ to architecture + "programming" tag
2. wiki-ingest SKILL.md — adds domain routing
3. Creates raw/programming/ directory
The setup script configures Obsidian as the visual "IDE" for your wiki.
| Component | Purpose | Why |
|---|---|---|
| Minimal (theme) | Clean wiki-style typography | By Obsidian CEO kepano; best Dataview table styling |
| Dataview | Dynamic tables from YAML frontmatter | Query pages by domain, tag, update date |
| Templater | Template engine for new pages | Quick-create pages with correct frontmatter |
| Obsidian Git | Auto-backup via git | Full history, rollback, multi-device sync |
| Tag Wrangler | Batch rename/merge tags | Essential for frontmatter-heavy vaults |
| Style Settings | Theme customization GUI | Adjust colors, fonts, layout without CSS |
| Iconize | File/folder icons | Visual category indicators in sidebar |
| Excalidraw | Embedded whiteboard/diagrams | Concept maps, architecture diagrams |
| Action | How |
|---|---|
| Jump to page | Cmd+O → type page name |
| Follow wikilink | Cmd+Click on [[link]] |
| Graph view | Cmd+G or sidebar icon |
| Global search | Cmd+Shift+F |
Add this to any page to see a dynamic table:
```dataview
TABLE domain, updated, tags
FROM "wiki/concepts"
SORT updated DESC
```- Human and LLM can both read/write directly
git diffshows knowledge evolution clearly- Obsidian-compatible out of the box
- Zero dependencies — no database, no vector store, no server
Wiki pages represent compiled truth — the latest understanding. When new knowledge contradicts old content, the old content gets replaced. History is preserved in raw/ (immutable source records) and log.md (operation timeline), not in wiki pages.
The old pattern of "one conversation → one standalone file" creates knowledge silos. Requiring each ingest to update the entire wiki network — entities, concepts, topics, cross-references — ensures knowledge is woven, not archived. The value compounds as cross-references multiply.
Plain-text files on disk, extensive plugin ecosystem, high composability with other tools. As the Obsidian team puts it: Obsidian is the browser, the LLM is the engine.
personal-knowledge-wiki/
├── README.md # English documentation (this file)
├── README_CN.md # Chinese documentation
├── LICENSE # MIT License
├── cover-constellation.jpg # Banner — knowledge graph constellation
├── cover-architecture.jpg # Architecture — compilation pipeline
│
├── scripts/
│ └── setup.sh # Interactive one-command setup (EN/中文)
│
├── skills/ # Claude Code skills (→ ~/.claude/skills/)
│ ├── wiki-ingest/ # Knowledge ingestion
│ │ ├── SKILL.md
│ │ └── references/ # Extraction strategy guides
│ │ ├── academic-writing-guide.md
│ │ ├── technical-task-guide.md
│ │ └── reading-notes-guide.md
│ ├── wiki-lint/ # 8 hard rules + soft analysis
│ │ └── SKILL.md
│ ├── wiki-query/ # Multi-strategy search + synthesis
│ │ └── SKILL.md
│ ├── wiki-migrate/ # Batch import from other systems
│ │ └── SKILL.md
│ └── wiki-export/ # Static site generation
│ └── SKILL.md
│
├── templates/ # Template files with {{placeholders}}
│ ├── CLAUDE.md # Wiki schema template
│ ├── index.md # Empty index template
│ ├── log.md # Initial log template
│ ├── settings.json # Claude Code project settings
│ └── obsidian/ # Obsidian templates
│ ├── entity-template.md # Templater: entity page
│ ├── concept-template.md # Templater: concept page
│ ├── topic-template.md # Templater: topic page
│ ├── synthesis-template.md # Templater: synthesis page
│ └── dashboard.md # Dataview dashboard (8 queries)
│
└── examples/ # Example wiki pages
├── entity-example.md # React (entity)
├── concept-example.md # DRY principle (concept)
├── topic-example.md # Code Review Best Practices (topic)
└── synthesis-example.md # When to Abstract vs Duplicate (synthesis)
This is a framework, not a product. Fork it, customize it, make it yours.
- Additional extraction guides (meeting notes, code review, lecture notes)
- CSS snippets for enhanced wiki styling in Obsidian
- Additional lint rules (circular references, broken images, etc.)
- Spaced repetition skill (surface pages for periodic review)
- Multi-vault support (separate vaults for work/personal)
- Automated periodic lint via cron / git hooks
- Knowledge graph statistics dashboard in
meta/
- Fork the repository
- Create a feature branch (
git checkout -b feature/new-extraction-guide) - Make your changes
- Submit a Pull Request
Q: Does this work with GPT / other LLMs? A: The skills are written for Claude Code, but the architecture (CLAUDE.md schema, directory structure, page formats) is LLM-agnostic. You could adapt the skills for other LLM tools.
Q: Can I use this without Obsidian? A: Yes. Obsidian is optional — it's just a nice viewer. The wiki is plain markdown files. Any editor works. You lose graph view and wikilink navigation, but the core system works fine.
Q: How big can the wiki get? A: There's no hard limit. The system uses plain text files + YAML frontmatter, which scales to thousands of pages. Obsidian handles large vaults well. The LLM reads pages on-demand via index.md, so it doesn't need to load everything.
Q: Is my data private? A: Everything stays on your local machine. No data is sent anywhere except to the Claude API during active conversations (same as normal Claude Code usage). The wiki files are just markdown on disk.
Q: Can I sync across devices? A: Push your wiki to a private GitHub repo. The setup script can initialize git for you. Obsidian Git plugin handles auto-commit/push.
- Andrej Karpathy — LLM Wiki pattern and the core insight
- Obsidian — Local-first knowledge IDE
- Claude Code — LLM engine powering all operations
- Author: ZLHad
- Email: zhangczssx@gmail.com
- Issues: GitHub Issues
MIT — Use it however you want. Attribution appreciated but not required.