` | Capture the completed task's trajectory (requires trajectories enabled) | | `/wiki-skills [query]` | Search distilled skills + past cases (requires trajectories enabled) | --- ## Layered Vault Architecture 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. | **How it works:** 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. --- ## Quick Start (Detailed) ### 1) Create a new wiki ```bash mkdir my-wiki cd my-wiki pi ``` Ask 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 a source ``` 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) Integrate the source 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) Query the 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 Layout ``` 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 ``` ### Ownership Model | 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 | Authoritative append-only state; back up for activity continuity | | `.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 | ### Activity history, backup, and portability `meta/events.jsonl` is the authoritative source for recorded extension activity. Unlike registry, backlinks, indexes, logs, and embeddings, it cannot be rebuilt from wiki pages or raw packets. Preserve it when backing up or Git-synchronizing a complete pi-llm-wiki vault. `meta/log.md` and OKF-mode `wiki/log.md` are generated views. `wiki/log.md` can travel with the OKF bundle as a readable snapshot, but it cannot reconstruct or resume the originating JSONL stream. Manual page edits are intentionally absent, so this is selected extension activity rather than a complete revision audit. File-capture events omit machine-local paths from the public log projection. Callers of `wiki_log_event` still control arbitrary detail fields and must not record secrets or private host paths. --- ## Linking & Citation Style ### Internal Navigation ```markdown [[concepts/retrieval-augmented-generation]] [[entities/openai|OpenAI]] [[syntheses/long-context-vs-rag]] ``` ### Factual Citations ```markdown [[sources/SRC-2026-04-04-001|SRC-2026-04-04-001]] ``` Stable source-page IDs keep provenance stable even if titles change. --- ## Guardrails 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. --- ## Source Packet Format 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 Server Use the wiki from **any MCP-compatible tool** — Claude Code, Cursor, Windsurf, and others. The package ships a standalone MCP server exposing 6 wiki tools over stdio: | Tool | Description | |------|-------------| | `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata | | `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 | ### Usage ```bash # 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/dist/mcp/index.js ``` Set `WIKI_ROOT` to your wiki vault directory. If unset, the server auto-detects from the current working directory. ### Client configuration The same server as an entry in `.mcp.json` (Claude Code) or `claude_desktop_config.json`: ```json { "mcpServers": { "llm-wiki": { "command": "node", "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"], "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" } } } } ``` > MCP clients spawn the command **without a shell**, so `~` is never expanded. A `~/my-wiki` in `args` or `env` is passed through literally and the server fails to start, which the client reports only as a generic connection error — use absolute paths here. The shell snippet above is fine: your shell expands `~` before `node` sees it. --- ## Skill Behavior 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 --- ## Architecture ### Vault Layers See the [Layered Vault Architecture](#layered-vault-architecture) section above for the personal/project/company layering. ### Four-Layer Page Model 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/ # Durable event source + generated internal projections .llm-wiki/ # Config and templates ``` Read [docs/architecture.md](docs/architecture.md) for the full design document. --- ## Documentation | Document | What it covers | |----------|---------------| | [Architecture](docs/architecture.md) | How the four layers work, ownership model | | [Commands](docs/commands.md) | All slash commands and tool reference | | [Obsidian Integration](docs/obsidian.md) | Vault setup and recommended plugins | | [Configuration](docs/configuration.md) | Wiki modes, topics, environment variables | | [API](docs/api.md) | Extension tool parameter reference | --- ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, test patterns, and PR workflow. --- <div align="center"> <a href="https://github.com/zosmaai/pi-llm-wiki/stargazers"> <img src="./assets/thank-you-for-the-star.png" alt="Thank you for starring pi-llm-wiki!" width="100%" /> </a> If you find pi-llm-wiki useful, <a href="https://github.com/zosmaai/pi-llm-wiki">⭐ star the repo</a> — it lets us know we're building something that matters. </div> ## Contributors Thanks to everyone who has contributed! This list is regenerated automatically by [`.github/workflows/contributors.yml`](.github/workflows/contributors.yml) — see [#60](https://github.com/zosmaai/pi-llm-wiki/issues/60) for the rationale.  <table> <tbody> <tr> <td align="center"> <a href="https://github.com/arjun-zosma"> <img src="https://avatars.githubusercontent.com/u/25246034?v=4" width="64;" alt="arjun-zosma"/> Arjun Nayak </a> </td> <td align="center"> <a href="https://github.com/Shanvit7"> <img src="https://avatars.githubusercontent.com/u/64424817?v=4" width="64;" alt="Shanvit7"/> Shanvit S Shetty </a> </td> <td align="center"> <a href="https://github.com/jfraser"> <img src="https://avatars.githubusercontent.com/u/165964?v=4" width="64;" alt="jfraser"/> James Fraser </a> </td> <td align="center"> <a href="https://github.com/mkuhl"> <img src="https://avatars.githubusercontent.com/u/61073?v=4" width="64;" alt="mkuhl"/> Mike P. Kuhl </a> </td> <td align="center"> <a href="https://github.com/CelestialCreator"> <img src="https://avatars.githubusercontent.com/u/177931942?v=4" width="64;" alt="CelestialCreator"/> Akshay </a> </td> <td align="center"> <a href="https://github.com/xcsf"> <img src="https://avatars.githubusercontent.com/u/43439835?v=4" width="64;" alt="xcsf"/> xcsf </a> </td> <td align="center"> <a href="https://github.com/danielnaab"> <img src="https://avatars.githubusercontent.com/u/136512?v=4" width="64;" alt="danielnaab"/> Daniel Naab </a> </td> <td align="center"> <a href="https://github.com/deestax"> <img src="https://avatars.githubusercontent.com/u/152369481?v=4" width="64;" alt="deestax"/> Superdao </a> </td> </tr> <tr> <td align="center"> <a href="https://github.com/mystery4f"> <img src="https://avatars.githubusercontent.com/u/40482524?v=4" width="64;" alt="mystery4f"/> 标准萌新 </a> </td> </tr> <tbody> </table>  Full history: [contributors graph](https://github.com/zosmaai/pi-llm-wiki/graphs/contributors). --- <div align="center"> Built with ❤️ by <a href="https://github.com/zosmaai">zosmaai</a> · <a href="https://pi.dev">pi.dev</a> · <a href="https://github.com/zosmaai/pi-llm-wiki/issues">Issues</a> </div> ## License MIT

# @zosmaai/pi-llm-wiki **English** | 中文 | Español | 日本語 | Deutsch | Français | Português | Русский | 한국어 | हिंदी [![CI](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/ci.yml/badge.svg)](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/@zosmaai/pi-llm-wiki)](https://www.npmjs.com/package/@zosmaai/pi-llm-wiki) [![npm downloads](https://img.shields.io/npm/dm/@zosmaai/pi-llm-wiki)](https://www.npmjs.com/package/@zosmaai/pi-llm-wiki) [![Coverage](https://img.shields.io/badge/coverage-85.09%25-brightgreen.svg)](https://codecov.io/gh/zosmaai/pi-llm-wiki) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) [![CodeQL](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml/badge.svg)](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml) [![GitHub Repo Stars](https://img.shields.io/github/stars/zosmaai/pi-llm-wiki?style=social)](https://github.com/zosmaai/pi-llm-wiki/stargazers)