Local Wiki RAG: LightRAG Graph Stack

The wiki uses a two-retrieval-path architecture: qmd for fast lexical+vector search inside Claude Code sessions, and LightRAG for graph-aware synthesis in th…

Local Wiki RAG: LightRAG Graph Stack

The wiki uses a two-retrieval-path architecture: qmd for fast lexical+vector search inside Claude Code sessions, and LightRAG for graph-aware synthesis in the TUI and MCP server. Both run locally at zero cost by default; LightRAG can optionally use Claude Haiku for higher-quality synthesis.

---

Architecture

wiki/ pages
    │
    ├─── qmd index (BM25 + vector)          ← wiki-context skill → Claude Code
    │    Updated by: post-commit hook (synchronous)
    │
    └─── LightRAG graph (.lightrag/)        ← wiki-chat TUI + wiki-mcp MCP server
         Updated by: wiki-index (background, post-commit)

Why two paths

Dimension	qmd	LightRAG
Retrieval type	BM25 + vector hybrid	entity/community graph traversal
Synthesis	Claude Sonnet (in-session)	qwen2.5:3b local or Claude Haiku
Latency	~1s	~15–30s (LLM synthesis)
Best for	In-session lookup, citation	Cross-concept questions, relationships
Cost	API (synthesis)	Free local; optional Haiku for quality
Available in	Claude Code, OpenCode	Anywhere (TUI or MCP)

The agentic-search-vs-rag experiment validated the LightRAG path: graph search achieved 2× retrieval IoU with 99% fewer tokens vs flat RAG. See Agentic Search Vs Rag.

---

Tools

wiki-chat — interactive TUI

wiki-chat                   # hybrid mode (default)
wiki-chat --mode local      # entity/concept-focused
wiki-chat --mode global     # community summaries, big-picture

Always uses qwen2.5:3b via ollama — no API cost, no API key required. Modes match LightRAG’s query modes (local/global/hybrid/naive).

TUI prompt commands:

• /mode local|global|hybrid|naive — switch mid-session
• /reindex — trigger wiki-index for new pages
• /status — show manifest stats

wiki-index — graph indexer

wiki-index              # incremental (new/changed pages only)
wiki-index --full       # wipe and rebuild from scratch
wiki-index --status     # show manifest stats without indexing
wiki-index --test       # verify LLM backend then exit

Extraction backend (controlled by .env):

• ANTHROPIC_API_KEY set → Claude Haiku (better entity/relation extraction)
• unset → qwen2.5:3b via ollama (free — recommended for full rebuilds)

Cost warning: LightRAG runs 3 extraction phases per page (entity → relation → community), each with multiple LLM calls. A full rebuild of ~150 pages with Haiku costs $10–30, not pennies. Use qwen2.5:3b for full rebuilds; Haiku is acceptable for incremental updates (1–3 new pages per ingest).

Incremental by default: a manifest.json tracks {path: mtime}. Only changed/new pages are re-extracted. The manifest is saved after each page so partial runs resume automatically.

The post-commit hook triggers wiki-index in the background after any commit touching wiki/. Progress: tail -f .lightrag/last-index.log.

wiki-mcp — MCP server

Zero-cost wiki queries from Claude Code or OpenCode. Exposes two tools:

• wiki_query(question, mode="hybrid") — graph-aware synthesis
• wiki_status() — show index stats

Synthesis backend: same hybrid logic as wiki-index (Haiku if key set, qwen2.5:3b otherwise). LightRAG graph is initialized once as a singleton; retrieval is always local (nomic-embed-text + graph traversal).

Wire into OpenCode (~/.config/opencode/opencode.json):

"wiki-rag": {
  "type": "local",
  "command": ["/Users/<user>/.local/bin/wiki-mcp"],
  "enabled": true
}

---

Setup

cd ~/repos/llm-wiki
bash claude-setup/scripts/install.sh

install.sh handles: copying binaries to ~/.local/bin, setting up the post-commit hook, pulling qwen2.5:3b and nomic-embed-text via ollama. uv handles Python deps via PEP 723 inline metadata — no pip or venv needed.

One-time graph build (required before wiki-chat or wiki-mcp):

wiki-index --test      # verify backend
wiki-index --full      # build (~30–60 min for ~150 pages with local LLM)

After initial build, the post-commit hook keeps the graph current automatically.

---

Design choices

Graph over flat RAG

Per Agentic Search Vs Rag: graph search wins on cross-concept queries (99% fewer tokens, 2× IoU). Flat RAG only wins on explicit dependency recall. The wiki’s primary use case — “how do X and Y relate?”, “what patterns apply to problem Z?” — is exactly where graph search wins.

One concept per page = natural graph nodes

The wiki rule “one thing per page” (CLAUDE.md) makes each page a clean entity for LightRAG to extract. Entities extracted from concepts/context-degradation naturally link to concepts/context-compression, concepts/ralph-loop, etc. Cross-links become graph edges.

qwen2.5:3b for local synthesis

Better structured output for entity extraction than phi4-mini. Fits comfortably in M1 Pro 16GB and RTX 2060 6GB. For higher-quality extraction at index time: use ANTHROPIC_API_KEY — Haiku costs ~$0.001 per page at current pricing.

Manifest-based incremental indexing

Building the full graph from scratch takes ~30–60 min for 150 pages with a local LLM. The manifest approach means each new ingest only costs extraction time for the new pages (typically 1–3 pages). Post-commit automation makes this transparent.

---

Performance

Metric	Value
Initial build (qwen2.5:3b local, ~150 pages)	~30–60 min, free
Initial build (Claude Haiku, ~150 pages)	faster, but $10–30
Incremental update (1–3 new pages, Haiku)	~1–5 min, ~$0.07–0.60
Incremental update (1–3 new pages, local)	~5–15 min, free
Query latency (wiki-chat, local)	~15–30s
Retrieval quality vs flat RAG	2× IoU, 99% fewer tokens

---

Related

• Agentic Search Vs Rag — experiment validating graph search for this wiki
• Local Rag Elasticsearch — stack comparison; retrieval latency benchmarks
• Contextual Retrieval — chunk context technique; wiki pages are pre-contextualized (one concept per page)
• BM25 — lexical retrieval used by qmd (wiki-context path)
• Reranking — post-retrieval filtering; not yet applied here
• qmd — BM25 + vector engine for the wiki-context skill path
• Wikilink Graph Extraction: Reducing LightRAG Indexing Cost — Obsidian wikilink hints injected at chunk time to reduce LightRAG extraction cost ~40–55%