Documentation

Quick Start

# Option 1: Obsidian Plugin
1. Install the plugin into Obsidian
2. Open Chat panel (Cmd+Shift+C)
3. Type /init

# Option 2: Claude Code Skill
1. Add the llm-wiki skill to Claude Code
2. Open any directory
3. Say "initialize a wiki here"

The /init command creates all directories, CLAUDE.md, index.md, and log.md — your wiki skeleton is ready. Drop an article into raw/, then type /ingest raw/your-article.md to see the magic.

Installation

Obsidian Plugin

1. Download main.js, manifest.json, and styles.css from the latest release
2. Place them in .obsidian/plugins/obsidian-llm-wiki/ inside your vault
3. Enable "LLM Wiki" in Obsidian Settings → Community Plugins
4. Install Claude Code or Cursor
5. Install the ACP bridge: npm install -g @agentclientprotocol/claude-agent-acp
6. In plugin settings, configure the ACP executable path

Claude Code Skill

1. Copy skills/llm-wiki/ to your Claude Code skills directory
2. Restart Claude Code (or reload skills)
3. Navigate to any directory and say "initialize a wiki here"

The skill creates the same wiki structure — no Obsidian required. Works with any text editor.

Plugin vs Skill

Core Operations

Five slash commands power the entire knowledge compilation pipeline. No complex UI.

/init — Initialize Wiki Structure

The first command you'll run. Creates the complete wiki skeleton — all directories, CLAUDE.md schema, index.md, and log.md. Plugin-native execution via Obsidian's Vault API, zero LLM dependency, completes in milliseconds.

Vault/
├── raw/          (tech/, work/, reading/, general/)
├── wiki/         (summaries/, concepts/, entities/, methods/, comparisons/, analysis/)
├── drafts/
├── legacy/
├── CLAUDE.md     ← LLM operation schema
├── index.md      ← Master wiki index
└── log.md        ← Operation timeline

/ingest — Compile Articles Into Wiki

The core operation. Feed an article, the LLM compiles it into the wiki. The ingest workflow:

1. Read the full source file and review the existing wiki index
2. Propose a processing plan (not ask questions) — suggested summary name, concepts/entities to create or update, risk notes — in under 10 lines
3. Wait for your one-line approval ("agreed" / "change X" / "skip Y")
4. Execute all file operations in one go: create summary page, update/create concept pages, update/create entity pages, extract methodology if applicable, add cross-references, check for contradictions, update index and log

/ingest raw/tech/transformer-paper.md

One ingest can touch 10–15 wiki pages. Source attribution is automatic — every paragraph annotated with (source: [[summary-filename]]).

/query — Wiki-Based Q&A

Ask questions grounded in your wiki. The LLM reads the index, finds relevant pages, reads them, and synthesizes answers with wikilink citations. If the answer is valuable and reusable, it can be archived as a new wiki page in wiki/analysis/. Only archived queries are logged.

/query How does self-attention differ from cross-attention?

/lint — Wiki Health Check

A comprehensive audit that checks for contradictions, orphan pages, stale content, missing pages, missing attribution, knowledge gaps, and method quality. The LLM auto-fixes what it can (merging duplicates, renaming files, adding missing links) and reports the rest in wiki/lint-report.md. Run it weekly.

• Contradictions between pages — flagged with [!warning]
• Orphan pages with no incoming links
• Stale content superseded by newer sources
• Missing pages for concepts that are mentioned but lack dedicated pages
• Missing attribution — content without source references
• Knowledge gaps with suggested search directions
• Method quality — validates method pages against quality standards

/scan — Legacy Library Indexing

For existing collections of hundreds of old notes. A lightweight scan — reads only titles and first 10 lines of each file — and generates an index map in legacy-index.md. Later, selectively migrate interesting items to raw/ for full ingest.

Tag Audit

Ask the LLM to audit your wiki's tags. It scans all frontmatter tags, identifies duplicates and near-duplicates, and suggests merges. You approve and it applies changes across all pages.

audit the tags in wiki/

The CLAUDE.md Schema

CLAUDE.md is the most important file in the system. It's not a README — it's the LLM operation schema that Claude Code reads automatically on startup. It defines the directory structure, ownership rules, wiki page format, operation procedures, and quality standards. Think of it as the compiler configuration file — edit it and the LLM adapts without any code changes.

What CLAUDE.md defines:

• Directory structure and ownership rules — who can write where (raw/ is immutable, wiki/ is LLM territory, drafts/ is human-only)
• Wiki page format — required YAML frontmatter with title, tags, sources, created, updated
• File naming — English lowercase kebab-case for all wiki files
• Operation procedures — step-by-step workflows for ingest, query, lint, and scan
• Methodology quality standards — three entry criteria, five self-check questions, mandatory page skeleton
• Wikilink rules — use filenames only, never include directory paths
• Ten iron rules — never modify raw/, always update index after changes, one ingest at a time, etc.

Key design principles baked into the schema:

• raw/ is immutable — LLM reads source files but never modifies, moves, or deletes them
• wiki/ is LLM territory — humans read wiki pages but don't edit them directly
• Knowledge must be traceable — every claim links back to its original source via wikilinks
• Contradictions are flagged, not silenced — conflicts get [!warning] callouts, never silently overwritten
• Log is append-only — operations are recorded for auditing; use tail to read recent entries

Wiki Page Types

The LLM maintains six types of pages in wiki/:

• Summary (wiki/summaries/) — one per ingested source. One-to-one mapping to raw files. Filename uses English kebab-case based on topic (never identical to raw filename).
• Concept (wiki/concepts/) — cross-source synthesis for each important concept or theme. Every paragraph annotated with source.
• Entity (wiki/entities/) — pages for notable people, tools, frameworks, organizations. Only for public figures — article authors without public visibility go in the summary's frontmatter author field.
• Method (wiki/methods/) — reusable how-to guides. Must satisfy three entry criteria: actionable, transferable, non-trivial. Strict separation from concept pages (methods answer "how to", concepts answer "what is").
• Comparison (wiki/comparisons/) — side-by-side analysis of related topics.
• Analysis (wiki/analysis/) — deep explorations, typically archived from good query answers.

Methodology Quality Standards

Method pages have the strictest quality bar in the wiki. Before creating a method page, content must pass three entry criteria:

1. Actionable — readers can follow step by step without understanding the background. "Do X; if Y, do Z", not "X is important".
2. Transferable — steps work beyond the source article's specific context. Product-specific manuals don't count.
3. Non-trivial — at least one step, rule, or anti-pattern is non-obvious. "Test before deploying" is common sense, not methodology.

All three must be satisfied. If not, no method page is created — better zero method pages than a concept page copied under the methods directory.

Source Attribution

Wiki's core value is knowledge traceability. Every piece of information must link back to its original source:

• Summary pages — frontmatter sources points to the raw source file
• Concept / Entity / Method pages — frontmatter sources lists all contributing raw files; body text uses inline citations: (source: [[summary-filename]])
• Citation filenames must match actual existing files — never invent or guess filenames

Design Decisions

Why not RAG?

For personal knowledge bases under 10,000 notes, a simple index.md works better than vector search. Zero infrastructure — no embedding pipeline or vector database. Deterministic — the index is human-readable and debuggable. Context-rich — LLM reads complete pages, not retrieved fragments. Cross-referenced — wikilinks create a browsable graph, not isolated chunks. When the wiki grows beyond the context window, RAG can complement — but start simple.

Why CLAUDE.md instead of hardcoded logic?

Everyone's knowledge needs differ. Some want a wiki/tutorials/ directory. Some don't need legacy/. Some prefer English, others Chinese. CLAUDE.md is an editable configuration file — change it and the LLM adapts. No plugin rebuild needed. It's also reusable: the same CLAUDE.md works with Claude Code, Cursor, or any LLM agent that respects the format.

Why strict directory ownership?

Unclear ownership is the root cause of wiki decay. When both human and AI edit the same files, trust erodes — you can't tell what's AI-generated vs human-curated. Clear boundaries: wiki/ is always LLM-maintained, so you can trust its structure and attribution. drafts/ is always human-only, so you have a safe scratch space.

Why no discussion during ingest?

Early versions had the LLM "discuss key points" before executing. Result: LLMs produced elegant analysis but created zero files. The fix: remove all discussion steps. The LLM proposes a brief plan (under 10 lines), you approve or adjust in one line, then it executes everything automatically. Think make build — it should produce compiled output, not a document about what it plans to compile.

Daily Workflow Loop

Once your wiki is set up, the daily rhythm is simple:

1. New article → drop into raw/ → /ingest → wiki auto-updates
2. Question → /query → good answer → archive as wiki page
3. Periodic → /lint → maintain wiki health
4. Old notes → legacy/ → /scan → index → selectively migrate to raw/

Tips & Best Practices

• Ingest one article at a time. The LLM produces better results when focused on a single source.
• Participate during ingest. The LLM proposes a plan first. Use your one-line response to steer emphasis.
• Archive great query answers. A good answer that only lives in chat history is lost. File it.
• Run lint weekly. Regular maintenance prevents accumulated mess — like running tests on code.
• Use Git. Wiki is a directory of Markdown files. Version control gives history, diff, and safety.
• Let the LLM rename files. Don't manually organize wiki pages. Lint catches bad names and the LLM fixes all references.
• Don't duplicate CLAUDE.md in prompts. Claude Code reads it automatically on startup. Redundant injection wastes tokens and increases confusion.
• Use XML tags for prompt isolation. Wrap raw source content in <raw_input role="data"> tags to prevent the LLM from executing article content as instructions.

Companion Tools

Tools that work well with LLM Wiki:

• Obsidian — browse your wiki with Graph view, Dataview for dynamic queries
• Obsidian Web Clipper — browser extension to save web pages as Markdown directly into raw/
• qmd — local Markdown search engine (BM25 + vector), complement index.md when wiki grows large
• Marp — Markdown-to-slides, generate presentations from wiki content
• Git — natural version control for a directory of Markdown files