@zosmaai/pi-llm-wiki

English | 中文 | Español | 日本語 | Deutsch | Français | Português | Русский | 한국어 | हिंदी

基于 pi 的自维护、兼容 Obsidian 的知识库。遵循 Andrej Karpathy 的 LLM Wiki 模式。 Follows Andrej Karpathy's LLM Wiki pattern.

将原始来源（网址、PDF、Markdown、JSON、XML）转化为持久、互联、由 LLM 维护的 Wiki，并随时间不断积累。

---

快速开始

pi install npm:@zosmaai/pi-llm-wiki

The extension will proactively suggest creating a wiki on your first session. Alternatively:

/wiki-init "AI Engineering"
/wiki-ingest
/wiki-query What are the key patterns?

---

为什么选择这个包？

大多数基于文件的 LLM 工作流如同一键式 RAG：每次提问时模型都会搜索原始文档。综合结果转瞬即逝。

pi-llm-wiki 创建了一个中间层：

• 原始来源包保留源头真实输入
• 来源页面总结每个来源的内容
• 规范 Wiki 页面追踪 Wiki 当前的知识状态
• 生成的元数据使所有内容可搜索和可导航

结果是一个不断累积的 Wiki——当你捕获来源、提问并归档持久分析时，知识会不断增长。

---

功能特性

Capability	Description
🏠 Personal fallback	Always-on ~/.llm-wiki/ vault — knowledge compounds across projects even when no project wiki exists
🔗 Immutable source capture	URLs, local files (PDF/md/txt/html/XML/JSON), or pasted text → structured source packets
🧠 Automated ingestion	wiki_ingest batch-processes sources into concept, entity, synthesis & analysis pages
🔍 Full-text search	Generated registry with keyword lookup across all pages and sources
🩺 Mechanical linting	Orphans, broken links, duplicate aliases, coverage gaps, stale captures
📊 Dashboard	wiki_status — counts, source states, recent activity
🤖 Auto-update watch	wiki_watch — schedule periodic discovery + ingest
🧠 Layered recall	Searches both personal (~/.llm-wiki/) and project (.llm-wiki/) vaults — personal knowledge follows you everywhere
📝 Auto-bootstrap	Extension suggests creating a wiki when none exists in the current directory
💾 Lightweight capture	wiki_retro — save atomic insights as a single markdown file; full 4-layer pipeline also available via wiki_capture_source
🌐 MCP Server	Use with Claude Code, Cursor, Windsurf via stdio MCP transport
📝 Obsidian-friendly	Folder-qualified wikilinks, stable source-ID citations, compatible vault
🛡️ Guardrails	Blocks direct edits to raw sources and generated metadata
🔧 Configurable PDF extraction	MarkItDown timeout via WIKI_MARKITDOWN_TIMEOUT_MS env var
🧪 38+ tests, CI, CodeQL	TypeScript, Vitest, Biome, Codecov

---

工具

Tool	Description
wiki_bootstrap	Initialize a new wiki vault with config, templates, schema, and metadata
wiki_capture_source	Capture a URL, local file, or pasted text into an immutable source packet
wiki_recall	Search wiki for task-relevant pages — searches both personal (~/.llm-wiki/) and project (.llm-wiki/) vaults, deduplicated
wiki_retro	Save atomic insights from completed tasks into the wiki
wiki_ingest	Process uningested source packets into wiki pages (batch)
wiki_ensure_page	Resolve or safely create entity / concept / synthesis / analysis pages
wiki_search	Search the generated wiki registry
wiki_lint	Deterministic health checks (orphans, gaps, contradictions, auto-fix)
wiki_status	Show counts, source states, and recent activity
wiki_rebuild_meta	Force a full metadata rebuild (registry, backlinks, index, log)
wiki_log_event	Append a structured event to the wiki activity log
wiki_watch	Schedule automatic wiki updates (daily / weekly / hourly)

斜杠命令

Command	Description
/wiki-init <topic>	Initialize a new LLM Wiki vault
/wiki-ingest [path]	Process new source files and update the wiki
/wiki-query <question>	Ask questions against the wiki with citations
/wiki-discover [--topic <topic>]	Auto-discover new sources from the web
/wiki-run [--schedule daily|weekly]	Full cycle: discover → ingest → lint
/wiki-lint [--fix]	Health check (orphans, contradictions, gaps)
/wiki-status	Show a concise operational summary
/wiki-digest [--period daily|weekly]	Generate a digest of recent activity
/wiki-retro	Save atomic insights from completed tasks

---

分层 Vault 架构

Knowledge follows you everywhere. pi-llm-wiki uses a layered vault system:

Layer	Location	Purpose
🏠 Personal	~/.llm-wiki/	Always active. Zero setup. Knowledge compounds across all your sessions — regardless of which project you're in.
📁 Project	{project}/.llm-wiki/	Explicit opt-in. Dedicated wiki per project, sharing personal knowledge when relevant.
🏢 Company (future)	git-tracked	Shared wiki across a team. wiki_publish promotes personal/project pages to the company wiki.

工作原理：

1. resolveVaultRoot() checks: cwd → walk up for .llm-wiki/ → ~/.llm-wiki/
2. wiki_recall (layered) searches both personal and project vaults, merging results with vault labels
3. Personal results are shown first in recall output, tagged as "📓 personal"
4. wiki_retro writes to whichever vault is active (project takes priority)
5. Set WIKI_HOME env var to override the personal wiki location

This means: you can have a project wiki for team documentation and a personal wiki for your own notes, and recall searches both simultaneously.

---

快速开始（详细）

1) 创建新 Wiki

mkdir my-wiki
cd my-wiki
pi

向 pi 提问：

Initialize an llm wiki here for AI research.

This calls wiki_bootstrap and creates:

.llm-wiki/
├── config.json
├── templates/
├── raw/
├── wiki/
├── meta/
└── WIKI_SCHEMA.md

2) 捕获来源

Capture this article into the wiki: https://example.com/some-article

Capture this PDF into the wiki: ./papers/context-windows.pdf

Capture these notes into the wiki: ...pasted text...

3) 整合来源

1. Capture the source
2. Read .llm-wiki/wiki/sources/SRC-*.md
3. Update that source page
4. Search for impacted canonical pages with wiki_search
5. Create missing pages with wiki_ensure_page
6. Update concept / entity / synthesis pages with citations
7. Mark the integration with wiki_log_event kind=integrate

4) 查询 Wiki

Based on the wiki, what are the main tradeoffs between long-context models and RAG?

By default, query mode is read-only. To file a durable answer:

Answer the question and file the result as an analysis page.

---

Vault 布局

my-wiki/
└─ .llm-wiki/
   ├─ config.json               # Vault config
   ├─ templates/                 # Page templates
   ├─ raw/
   │  └─ sources/
   │     └─ SRC-2026-05-11-001/
   │        ├─ manifest.json
   │        ├─ original/           # Original artifact
   │        ├─ extracted.md        # Normalized text
   │        └─ attachments/
   ├─ wiki/
   │  ├─ sources/                  # Source pages (what each source says)
   │  ├─ concepts/                 # Concepts and recurring ideas
   │  ├─ entities/                 # People, orgs, products, papers, systems
   │  ├─ syntheses/                # Cross-source theses and tensions
   │  └─ analyses/                 # Durable filed answers from queries
   ├─ meta/
   │  ├─ registry.json             # Auto-generated search index
   │  ├─ backlinks.json
   │  ├─ index.md
   │  ├─ events.jsonl              # Append-only event log
   │  ├─ log.md
   │  └─ lint-report.md
   └─ WIKI_SCHEMA.md               # Operating manual

所有权模型

Path	Owner	Rule
Path	Owner	Rule
------	-------	------
.llm-wiki/raw/**	Extension tools	Immutable after capture
.llm-wiki/wiki/**	Model + user	Editable knowledge pages
.llm-wiki/meta/registry.json	Extension	Generated
.llm-wiki/meta/backlinks.json	Extension	Generated
.llm-wiki/meta/index.md	Extension	Generated
.llm-wiki/meta/events.jsonl	Extension / tool	Append-only
.llm-wiki/meta/log.md	Extension	Generated from events
.llm-wiki/meta/lint-report.md	Extension	Generated
.llm-wiki/WIKI_SCHEMA.md	Human + explicit request	Operating manual

---

链接与引用风格

内部导航

[[concepts/retrieval-augmented-generation]]
[[entities/openai|OpenAI]]
[[syntheses/long-context-vs-rag]]

事实引用

[[sources/SRC-2026-04-04-001|SRC-2026-04-04-001]]

Stable source-page IDs keep provenance stable even if titles change.

---

防护措施

The extension blocks direct tool-call edits to:

• .llm-wiki/raw/** — immutable source artifacts
• .llm-wiki/meta/registry.json
• .llm-wiki/meta/backlinks.json
• .llm-wiki/meta/events.jsonl
• .llm-wiki/meta/index.md
• .llm-wiki/meta/log.md
• .llm-wiki/meta/lint-report.md

If the model directly edits .llm-wiki/wiki/** using Pi's built-in write or edit tools, the extension automatically rebuilds generated metadata at the end of the agent turn.

---

来源包格式

Each captured source is stored as a structured packet:

.llm-wiki/raw/sources/SRC-YYYY-MM-DD-NNN/
├─ manifest.json     # Capture metadata (title, URL, format, timestamp)
├─ original/         # Original artifact (preserved as-is)
├─ extracted.md      # Normalized text (PDF→md, XML→md, JSON→md, etc.)
└─ attachments/      # Future attachment downloads

This preserves both the original artifact and a normalized extracted view for reading.

---

MCP 服务器

Use the wiki from any MCP-compatible tool — Claude Code, Cursor, Windsurf, and others.

The package ships a standalone MCP server exposing 5 wiki tools over stdio:

Tool	Description
wiki_recall	Search wiki for task-relevant pages
wiki_search	Full registry search
wiki_status	Wiki stats (page counts, type breakdown)
wiki_retro	Save atomic insights
wiki_capture_source	Capture text as a source packet

使用方法

# Auto-discovered by pi:
pi install npm:@zosmaai/pi-llm-wiki

# Standalone with any MCP client:
WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js

Set WIKI_ROOT to your wiki vault directory. If unset, the server auto-detects from the current working directory.

---

技能行为

The bundled llm-wiki skill teaches the model to:

• ❌ Never edit raw sources directly
• ❌ Never edit generated metadata files
• ✅ Capture first, integrate second
• ✅ Search before creating new canonical pages
• ✅ Cite facts using source-page IDs
• ✅ Keep query mode read-only by default
• ✅ Use "Tensions / caveats" and "Open questions" when evidence is mixed

---

架构

Vault 层

See the Layered Vault Architecture section above for the personal/project/company layering.

四层页面模型

Each wiki vault has four layers with clear ownership:

.llm-wiki/raw/sources/SRC-*/     # Immutable source packets (extension-owned)
.llm-wiki/wiki/                   # Editable knowledge pages (you + LLM)
.llm-wiki/meta/                   # Auto-generated registry, backlinks, index, log
.llm-wiki/                        # Config and templates

Read docs/architecture.md for the full design document.

---

文档

Document	What it covers
Architecture	How the four layers work, ownership model
Commands	All slash commands and tool reference
Obsidian Integration	Vault setup and recommended plugins
Configuration	Wiki modes, topics, environment variables
API	Extension tool parameter reference

---

贡献

See CONTRIBUTING.md for development setup, test patterns, and PR workflow.

---

Star 历史

贡献者

---

许可证

MIT