![llm_wiki_banner](/docs/assets/llm_wiki_banner.webp) # ๐Ÿง  Karpathy LLM Wiki Plugin for Obsidian > AI-powered structured knowledge base that ingests your notes and generates a connected Wiki โ€” based on [Andrej Karpathy's LLM Wiki concept](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). > > **Obsidian official score 95/100** | Native support for 8 languages | Actively maintained, continuously evolving [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/green-dalii/obsidian-llm-wiki) [![Release Obsidian plugin](https://github.com/green-dalii/obsidian-llm-wiki/actions/workflows/release.yml/badge.svg)](https://github.com/green-dalii/obsidian-llm-wiki/actions/workflows/release.yml) ![Version](https://img.shields.io/github/v/release/green-dalii/obsidian-llm-wiki?style=flat-square) ![Author](https://img.shields.io/badge/author-Greener--Dalii-blue?style=flat-square) ![License](https://img.shields.io/badge/license-MIT-green?style=flat-square) ![Maintenance](https://img.shields.io/badge/maintenance-actively%20maintained-brightgreen?style=flat-square) ![Build Status](https://img.shields.io/github/actions/workflow/status/green-dalii/obsidian-llm-wiki/release.yml?style=flat-square) ![Obsidian Compatibility](https://img.shields.io/badge/obsidian-1.6.6%2B-purple?style=flat-square) ![GitHub Stars](https://img.shields.io/github/stars/green-dalii/obsidian-llm-wiki?style=flat-square) ![Downloads](https://img.shields.io/badge/dynamic/json?logo=obsidian&color=483699&label=downloads&query=$[karpathywiki].downloads&url=https://raw.githubusercontent.com/obsidianmd/obsidian-releases/master/community-plugin-stats.json&style=flat-square) ![Languages](https://img.shields.io/badge/languages-8-informational?style=flat-square) ![Providers](https://img.shields.io/badge/providers-8%2B-cyan?style=flat-square) [English](README.md) | [ไธญๆ–‡ๆ–‡ๆกฃ](docs/README_CN.md) | [ๆ—ฅๆœฌ่ชž](docs/README_JA.md) | [ํ•œ๊ตญ์–ด](docs/README_KO.md) | [Deutsch](docs/README_DE.md) | [Franรงais](docs/README_FR.md) | [Espaรฑol](docs/README_ES.md) | [Portuguรชs](docs/README_PT.md) [Official Site](https://llmwiki.greenerai.top/) | [Blog](https://llmwiki.greenerai.top/blog/) | [Feedback & Discussion](https://github.com/green-dalii/obsidian-llm-wiki/discussions) | [๐Ÿค– Explore Repo with DeepWiki](https://deepwiki.com/green-dalii/obsidian-llm-wiki) --- ## ๐Ÿ“‘ Contents - [๐Ÿ’ก What is LLM-Wiki?](#-what-is-llm-wiki) - [โšก Why Obsidian + LLM-Wiki?](#-why-obsidian--llm-wiki) - [๐Ÿš€ Quick Start](#-quick-start) - [๐Ÿ“ฆ Installation](#-installation) - [๐Ÿ”„ Updating](#-updating) - [๐Ÿ”‘ Configure an LLM Provider](#-configure-an-llm-provider) - [๐ŸŽฎ Usage](#-usage) - [โš ๏ธ Upgrading from an Older Version?](#๏ธ-upgrading-from-an-older-version) - [โšก What's New in v1.16.0](#-whats-new-in-v1160) - [โœจ Features](#-features) - [๐Ÿ“Š Knowledge Quality](#-knowledge-quality) - [๐Ÿ› ๏ธ Maintenance](#๏ธ-maintenance) - [๐Ÿ’ฌ Query & Feedback](#-query--feedback) - [๐ŸŒ LLM & Language](#-llm--language) - [๐Ÿ—๏ธ Architecture & Performance](#๏ธ-architecture--performance) - [๐Ÿ”’ Privacy & Security](#-privacy--security) - [โŒจ๏ธ Commands](#๏ธ-commands) - [๐Ÿ“– Example](#-example) - [๐Ÿค– Model Selection Guide](#-model-selection-guide) - [๐Ÿ—๏ธ Architecture](#๏ธ-architecture) - [โ“ FAQ](#-faq) - [๐Ÿ’ก General](#-general) - [๐Ÿท๏ธ Aliases & Duplicates](#๏ธ-aliases--duplicates) - [โšก Performance & Cost](#-performance--cost) - [๐Ÿงน Maintenance](#-maintenance) - [๐Ÿ” Troubleshooting](#-troubleshooting) - [๐Ÿ”’ Transparency & Compliance](#-transparency--compliance) - [๐Ÿ“œ License](#-license) - [๐Ÿ™ Acknowledgments](#-acknowledgments) --- ## ๐Ÿ’ก What is LLM-Wiki? You write. AI organizes. You ask. That's it. **๐ŸŽฏ The problem.** Your notes are a goldmine โ€” people, concepts, ideas, connections. But right now they're just files in folders. Finding what relates to what means searching, tagging, and hoping you remember the thread. **โœจ The fix.** [Andrej Karpathy suggested](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) something elegant: treat your notes as raw material, and let an LLM do the architect work. It reads what you write, pulls out entities and concepts, and weaves them into a structured Wiki โ€” complete with `[[bidirectional links]]`, an auto-generated index, and a chat interface that answers questions from *your* knowledge. **๐Ÿ“š So you don't have to be the librarian.** No deciding what deserves a page. No maintaining cross-links. No wondering if something is out of date. Drop notes into `sources/` and the LLM reads, extracts, writes, links, and even flags contradictions โ€” while you stay in flow. **๐Ÿค– And it's not another chatbot.** ChatGPT knows the internet. LLM-Wiki knows *you* โ€” or rather, what you've taught it. Every answer carries `[[wiki-links]]` back into your knowledge graph. Every response is a trailhead, not a dead end. --- ## โšก Why Obsidian + LLM-Wiki? Obsidian is brilliant at linked thinking. But there's a catch: you're the one doing all the linking. LLM-Wiki flips that. Instead of you building the graph by hand, the AI grows it with you. Add a note about a new concept โ€” it finds the connections you'd miss. Ask a question โ€” it walks your own knowledge graph and brings back answers with citations. - **๐Ÿ”— Your Graph View comes alive.** New notes don't just sit there โ€” they sprout links to entities, concepts, and sources. The graph grows organically, and the plugin maintains it: detecting duplicates, fixing dead links, bridging languages with aliases. - **๐Ÿ’ฌ Your notes learn to talk back.** Search becomes conversation. "What did I write about X?" becomes a dialogue, with streaming responses and `[[wiki-links]]` as breadcrumbs. Every answer is a path deeper into your own knowledge. - **๐Ÿง  Obsidian becomes a thinking partner.** It stops being a cabinet for notes and starts being something that helps you *think* โ€” surfacing hidden connections, flagging contradictions, remembering what you forgot you knew. --- ## ๐Ÿš€ Quick Start ### ๐Ÿ“ฆ Installation **๐ŸŒŸ Recommended โ€” Obsidian Community Plugin Market:** 1. In Obsidian, go to **Settings โ†’ Community plugins** 2. Click **Browse** and search for "Karpathy LLM Wiki" 3. Click **Install**, then **Enable** **๐ŸŒ Or from the Community Plugin website โ€”** visit [community.obsidian.md/plugins/karpathywiki](https://community.obsidian.md/plugins/karpathywiki) and click **Add to Obsidian** to install directly. **โš™๏ธ Manual (alternative):** 1. Download `main.js`, `manifest.json`, `styles.css` from [Releases](https://github.com/green-dalii/obsidian-llm-wiki/releases) 2. In Obsidian, go to Settings โ†’ Community plugins. On the **Installed plugins** tab, click the folder icon to open your plugins directory 3. Create a folder named `karpathywiki`, drop the three files inside 4. Back in Obsidian, click the refresh icon โ€” **Karpathy LLM Wiki** will appear under Installed plugins 5. Toggle it on to enable **๐Ÿ”จ Development:** `git clone`, `pnpm install`, `pnpm build`. ### ๐Ÿ”„ Updating This project evolves rapidly โ€” new features, bug fixes, and improvements are shipped frequently. We recommend keeping up to date: **Option A โ€” Manual update (recommended):** 1. Go to **Settings โ†’ Community plugins** 2. Click **Check for updates** 3. Find **Karpathy LLM Wiki** in the list and click **Update** **Option B โ€” Enable auto-update:** 1. Go to **Settings โ†’ Community plugins** 2. Toggle on **Automatically check for plugins updates** 3. New versions will be detected automatically; update manually at your convenience > ๐Ÿ’ก **Why stay updated?** Each release may include new features, performance improvements, and important bug fixes. We actively maintain this plugin โ€” missing updates means missing out on a better experience. ### ๐Ÿ”‘ Configure an LLM Provider 1. Open Settings โ†’ Karpathy LLM Wiki 2. Pick a provider from the dropdown (Anthropic, Anthropic Compatible, Google Gemini, OpenAI, DeepSeek, Kimi, GLM, Ollama, OpenRouter, or custom) 3. Enter your API key (not needed for Ollama) 4. Click **Fetch Models** to populate the model dropdown, or type a model name manually 5. Click **Test Connection**, then **Save Settings** **๐Ÿฆ™ Ollama (local, no API key):** Install [Ollama](https://ollama.com), pull a model (`ollama pull gemma4`), select "Ollama (Local)" in the provider dropdown. > See [Model Selection Guide](#-model-selection-guide) for details. ### ๐ŸŽฎ Usage | Method | How | |--------|-----| | **๐Ÿ“ฅ Ingest single source** | `Cmd+P` โ†’ "Ingest single source" โ€” select a note to extract entities and concepts into Wiki pages | | **๐Ÿ“‚ Ingest from folder** | `Cmd+P` โ†’ "Ingest from folder" โ€” pick a folder, batch generate Wiki from all notes inside | | **๐Ÿ” Query wiki** | `Cmd+P` โ†’ "Query wiki" โ€” ask questions, get streaming answers with `[[wiki-links]]` | | **๐Ÿ› ๏ธ Lint wiki** | `Cmd+P` โ†’ "Lint wiki" โ€” health scan: duplicates, dead links, empty pages, orphans, missing aliases | | **๐Ÿ“‹ Regenerate index** | `Cmd+P` โ†’ "Regenerate index" โ€” rebuild `wiki/index.md` with current pages and aliases | | **๐Ÿ’ก Suggest schema updates** | `Cmd+P` โ†’ "Suggest schema updates" โ€” LLM analyzes Wiki and proposes schema improvements | | **๐ŸŽฏ One-click ingest** | Click the `sticker` icon in the left sidebar or `Cmd+P` โ†’ "Ingest current file" โ€” directly ingest the file you're editing | Re-ingesting the same source does incremental updates on entity/concept pages (new info merged in). Summary pages are regenerated. **๐Ÿ’ก Smart Batch Skip:** When ingesting a folder, the plugin automatically detects already-processed files and skips them to save time and API costs. The batch report shows skipped count. ### โš ๏ธ Upgrading from an Older Version? **This release is fully backward-compatible.** v1.14.0 contains no breaking changes โ€” your existing wiki pages, settings, and workflows are preserved. No reconfiguration or data migration needed. **If your existing Wiki was built across many versions**, some pages may lack recent capabilities (aliases, alias-aware dedup, modernized prompts). Run **Lint Wiki** to see what needs attention. Smart Fix All handles the most common cleanups in one click. **If upgrading from a version before v1.14.0**, run **Lint Wiki** once to automatically fix historical issues: - **Double-nested links** `[[[[entities/Foo|Foo]]]]` in log.md โ€” Lint detects and fixes these with zero LLM cost - **Cross-directory stub duplicates** โ€” pages that exist in both `entities/` and `concepts/` with the same slug are now correctly matched **For wikis built across many versions**, follow these steps to bring your Wiki up to current standards: **1๏ธโƒฃ Rebuild your index** `Cmd+P` โ†’ **"Regenerate index"** โ€” This rebuilds `wiki/index.md` with alias entries for every page, enabling alias-aware search (e.g., searching "DSA" finds "DeepSeek-Sparse-Attention"). The old index format only listed page titles. **2๏ธโƒฃ Run Lint wiki** `Cmd+P` โ†’ **"Lint wiki"** โ€” This scans your entire Wiki and shows: - **๐Ÿท๏ธ Missing aliases**: Pages without aliases (any version, if you never ran "Complete Aliases"). Click **"Complete Aliases"** โ€” the LLM generates translations, acronyms, and alternate names in bulk. This is critical for duplicate detection. - **๐Ÿ”„ Duplicate pages**: Pages with overlapping content (e.g., "CoT" vs "ๆ€็ปด้“พ" created by older versions that didn't have alias-aware dedup). Click **"Merge Duplicates"** to fuse them and preserve all aliases. - **๐Ÿ’€ Dead links / Empty pages / Orphans**: Standard wiki maintenance issues. **3๏ธโƒฃ Use Smart Fix All** Click **"Smart Fix All"** in the Lint report for a one-click, causality-ordered repair: aliases completed โ†’ duplicates merged โ†’ dead links fixed โ†’ orphans linked โ†’ empty pages expanded. This is the fastest way to clean up a wiki built across many versions. **4๏ธโƒฃ Enable parallel page generation** Settings โ†’ **Ingestion Acceleration**: - **โšก Page Generation Concurrency**: Set to 3 for most providers. Speeds up ingestion 2โ€“3ร— on sources with 10+ entities. - **โฑ๏ธ Batch Delay**: Start at 300ms. Increase to 500โ€“800ms if you hit rate limits. **5๏ธโƒฃ Review current settings:** - **๐ŸŒ Wiki Output Language**: Independent from UI language โ€” your Wiki can be in Chinese while the plugin UI stays in English, or vice versa. - **๐Ÿ“Š Extraction Granularity**: Five options control how deeply the LLM extracts entities from sources: - **Fine** (~100 items) โ€” Deep analysis, edge-case mentions included. High token cost, best for key sources. - **Standard** (~50 items) โ€” Balanced extraction. Good default for daily notes. - **Coarse** (~10 items) โ€” Quick overview, core entities only. Low cost, fast ingestion. - **Minimal** (~5 items) โ€” Essential items only. Ideal for batch processing 100+ files or testing new sources. - **Custom** (1โ€“300 items) โ€” User-defined entity/concept limits for specialized workflows. > ๐Ÿ’ก **Recommendation**: Use Minimal or Coarse for large folders to save time and API costs. Use Fine selectively on key documents that warrant deep analysis. - **๐Ÿ”„ Auto-Maintenance**: Optional file watcher, periodic Lint, and startup health check. All default OFF โ€” enable only if you want automatic background processing. > **๐Ÿ›ก๏ธ Safety**: Parallel generation uses `Promise.allSettled` โ€” if one page fails, others continue. Failed pages are retried individually with exponential backoff. Smart Batch Skip automatically detects already-ingested files to save time and API costs. --- ## โšก What's New in v1.16.0 This release focuses on **local model compatibility** and **data quality** โ€” responding to the most impactful issues reported by the community. **Key Improvements:** - **LM Studio support (new!).** A dedicated LM Studio provider option joins Ollama in the dropdown. API key is optional (LM Studio supports it but doesn't require it). Base URL defaults to `http://localhost:1234/v1`. - **Context Window setting.** Local model users can now cap LLM output tokens to avoid HTTP 400 errors when requests exceed the model's context window. A dropdown with options from 4K to 1M โ€” shown only for local/custom providers. Also caps truncation retry, preventing retry-timeout loops. Turn it on in Settings โ†’ LLM Configuration โ†’ Context Window. - **YAML sources field normalization (Issue #81).** 6 pollution patterns (external paths, .md suffixes, alias pipes, duplicates, inline arrays, empty [[]] links) are now automatically normalized to canonical `[[sources/X]]` format. Lint runs the fix before any LLM-dependent phases โ€” 572 files / 1616 entries cleaned on the reporter's ~3800-page vault alone. - **Startup quick fixes.** The former "Startup Health Check" now actively repairs low-level format issues (sources normalization, wiki structure verification) on plugin load. A detailed 10-second Notice shows what was fixed with a disable hint. Default ON โ€” turn off in Settings โ†’ Auto Maintenance. - **Alias language fix.** Replaced hardcoded Chineseโ†”English translation rules with English-as-linker-language and a "do NOT invent translations for established technical terms" guard. Transformer won't become "ๅ˜ๆขๅ™จ" anymore. - **LM Studio HTTP 400 fix (Issue #75).** Root cause was a shadow `MAX_TOKENS = 16000` constant in `source-analyzer.ts` that bypassed the centralized `MAX_TOKENS_BATCH`. Now fully centralized and configurable. - **Settings UX refinements.** New "LLM-Wiki Status" section. Section headings simplified: "LLM Configuration" and "Wiki Configuration". LLM Concurrency and Batch Delay moved to LLM Configuration. Status indicators now in a single row with no redundant prefix. **Upgrading from an older version?** Just install and use โ€” zero breaking changes, zero reconfiguration. The new Context Window setting defaults to 0 (no cap) for cloud users. Local users should set it manually to match their model context. **We strongly recommend all users upgrade to this version.** --- ## โœจ Features ### ๐Ÿ“Š Knowledge Quality - **๐Ÿ” Entity/Concept Extraction** โ€” LLM extracts entities (people, orgs, products, events) and concepts (theories, methods, terms) from your notes with flexible extraction granularity (Minimal~5 items, Coarse~10, Standard~50, Fine~100, Custom 1โ€“300) to balance analysis depth vs. API cost - **๐Ÿท๏ธ Mandatory Page Aliases** โ€” Every generated page includes at least 1 alias (translation, acronym, alternate name), enabling cross-language duplicate detection - **๐Ÿ”„ Duplicate Detection & Merge** โ€” Semantic tiering catches true duplicates (cross-language translations, abbreviations, spelling variants); intelligent LLM merge fuses content and preserves aliases - **๐Ÿงฉ Smart Knowledge Fusion** โ€” Multi-source updates merge new info without redundancy, contradictions preserved with attribution, `reviewed: true` pages protected from overwrite - **๐Ÿ“ Content Truncation Protection** โ€” 8000 max_tokens with automatic stop_reason detection and retry at 2ร— tokens across all providers - **๐Ÿ“ Verbatim Source Mentions** โ€” Original language quotes preserved with optional translation for traceability ### ๐Ÿ› ๏ธ Maintenance - **๐Ÿ” Lint Health Scan** โ€” Detects duplicates, dead links, empty pages, orphans, missing aliases, and contradictions in one comprehensive report - **๐ŸŽฏ Semantic-Tier Duplicate Detection** โ€” Tier 1 (direct name matches: cross-language, abbreviations, high-similarity titles) always verified; Tier 2 (indirect signals: shared links, moderate similarity) fills token budget - **โšก Smart Fix All** โ€” Causality-ordered batch fix: duplicates merged โ†’ dead links resolved โ†’ orphans linked โ†’ empty pages expanded - **๐Ÿ”— Double-Nested Link Auto-Fix** โ€” Lint automatically detects and fixes `[[[[...]]]]` formatting errors across all wiki files, zero LLM cost - **โน๏ธ Cancel Operations** โ€” Cancel ongoing ingestion or lint via status bar click or command palette, with clean partial-result preservation - **๐Ÿท๏ธ Alias Completion** โ€” One-click parallel batch generation of missing aliases, improving future duplicate detection - **๐Ÿ”„ Auto-Maintenance** โ€” Multi-folder file watcher, periodic lint, startup health check (all optional) - **โš ๏ธ Contradiction State Machine** โ€” `detected โ†’ review_ok โ†’ resolved` (AI fix) or `detected โ†’ pending_fix` (manual) ### ๐Ÿ’ฌ Query & Feedback - **๐Ÿค– Conversational Query** โ€” ChatGPT-style dialog with streaming Markdown and `[[wiki-links]]`, multi-turn history - **๐Ÿ“ค Query-to-Wiki Feedback** โ€” Save valuable conversations to Wiki with entity/concept extraction, semantic dedup before save - **๐Ÿ”’ Duplicate Save Prevention** โ€” Hash tracking prevents re-evaluation of unchanged conversations ### ๐ŸŒ LLM & Language - **๐Ÿ”Œ Multi-Provider** โ€” Anthropic, Gemini, OpenAI, DeepSeek, Kimi, GLM, OpenRouter, Ollama, MiniMax, custom endpoints โ€” with guided first-run setup and real-time model list fetching - **๐Ÿ”„ 5xx/429/Overload Retry** โ€” Automatic exponential backoff retry (max 2) on HTTP 5xx/429/529 overload errors across all clients, with status-aware error diagnostics - **๐Ÿ“‹ Dynamic Model List** โ€” Real-time fetching from provider APIs - **๐ŸŒ Wiki Output Language** โ€” 8 languages independent of UI (EN/ZH/JA/KO/DE/FR/ES/PT), with custom input - **๐ŸŒ Full UI Internationalization** โ€” Plugin UI supports 8 languages (EN/ZH/JA/KO/DE/FR/ES/PT), 269+ UI fields fully translated with natural local expressions - **โšก Rate Limit Guardian** โ€” When parallel generation triggers rate limits, auto-detects and suggests: lower concurrency, increase batch delay, switch provider - **๐Ÿฆ™ Web Clipper Compatible** โ€” One-click add Obsidian Web Clipper's `Clippings/` folder to watch list, auto-ingest web clips into Wiki ### ๐Ÿ—๏ธ Architecture & Performance - **โšก Parallel Page Generation** โ€” Configurable 1โ€“5 concurrent pages, default 3 (parallel), 2โ€“3ร— faster for large sources, error isolation per page - **๐Ÿ“š Iterative Batch Extraction** โ€” Adaptive batch sizing eliminates max_tokens bottleneck for long documents - **โน๏ธ Batch-Level Cancellation** โ€” Cancel long-running operations at batch boundaries, preserving completed work with immediate user feedback - **๐Ÿ›๏ธ Three-Layer Architecture** โ€” `sources/` (read-only) โ†’ `wiki/` (LLM-generated) โ†’ `schema/` (co-evolved config) - **๐Ÿงฉ Modular Codebase** โ€” 13 focused modules in `src/` ### ๐Ÿ”’ Privacy & Security - **No backend, no telemetry.** The plugin runs entirely inside Obsidian โ€” there is no external server, no analytics, and no data collection of any kind. Your notes never leave your vault unless you explicitly configure an LLM provider. - **Your data stays local by default.** The plugin does not store, cache, or transmit your content anywhere beyond the LLM API you choose. Only the text you send for ingestion or query leaves your device โ€” and only to the provider you configured. - **Full local mode with Ollama, LM Studio, or local providers.** For complete data sovereignty, use a locally-running LLM. Your notes are processed entirely on your machine โ€” nothing touches the internet. - **Minimal permissions.** Vault file access is required for wiki management (reading notes, generating pages, detecting dead links). Network access is used exclusively for LLM API calls to your chosen provider. Clipboard access is limited to the "Copy" button in the Query modal โ€” only when you click it. --- ## โŒจ๏ธ Commands | Command | Description | |---------|-------------| | **๐Ÿ“ฅ Ingest single source** | Select a note โ†’ generate Wiki pages with entities, concepts, and summary | | **๐Ÿ“‚ Ingest from folder** | Select a folder โ†’ batch generate Wiki from existing notes | | **๐Ÿ” Query wiki** | Conversational Q&A over your Wiki, streaming responses with `[[wiki-links]]` | | **๐Ÿ› ๏ธ Lint wiki** | Full health scan: duplicates, dead links, empty pages, orphans, missing aliases, contradictions | | **๐Ÿ“‹ Regenerate index** | Manually rebuild `wiki/index.md` | | **๐Ÿ’ก Suggest schema updates** | LLM analyzes Wiki and proposes schema improvements | --- ## ๐Ÿ“– Example **Input:** `sources/machine-learning.md` ```markdown ### Machine Learning Machine learning uses algorithms to learn from data. ### Types - Supervised learning - Unsupervised learning - Reinforcement learning ``` **Output โ€” Concept page:** `wiki/concepts/supervised-learning.md` ```markdown --- type: concept created: 2026-05-15 updated: 2026-05-15 sources: ["[[sources/machine-learning]]"] tags: [method] aliases: ["็›‘็ฃๅญฆไน ", "Supervised Learning"] --- ### Supervised Learning ### Basic Information - Type: method - Source: [[sources/machine-learning]] ### Description Supervised learning is a machine learning paradigm where models learn from labeled training data to make predictions on unseen data... ### Related Concepts - [[concepts/Machine-Learning|Machine Learning]] - [[concepts/Unsupervised-Learning|Unsupervised Learning]] ### Related Entities - [[entities/Arthur-Samuel|Arthur Samuel]] ### Mentions in Source - "Supervised learning uses labeled data to train predictive models..." ``` --- ## ๐Ÿค– Model Selection Guide This plugin follows Karpathy's philosophy: **feed the LLM full Wiki context, not chunked RAG retrieval**. Long-context models are strongly recommended โ€” the larger your Wiki grows, the more context the LLM needs. > ๐Ÿ’ก **Why not RAG?** Karpathy's [original critique](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) argues that RAG fragments knowledge and breaks the LLM's ability to reason across the full knowledge graph. **๐Ÿ’ฐ Value-First Strategy:** You don't need flagship models. The following **cost-effective alternatives** deliver excellent results at lower prices: | Tier | Model | Context | Why | |------|-------|---------|-----| | **๐ŸŒŸ Value Pick** | **DeepSeek V4-Flash** | 1M tokens | Lowest cost ($0.14/M), 284B MoE, ideal for batch ingestion | | **๐ŸŒŸ Value Pick** | **Gemini-3.5-Flash** | 1M tokens | 4ร— faster output than GPT-5.5, great for agent tasks | | **๐ŸŒŸ Value Pick** | **Qwen3.6-Plus** | 1M tokens | Strong coding & agentic capabilities, competitive pricing | | **๐ŸŒŸ Value Pick** | **Grok-4** | 2M tokens | 2M context window, excellent for very large wikis | | **Balanced** | **Claude Sonnet 4.6** | 1M tokens | Great quality/cost balance, $3/$15 per million tokens | | **Lightweight** | **Claude Haiku 4.5** | 200K tokens | Fast and affordable for smaller wikis | | **Budget** | **MiMo-V2.5-Flash** | 1M tokens | Xiaomi's cost-effective option, 309B MoE architecture | | **Flagship** | Claude Opus 4.7 | 1M tokens | Ultimate quality, higher cost โ€” use selectively | | **Flagship** | GPT-5.5 | 1M tokens | Top reasoning, higher cost โ€” use selectively | For local models (Ollama): context windows are typically smaller (8Kโ€“128K). Consider using a cloud provider for ingestion + local model for query. **๐Ÿ”Œ Anthropic Compatible (Coding Plan):** If your provider offers an Anthropic-compatible API endpoint, select "Anthropic Compatible" and enter your provider's Base URL and API Key. > ๐Ÿ’ก **Subscription plans:** Coding Plan, OpenAI Pro, or Anthropic Pro plans are excellent options for cost control with frequent use. This plugin supports these services. --- ## ๐Ÿ—๏ธ Architecture Karpathy's three-layer separation design: ``` sources/ # ๐Ÿ“„ Your source documents (read-only) โ†“ ingest wiki/ # ๐Ÿง  LLM-generated Wiki pages โ†“ query / maintain schema/ # ๐Ÿ“‹ Wiki structure configuration (naming, templates, categories) ``` **Codebase** (`src/`): ``` wiki/ # Wiki engine modules wiki-engine.ts # ๐ŸŽฏ Orchestrator query-engine.ts # ๐Ÿ’ฌ Conversational query source-analyzer.ts # ๐Ÿ“Š Iterative batch extraction page-factory.ts # ๐Ÿ—๏ธ Entity/concept CRUD + merge lint-controller.ts # ๐Ÿ” Lint orchestration lint-fixes.ts # ๐Ÿ› ๏ธ Fix logic for dead links, empty pages, orphans lint/ # Lint sub-modules duplicate-detection.ts # ๐Ÿ”„ Programmatic candidate generation fix-runners.ts # โšก Batch fix execution helpers contradictions.ts # โš ๏ธ Contradiction detection system-prompts.ts # ๐Ÿ—ฃ๏ธ Language directive + section labels schema/ # Schema co-evolution schema-manager.ts # ๐Ÿ“‹ Schema CRUD + suggestions auto-maintain.ts # ๐Ÿ”„ File watcher + periodic lint ui/ # User interface settings.ts # โš™๏ธ Settings panel modals.ts # ๐Ÿ“ฆ Lint/Ingest/Query modals + shared modules: llm-client.ts, prompts.ts, texts.ts, utils.ts, types.ts ``` **Generated pages:** - `wiki/sources/filename.md` โ€” ๐Ÿ“„ Source summary - `wiki/entities/entity-name.md` โ€” ๐Ÿ‘ค Entity pages (people, orgs, projects, etc.) - `wiki/concepts/concept-name.md` โ€” ๐Ÿ’ก Concept pages (theories, methods, terms, etc.) - `wiki/index.md` โ€” ๐Ÿ“‘ Auto-generated index - `wiki/log.md` โ€” ๐Ÿ“ Operation log --- ## โ“ FAQ > **Keep your plugin updated.** This project ships frequently โ€” new features and fixes land every few days. Run **Settings โ†’ Community Plugins โ†’ Check for updates** regularly. > > For more, see the [FAQ Discussion on GitHub](https://github.com/green-dalii/obsidian-llm-wiki/discussions/28). ### ๐Ÿ’ก General **What does the plugin actually do?** You drop notes in, it extracts people, concepts, and theories, then generates an interlinked wiki with `[[bidirectional links]]`. Ask questions and get answers grounded in *your* notes โ€” not internet hallucinations. **Minimum requirements?** Obsidian v1.6.6+, desktop (Windows/macOS/Linux), an LLM provider API key. Ollama works locally with no API key. See [Configure an LLM Provider](#-configure-an-llm-provider) above. **Which model should I use?** See [Model Selection Guide](#-model-selection-guide) above. Long-context models work best โ€” the larger your wiki, the more context the LLM needs. ### ๐Ÿท๏ธ Aliases & Duplicates **Why does Lint show "missing aliases" on almost all my pages?** Pages generated before v1.7.11 didn't include aliases. This is harmless โ€” aliases are an enhancement, not a bug. Click **Complete Aliases** in the Lint report to batch-generate translations, acronyms, and alternate names. Once aliases exist, duplicate detection and alias-aware search become much more effective. **Why do I see duplicate pages like "CoT" and "ๆ€็ปด้“พ"?** Pre-v1.7.10 versions lacked alias-aware duplicate detection. Run **Lint Wiki** โ†’ **Merge Duplicates** to fuse them. The merged page preserves aliases from both, preventing future duplicates. **How does duplicate detection work? (v1.7.10+)** Two-tier semantic detection: Tier 1 (always LLM-verified) catches cross-language matches, abbreviations, high-similarity titles. Tier 2 fills remaining token budget with moderate-similarity candidates. Aliases are critical for Tier 1 โ€” run **Complete Aliases** if your pages are pre-v1.7.11. **What are "polluted pages"? (v1.9.0)** Pages with folder prefixes accidentally baked into filenames โ€” e.g. `concepts/conceptsๅธƒๅฑ€ไผ˜ๅŒ–.md`. Run **Lint Wiki** โ†’ **๐Ÿงน Fix Polluted Pages** to rename and update all incoming links. ### โšก Performance & Cost **How do I speed up ingestion?** In **Settings โ†’ Ingestion Acceleration**: increase **Page Generation Concurrency** to 3โ€“5 (parallel page creation), lower **Batch Delay** to 100โ€“300ms (watch for rate limits). Choose "Minimal", "Coarse", or "Standard" **Extraction Granularity** to reduce page count and save API costs. **Why am I getting HTTP 429 errors?** The plugin auto-detects rate-limiting and suggests: lower concurrency to 1โ€“2, increase Batch Delay to 500โ€“800ms, or switch to a higher-limit provider. **How do I control API costs?** - Auto-Maintenance is OFF by default (enable only if you need background processing) - Smart Batch Skip automatically skips already-ingested files - "Standard" or "Coarse" granularity = fewer LLM calls - Batch Delay > 500ms spaces calls without increasing token usage - Lint report shows counts before you run fixes โ€” decide what's worth it ### ๐Ÿงน Maintenance **What does Smart Fix All do?** Runs fixes in causality order (v1.9.0+): 1. ๐Ÿงน Fix polluted pages โ†’ 2. ๐Ÿท๏ธ Complete aliases โ†’ 3. ๐Ÿ”„ Merge duplicates โ†’ 4. ๐Ÿ”— Fix dead links โ†’ 5. ๐Ÿ”— Link orphans โ†’ 6. ๐Ÿ“ Expand empty pages **Lint freezes on a large Wiki?** Upgrade to v1.7.17+ โ€” Lint now yields to Obsidian's UI thread every 50 pages, preventing multi-second freezes even on 1200+ page wikis. ### ๐Ÿ” Troubleshooting **Why can't I use ingest/lint/query after installing?** The plugin requires a successful connection test before core features unlock. Go to **Settings โ†’ Karpathy LLM Wiki** โ†’ pick a provider โ†’ enter your API key โ†’ click **Fetch Models** โ†’ select a model โ†’ click **Test Connection**. Once you see the green "LLM Ready" indicator, all features are available. This prevents silent failures from misconfigured providers. **How do I cancel a running ingestion or lint?** Click the status bar text during an operation (it shows "Ingesting... click to cancel"), or use `Ctrl+P` โ†’ "Cancel current ingestion". The operation stops cleanly at the next batch boundary, preserving all completed work. **How do I quickly ingest the file I'm currently editing?** Click the `sticker` icon in the left ribbon bar, or use `Ctrl+P` โ†’ "Ingest current file". This skips the file picker and directly ingests the active editor tab. **I see `[[[[entities/Foo|Foo]]]]` double brackets in my log.md โ€” how do I fix this?** Run **Lint Wiki** โ€” the scanner now automatically detects and fixes all double-nested wiki-links across your entire wiki directory (including log.md) with zero LLM cost. No manual cleanup needed. **Why am I getting "Overloaded" errors?** The plugin now recognizes Anthropic's 529 overload error as retryable. Overload errors are automatically retried with exponential backoff across all providers. **Why was a duplicate stub created when the page already exists in entities/ or concepts/?** The plugin now uses slug-based matching โ€” different formatting of the same name resolves to the existing page instead of creating a duplicate stub. **Query can't find pages I know exist?** Three common causes: (1) Index is stale โ†’ **Regenerate index**. (2) Missing aliases โ†’ **Complete Aliases**. (3) Try different phrasing โ€” LLM does semantic matching, not keyword search. **Can I manually edit Wiki pages?** Yes. Set `reviewed: true` in frontmatter to protect from overwrite. Manual aliases, tags, and sources are preserved during merges. **Safe upgrade?** The plugin never modifies your source files. Backup `wiki/` โ†’ update plugin โ†’ **Regenerate index** โ†’ **Lint Wiki** โ†’ fix selectively. **How do I get help?** - [GitHub Issues](https://github.com/green-dalii/obsidian-llm-wiki/issues) โ€” bug reports - [GitHub Discussions](https://github.com/green-dalii/obsidian-llm-wiki/discussions) โ€” questions & feedback **How do I collect debug logs for troubleshooting?** 1. Open Developer Tools (`Ctrl+Shift+I` / `Cmd+Option+I`) 2. Go to the **Console** tab 3. Run your operation (ingest, query, or lint) 4. Look for messages with module name prefixes like `[Step]`, `[LLM]`, module names 5. For local testing, use `pnpm build:dev` instead of `pnpm build` to preserve full debug output 6. Copy the relevant log lines and include them in your GitHub issue โ€” this makes bug diagnosis much faster --- ## ๐Ÿ”’ Transparency & Compliance This plugin is listed on the Obsidian Community Plugin Market and undergoes automated review for security and permissions. **The plugin has no backend, no server infrastructure, and no data collection of any kind.** It is purely local software running inside Obsidian. The plugin cannot and does not collect, store, or transmit your data to any server โ€” because no such server exists. **Network access** is used only to communicate with the LLM provider you configure โ€” no other network calls are made. This is entirely under your control: you choose the provider, you enter the API key, you decide where your data goes. **File system access** (vault enumeration) is required to build and maintain the wiki: reading your source notes, generating pages, scanning for dead links, and detecting duplicate pages. The plugin never modifies your source files โ€” only files under the wiki folder. **Clipboard access** is used exclusively by the "Copy" button in the Query modal, and only when you click it. If you prefer complete data locality, use a local LLM provider such as Ollama or LM Studio. With a local provider, your data never leaves your machine. ## ๐Ÿ“œ License MIT License โ€” see [LICENSE](LICENSE). ## ๐Ÿ™ Acknowledgments - **๐Ÿ’ก Concept:** [Andrej Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) โ€” the original vision that inspired this plugin - **๐Ÿ› ๏ธ Platform:** [Obsidian Plugin API](https://docs.obsidian.md/Plugins/Getting+started/Build+a+plugin) - **๐Ÿ”Œ LLM SDKs:** Anthropic SDK, OpenAI SDK