[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-947":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":47,"readmeContent":48,"aiSummary":49,"trendingCount":16,"starSnapshotCount":16,"syncStatus":50,"lastSyncTime":51,"discoverSource":52},947,"obsidian-llm-wiki-local","kytmanov\u002Fobsidian-llm-wiki-local","kytmanov","Karpathy’s LLM Wiki, 100% local with Ollama. Drop Markdown notes → AI extracts concepts → your Obsidian wiki auto-links and grows. Zero sharing. Your notes stay yours.","",null,"Python",708,115,7,1,0,14,34,196,42,10.19,"MIT License",false,"master",true,[27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46],"git-based-wiki","karpathy","knowledge-base","llm-knowledge-base","llm-pipeline","llm-tools","llm-wiki","local-first-ai","local-llm","markdown-wiki","obsidian","obsidian-llm","obsidian-wiki","ollama","personal-knowledge-management","pkm","rag-alternative","rag-local","second-brain","self-hosted-wiki","2026-06-12 02:00:21","# obsidian-llm-wiki\n\n\u003Cp align=\"center\">\n     \u003Ca href=\"https:\u002F\u002Fpepy.tech\u002Fprojects\u002Fobsidian-llm-wiki\">\u003Cimg src=\"https:\u002F\u002Fstatic.pepy.tech\u002Fpersonalized-badge\u002Fobsidian-llm-wiki?period=total&units=NONE&left_color=BLACK&right_color=GREEN&left_text=downloads\" alt=\"PyPI Downloads\">\u003C\u002Fa>\n     \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fkytmanov\u002Fobsidian-llm-wiki-local\u002Fstargazers\">\u003Cimg alt=\"GitHub stars\" src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fkytmanov\u002Fobsidian-llm-wiki-local?style=flat\">\u003C\u002Fa> \n     \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fkytmanov\u002Fobsidian-llm-wiki-local\u002Fnetwork\u002Fmembers\">\u003Cimg alt=\"GitHub forks\" src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fforks\u002Fkytmanov\u002Fobsidian-llm-wiki-local?style=flat\">\u003C\u002Fa> \n     \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fkytmanov\u002Fobsidian-llm-wiki-local\u002Fcommits\u002Fmaster\">\u003Cimg alt=\"GitHub last commit\" src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flast-commit\u002Fkytmanov\u002Fobsidian-llm-wiki-local?style=flat\">\u003C\u002Fa> \n     \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fkytmanov\u002Fobsidian-llm-wiki-local\u002Factions\u002Fworkflows\u002Fci.yml\">\u003Cimg alt=\"CI status\" src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Factions\u002Fworkflow\u002Fstatus\u002Fkytmanov\u002Fobsidian-llm-wiki-local\u002Fci.yml?style=flat&label=CI\">\u003C\u002Fa> \n     \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Fobsidian-llm-wiki\u002F\">\u003Cimg alt=\"PyPI version\" src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fobsidian-llm-wiki?style=flat\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n**Turn your raw notes into a self-improving, interlinked wiki — powered by a local LLM.**\n\nDrop a markdown file into a folder. The pipeline reads it, extracts concepts, and creates or updates wiki articles. If a draft is wrong, reject it and explain why; the next compile addresses your feedback. Over time, every note you add and every draft you review makes the wiki smarter.\n\n**Local-first, provider-flexible.** Runs 100% locally with [Ollama](https:\u002F\u002Follama.com) by default. Also works with any OpenAI-compatible endpoint — Groq, Together AI, LM Studio, vLLM, Azure OpenAI, and [more](#providers).\n\u003Cp align=\"center\">\n\u003Cimg width=\"400\" height=\"390\" alt=\"image\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F0b3998bd-af4d-4f3f-a2da-8334a0e81711\"\u002F>\n\u003C\u002Fp>\n\n---\n\n## The idea (Karpathy's LLM Wiki)\n\nThis project is a practical implementation of the pattern described by Andrej Karpathy in [**\"The LLM Wiki\"**](https:\u002F\u002Fkarpathy.ai\u002Fllmwiki) — a vision for a personal knowledge base where:\n\n> *\"The LLM doesn't just store what you tell it — it synthesizes, cross-references, and keeps everything current. You add raw material; it does the bookkeeping.\"*\n\nThe key insight: treat your notes as **source material**, not as the final artifact. The LLM compiles them into a structured wiki that grows smarter as you add more. Unlike a chatbot that forgets, the wiki **persists and compounds**.\n\n```\nYou write raw notes  →  LLM extracts concepts  →  Wiki articles created\u002Fupdated\n     raw\u002F                    (automatic)                    wiki\u002F\n  quantum.md          \"Qubit\", \"Superposition\"       Qubit.md   ←──┐\n  ml-basics.md        \"Neural Network\", \"SGD\"    Superposition.md  │\n  physics.md          \"Qubit\" (again!)           Neural Network.md │\n                                                      ↑  linked via [[wikilinks]]\n```\n\nThe wiki lives in Obsidian, so you get the graph view, backlinks, and Dataview queries for free.\n\n---\n\n## Features\n\n**Incremental compiles.** Each concept gets its own article. When you change a source note, only the articles tied to that note recompile, not the whole vault.\n\n**File watcher.** Run `olw watch` once and it processes anything you drop into `raw\u002F` automatically. Ingest and compile run in the background, so the wiki keeps improving while you keep writing notes.\n\n**Rejection feedback.** Reject a draft and attach a reason. The next compile of that concept includes your feedback in the prompt, so the model can address it. Five rejections without an approval auto-blocks the concept until you re-enable it.\n\n**Hand-edits are preserved.** Edit an article in Obsidian and the compiler will detect the change on the next run and skip it. Your edits aren't overwritten by regeneration.\n\n**Query and synthesize.** `olw query \"what is X?\"` answers from your published wiki without embeddings or a vector DB. With `--synthesize` it saves the answer as a permanent wiki page, complete with source hashes and the same hand-edit protection.\n\n**Self-maintenance.** Aliases like `PC` for `Program Counter` are extracted at ingest and used to repair broken wikilinks. `olw lint` reports orphans and stale articles; `olw maintain --fix` rewrites alias links and creates stubs for missing targets.\n\n**Provider-flexible.** Ollama by default, fully offline. You can also point it at Groq, Together AI, LM Studio, vLLM, Azure OpenAI, or any OpenAI-compatible endpoint via `olw setup`. `olw compare` previews a switch in isolated vaults so you can decide before editing `wiki.toml`.\n\n**Multi-language.** Each note's language is auto-detected at ingest and the article is written in that language. Extraction rules don't depend on hard-coded word lists, so any language works.\n\n**Git-aware.** Every automatic action commits with an `[olw]` prefix, and `olw undo` reverts the last one. Raw notes are never modified; `olw` only writes to `wiki\u002F` and `.olw\u002F`.\n\n---\n\n## Quick start\n\n### 1. Install\n\n**From PyPI** (recommended):\n\n```bash\npip install obsidian-llm-wiki\n```\n\nOr with `uv`:\n\n```bash\nuv tool install obsidian-llm-wiki\n```\n\n**From source** (latest development version):\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fkytmanov\u002Fobsidian-llm-wiki-local\ncd obsidian-llm-wiki-local\npython install.py\n```\n\n`install.py` detects `uv` or falls back to `pip`, verifies the install, and tells you to run the next step.\n\n### 2. Install and start Ollama\n\n```bash\n# Install Ollama: https:\u002F\u002Follama.com\u002Fdownload\nollama pull gemma4:e4b      # fast model — analysis and routing\nollama pull qwen2.5:14b     # heavy model — article writing (optional, 7B+ recommended)\n```\n\n> **Minimal setup:** pull only `gemma4:e4b` and set both `fast` and `heavy` to it in the wizard.\n\n### 3. Run the setup wizard\n\n```bash\nolw setup\n```\n\nAn interactive wizard selects a provider, configures the URL and optional API key, picks fast and heavy models, sets an optional default vault, and offers experimental features. Takes ~30 seconds.\n\n```\n╭──────────────────────────────────────────────────╮\n│      obsidian-llm-wiki  ·  setup                 │\n╰──────────────────────────────────────────────────╯\n\n  Step 1  Provider\n\n    Local (no API key needed):\n       1. Ollama          http:\u002F\u002Flocalhost:11434  [default]\n       2. LM Studio       http:\u002F\u002Flocalhost:1234\u002Fv1\n       3. vLLM            http:\u002F\u002Flocalhost:8000\u002Fv1\n       ...\n    Cloud (API key required):\n      10. Groq            https:\u002F\u002Fapi.groq.com\u002Fopenai\u002Fv1\n      11. Together AI     https:\u002F\u002Fapi.together.xyz\u002Fv1\n      ...\n\n    Select provider (number or name) [1]: _\n\n  Step 2  URL\n    Base URL [http:\u002F\u002Flocalhost:11434]: _\n    ✓ connected\n\n  Step 3  Fast model  (analysis & routing · 3–8B recommended)\n    #  Model           Size\n    1  gemma4:e4b      9.6 GB\n    2  phi4-mini       2.5 GB\n    Select (number or name) [1]: _\n  ...\n```\n\nSettings are saved to `~\u002F.config\u002Folw\u002Fconfig.toml` (Mac\u002FLinux) or `%APPDATA%\\olw\\config.toml` (Windows). API keys are stored only in this user-private file, never in `wiki.toml`.\n\nExperimental setup choices are saved only as defaults for new vaults. Runtime behavior is controlled by each vault's `wiki.toml`.\n\n### 4. Set up your vault\n\n```bash\nolw init ~\u002Fmy-wiki\n```\n\nThis creates the folder structure and a `wiki.toml` pre-filled with your setup wizard choices.\n\nTo enable experimental inline source citations for an existing vault:\n\n```bash\nolw config inline-source-citations on --vault ~\u002Fmy-wiki\nolw config inline-source-citations status --vault ~\u002Fmy-wiki\n```\n\nTurn them off at any time with:\n\n```bash\nolw config inline-source-citations off --vault ~\u002Fmy-wiki\n```\n\nManual fallback:\n\n```toml\n[pipeline]\ninline_source_citations = true\n```\n\n### 5. Add some notes\n\nDrop any `.md` files into `~\u002Fmy-wiki\u002Fraw\u002F`. Web clips, book notes, meeting notes, anything.\n\n```\n~\u002Fmy-wiki\u002Fraw\u002F\n  quantum-computing.md\n  ml-fundamentals.md\n  physics-lecture.md\n```\n\n### 6. Run the full pipeline\n\n```bash\n# One command: ingest + compile + lint + optional auto-approve\nolw run\n\n# Or step by step:\nolw ingest --all\nolw compile\nolw review        # interactive draft review\n```\n\nIf you set a default vault in `olw setup`, the `--vault` flag is optional. Otherwise use `--vault ~\u002Fmy-wiki` or `export OLW_VAULT=~\u002Fmy-wiki`.\n\nOpen `~\u002Fmy-wiki` as an Obsidian vault. The graph view shows your connected wiki.\nBefore approving drafts, use a draft-review graph filter:\n\n```text\n-path:raw -path:wiki\u002Fsources -path:_resources -file:Welcome\n```\n\nAfter approving drafts, use a published-only graph filter:\n\n```text\n-path:raw -path:wiki\u002Fsources -path:wiki\u002F.drafts -path:_resources -file:Welcome\n```\n\nThe published-only filter hides `wiki\u002F.drafts`, so it will look empty until drafts are approved. Run `olw doctor` to print graph guidance for the current vault.\n\nWant to preview a model or provider switch before changing `wiki.toml`?\n\n```bash\nolw compare --heavy-model qwen2.5:14b\n```\n\n`olw compare` rebuilds isolated preview vaults from the same `raw\u002F` notes and tells you whether to switch, keep your current config, or review the diffs manually.\n\n### 7. Keep it running (optional)\n\n```bash\nolw watch\n# Drop a file in raw\u002F → ingest + compile happen automatically (selective: only linked concepts)\n```\n\n---\n\n## Query synthesis\n\n`olw query` answers from the published wiki without embeddings. Use `--save` to keep a dated Q&A note in `wiki\u002Fqueries\u002F`, or `--synthesize` to publish a reusable synthesis page in `wiki\u002Fsynthesis\u002F`.\n\n```bash\n# Just answer in the terminal\nolw query \"What is backpropagation?\"\n\n# Save a dated Q&A note under wiki\u002Fqueries\u002F\nolw query \"What is backpropagation?\" --save\n\n# Save a reusable synthesis article under wiki\u002Fsynthesis\u002F\nolw query \"What is backpropagation?\" --synthesize\n```\n\nSynthesis behavior:\n\n- synthesis pages are published notes tagged with `synthesis`\n- they store the source question, selected source pages, and source page body hashes in frontmatter\n- `wiki\u002Findex.md` includes a capped `## Synthesis` section sourced from the DB, ordered by newest first and then title\n- compare runs stay side-effect-free: query evaluation never writes to the active vault during `olw compare`\n- query-time synthesis does not create a new `[olw]` git commit\n\nDuplicate handling:\n\n- default behavior is `keep_existing` for the same normalized question\n- interactive terminals only prompt for a strategy when a duplicate already exists\n- `save_with_suffix` keeps the existing page and writes a new suffixed file\n- `update_in_place` rewrites the existing synthesis only when its body still matches the DB-tracked hash\n- if the existing synthesis was manually edited, `update_in_place` refuses to overwrite it\n- synthesis pages cannot cite another synthesis page as a source\n\n---\n\n## Compare a new model or provider\n\n`olw compare` is a vault switch advisor, not a benchmark harness. It compares your\ncurrent vault config against one challenger config using the same active vault and\nthe same `raw\u002F` notes.\n\n```bash\n# Same provider, different heavy model\nolw compare --heavy-model qwen2.5:14b\n\n# Try a different local provider\nolw compare \\\n  --provider lm_studio \\\n  --provider-url http:\u002F\u002Flocalhost:1234\u002Fv1 \\\n  --fast-model google\u002Fgemma-4-e4b \\\n  --heavy-model google\u002Fgemma-4-e4b\n\n# Quick spot-check on a large vault\nolw compare --heavy-model qwen2.5:14b --sample-n 20\n```\n\nWhat it does:\n\n- rebuilds the current config and challenger config in isolated preview vaults\n- writes reports under `.olw\u002Fcompare\u002F\u003Crun_id>\u002F`\n- leaves your active `raw\u002F` and `wiki\u002F` untouched and does not modify active `.olw\u002F` state outside `.olw\u002Fcompare\u002F`\n- returns one verdict: `switch`, `keep_current`, or `manual_review`\n\nUseful options:\n\n- `--queries path\u002Fto\u002Fqueries.toml` adds a few representative questions to the comparison\n- `--out \u002Ftmp\u002Fmy-compare` writes artifacts outside the vault if you want to inspect them elsewhere\n- `--keep-artifacts` retains the ephemeral preview vaults instead of deleting them after the run\n- `--sample-n N` limits the preview to the first `N` raw notes for a fast spot-check\n- `--allow-cloud-upload` is required when the challenger uses a cloud provider\n\nNotes:\n\n- compare previews automated generated output, not the final curated vault after human review\n- the report includes a ready-to-copy `wiki.toml` snippet for the challenger when the verdict is `switch`\n\nMinimal `queries.toml` example:\n\n```toml\n[[query]]\nid = \"backprop\"\nquestion = \"What is backpropagation?\"\nexpected_contains = [\"chain rule\"]\n```\n\nReports are written as Markdown and JSON by default:\n\n- `report.md` — recommendation-first summary with next steps\n- `report.json` — full machine-readable report\n- `summary.json` — compact verdict and reason summary\n\n---\n\n## How it works\n\nThe pipeline has three stages, each using the LLM for a different purpose:\n\n```\nraw\u002Fnote.md\n    │\n    ▼ olw ingest  (or olw run)\n    Fast LLM (3B–8B)\n    • Reads note\n    • Extracts concept names\n    • Preserves explicitly evidenced named references as knowledge item candidates\n    • Writes quality score + summary to state.db\n    • Creates wiki\u002Fsources\u002FNote.md (source summary page)\n    │\n    ▼ olw compile\n    Heavy LLM (7B–14B)\n    • For each concept: gathers all source notes that mention it\n    • Injects rejection feedback from previous reviews into the prompt\n    • Writes a wiki article with [[wikilinks]] to related concepts\n    • Adds quality annotations if confidence is low or sources are sparse\n    • Lands in wiki\u002F.drafts\u002F for review\n    │\n    ▼ olw review  (or olw approve)\n    • Interactive numbered menu — approve \u002F reject \u002F diff \u002F edit\n    • Rejection feedback stored and injected into next compile\n    • On approve: annotations stripped, article published to wiki\u002F\n    • Updates wiki\u002Findex.md (navigation layer)\n    • Git commits the change\n```\n\n**No vector databases, no embeddings.** `wiki\u002Findex.md` acts as the routing layer for `olw query`. This keeps the setup simple and works well up to ~100 source notes.\n\nThe pipeline is intentionally conservative. Strong concepts become draft articles; explicitly evidenced named references become auditable knowledge item candidates. This keeps source-specific names visible without generating low-evidence articles from them.\n\n---\n\n## Multi-language support\n\n`olw` detects the language of each raw note during ingest and stores it. At compile time, the article is written in that language — no configuration needed.\n\nExtraction and cleanup are designed to be language-agnostic. The pipeline avoids hard-coded natural-language word lists for title\u002Fentity promotion. Instead, it uses structural evidence, explicit source evidence, and conservative confidence levels so notes in any language follow the same rules.\n\n**How it works:**\n\n1. **Ingest** — the fast model detects the primary language and stores an ISO 639-1 code (`en`, `fr`, `de`, …) per note in the state DB.\n2. **Compile** — when all source notes for a concept share the same language, the heavy model is instructed to write the article in that language. If sources are mixed, it falls back to matching the source text.\n3. **Config override** — set `language` in `wiki.toml` to force a specific output language for the whole vault, regardless of what the model detected.\n\n```toml\n[pipeline]\nlanguage = \"fr\"   # all articles will be written in French\n```\n\nLeave `language` unset (the default) to let auto-detection drive it per concept.\n\n**Example:** a French note ingested alongside English notes produces a French article for French-only concepts and an English article for concepts sourced from English notes. Setting `language = \"en\"` forces everything to English.\n\nThis language setting controls generated article language only. It does not enable language-specific concept merging or ontology decisions.\n\n---\n\n## Knowledge item candidates\n\nNot every useful reference deserves a wiki article. During ingest, `olw` keeps a separate knowledge item ledger for ambiguous, low-evidence references found explicitly in notes:\n\n- LLM-proposed named references accepted only when the exact text appears in the title, filename, or body\n- structurally prominent quoted titles, such as `\"A Practical Guide To Notes\"`\n- confirmed concepts mirrored into the ledger as confirmed knowledge items\n\nThese items are not compiled into articles by default. They are preserved for later review, classification, or future evidence accumulation.\n\n```bash\nolw items audit\nolw items show \"Example Reference\"\n```\n\nThis is deliberately conservative: a named reference should not become a concept article unless the source content supports it. The item ledger keeps the reference from disappearing while avoiding hallucinated articles.\n\n---\n\n## Rejection feedback loop\n\nWhen you reject a draft:\n\n```bash\nolw review\n# Select draft → [r]eject → \"The overview section is too vague, needs concrete examples\"\n```\n\nThe feedback is stored in the state database. On the next compile of that concept, the prompt includes:\n\n```\nPREVIOUS REJECTIONS — address these issues:\n- The overview section is too vague, needs concrete examples\n```\n\nAfter 5 rejections of the same concept without an approval, the concept is **auto-blocked** and excluded from future compiles until you explicitly re-enable it:\n\n```bash\nolw unblock \"Quantum Computing\"\n```\n\n---\n\n## Draft annotations\n\nDrafts with low confidence or sparse sources are annotated with HTML comments that are invisible in Obsidian's preview but visible in the editor:\n\n```markdown\n\u003C!-- olw-auto: low-confidence (0.32) — verify before publishing -->\n\u003C!-- olw-auto: single-source — cross-reference recommended -->\n\n## Overview\n...\n```\n\nAnnotations are stripped automatically when you approve a draft. `olw review` surfaces them as a warning in the draft list.\n\n---\n\n## Vault structure\n\n```\nmy-wiki\u002F\n├── raw\u002F                        ← YOUR NOTES (never modified by olw)\n│   ├── quantum-computing.md\n│   └── ml-fundamentals.md\n├── wiki\u002F\n│   ├── Quantum Computing.md    ← concept articles (flat, one per concept)\n│   ├── Machine Learning.md\n│   ├── sources\u002F                ← auto-generated source summaries\n│   │   ├── Quantum Computing Fundamentals.md\n│   │   └── ML Fundamentals.md\n│   ├── queries\u002F                ← saved Q&A answers (olw query --save)\n│   ├── synthesis\u002F              ← saved synthesis articles (olw query --synthesize)\n│   ├── .drafts\u002F                ← pending human review\n│   ├── index.md                ← auto-generated navigation + routing layer\n│   └── log.md                  ← append-only operation history\n├── vault-schema.md             ← LLM context: conventions for this vault\n├── wiki.toml                   ← configuration\n└── .olw\u002F\n    ├── compare\u002F                ← compare reports + optional preview vault artifacts\n    ├── state.db                ← SQLite: notes, concepts, articles, items, rejections, stubs\n    └── pipeline.lock           ← advisory lock (auto-released when the holding process exits)\n```\n\n`raw\u002F` is immutable — `olw` never writes to it. All metadata lives in `state.db`.\n\n---\n\n## Configuration\n\n`wiki.toml` (created by `olw init`):\n\n```toml\n[models]\nfast  = \"gemma4:e4b\"      # extraction, analysis, query routing\nheavy = \"qwen2.5:14b\"     # article generation, Q&A answers\n# Single-model: set heavy = fast\n\n# ── Local Ollama (default) ────────────────────────────────────────────────────\n[ollama]\nurl = \"http:\u002F\u002Flocalhost:11434\"   # supports LAN: http:\u002F\u002F192.168.1.x:11434\ntimeout = 600\nfast_ctx = 16384                 # context window for fast model (tokens)\nheavy_ctx = 32768                # context window for heavy model (tokens)\n\n# ── Any other provider (replaces [ollama] when present) ──────────────────────\n# [provider]\n# name = \"groq\"                              # or lm_studio, vllm, together, azure, custom …\n# url  = \"https:\u002F\u002Fapi.groq.com\u002Fopenai\u002Fv1\"\n# timeout = 120\n# fast_ctx = 8192\n# heavy_ctx = 32768\n# azure_api_version = \"2024-02-15-preview\"  # Azure only\n\n[pipeline]\nauto_approve = false             # true = skip draft review\nauto_commit = true               # git commit after each operation\nauto_maintain = false            # true = run maintain checks after each compile\nmax_concepts_per_source = 8      # limit concepts extracted per note\nwatch_debounce = 3.0             # seconds after last file event before processing\ningest_parallel = false          # true = parallel chunk analysis (needs OLLAMA_NUM_PARALLEL>=4)\n# language = \"en\"               # ISO 639-1 output language; autodetects from notes if unset\n# inline_source_citations = false\n# source_citation_style = \"legend-only\"  # legend-only | inline-wikilink\n# draft_media = \"reference\"              # reference | embed | omit\n```\n\n> **API keys** are never stored in `wiki.toml`. They are read at runtime from the provider-specific env var (e.g. `GROQ_API_KEY`), the generic `OLW_API_KEY` env var, or the `api_key` field in `~\u002F.config\u002Folw\u002Fconfig.toml` (written by `olw setup`).\n\n### Tuning context windows\n\n`heavy_ctx` controls how much source material the heavy model reads when writing articles (`source budget = heavy_ctx \u002F 2` chars) and how long the generated article can be. Defaults target **16 GB VRAM**. **If you use a model with a large context window (e.g. `gemma4:e4b` supports 128K), increase it.**\n\n| VRAM | Recommended `heavy_ctx` | Source budget | Notes |\n|---|---|---|---|\n| 8 GB | `8192` | ~4K chars | Minimum; short articles |\n| 16 GB | `32768` | ~16K chars | Default |\n| 32 GB+ | `65536` | ~32K chars | Rich multi-source articles |\n\n`fast_ctx` controls ingest analysis. Notes longer than `fast_ctx \u002F 2` chars are automatically split into chunks and analyzed in sequence — all content is covered, no truncation.\n\n| VRAM | Recommended `fast_ctx` | Notes per chunk |\n|---|---|---|\n| 8 GB | `8192` | ~4K chars |\n| 16 GB | `16384` | ~8K chars — Default |\n| 32 GB+ | `32768` | ~16K chars |\n\n### Speeding up long-note ingest\n\nFor vaults with many long notes (>8K chars), enable parallel chunk analysis:\n\n```toml\n[pipeline]\ningest_parallel = true   # requires OLLAMA_NUM_PARALLEL>=4\n```\n\nAlso set in your shell before starting Ollama:\n\n```bash\nOLLAMA_NUM_PARALLEL=4 ollama serve\n```\n\nThis lets Ollama process multiple chunks simultaneously. On 16 GB VRAM with `gemma4:e4b` (9.6 GB), 4 parallel slots fit comfortably (~12.8 GB total). Wall time for a 25K-char note drops from ~39s to ~14s.\n\nAfter editing `wiki.toml`, no reinstall is needed. Run `olw compile --force` to regenerate articles with the new context budget.\n\n---\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `olw setup` | Interactive setup wizard: pick provider, models, vault |\n| `olw init PATH` | Create vault structure and git repo |\n| `olw init PATH --existing` | Adopt an existing Obsidian vault |\n| `olw doctor` | Check provider connectivity, models, vault structure |\n| `olw run` | Full pipeline: ingest → compile → lint → [approve] |\n| `olw run --auto-approve` | Full pipeline, publish without review |\n| `olw run --dry-run` | Report what would happen, make no changes |\n| `olw compare --heavy-model MODEL` | Compare current vault config against one challenger model |\n| `olw compare --provider NAME --provider-url URL ...` | Compare a provider switch safely in isolated preview vaults |\n| `olw ingest --all` | Analyze all raw notes |\n| `olw ingest FILE` | Analyze one note |\n| `olw compile` | Generate wiki articles → `.drafts\u002F` |\n| `olw compile --retry-failed` | Retry previously failed notes |\n| `olw review` | Interactive draft review (approve \u002F reject \u002F diff) |\n| `olw approve --all` | Publish all drafts without review |\n| `olw approve FILE` | Publish one draft |\n| `olw reject FILE` | Discard a draft (prompts for feedback) |\n| `olw reject FILE --feedback \"...\"` | Discard with feedback for next compile |\n| `olw reject --all` | Discard all drafts (prompts once for shared feedback) |\n| `olw reject --all --feedback \"...\"` | Discard all drafts with feedback |\n| `olw unblock \"Concept\"` | Re-enable a concept blocked after 5 rejections |\n| `olw maintain` | Health check + stubs + orphan and merge suggestions |\n| `olw maintain --fix` | Repair broken alias links, create stubs, normalize alias wikilinks |\n| `olw maintain --dry-run` | Report issues without making changes |\n| `olw items audit` | Show preserved non-concept knowledge item candidates |\n| `olw items show NAME` | Show one knowledge item and its source mentions |\n| `olw status` | Show pipeline state and pending drafts |\n| `olw status --failed` | List failed notes with error messages |\n| `olw query \"question\"` | Answer from your wiki |\n| `olw query \"...\" --save` | Answer and save to `wiki\u002Fqueries\u002F` |\n| `olw query \"...\" --synthesize` | Answer and save a synthesis article to `wiki\u002Fsynthesis\u002F` |\n| `olw lint` | Health check: orphans, broken links, stale articles |\n| `olw lint --fix` | Auto-fix missing frontmatter fields |\n| `olw watch` | File watcher — auto-pipeline on new notes |\n| `olw watch --auto-approve` | Watch + auto-publish (no manual review) |\n| `olw undo` | Revert last `[olw]` git commit |\n| `olw clean` | Clear state DB + wiki\u002F, keep raw\u002F notes |\n\nAll commands accept `--vault PATH` or the env var `OLW_VAULT`.\n\n---\n\n## Providers\n\nRun `olw setup` to pick a provider interactively. All providers are also configurable directly in `wiki.toml`.\n\n| Provider | Type | Embeddings | Notes |\n|----------|------|-----------|-------|\n| **Ollama** | local | ✓ | default; full offline |\n| LM Studio | local | ✓ | |\n| vLLM | local | ✓ | |\n| llama.cpp | local | — | |\n| LocalAI | local | ✓ | |\n| TGI | local | — | |\n| SGLang | local | ✓ | |\n| Llamafile | local | — | |\n| Lemonade | local | — | |\n| **Groq** | cloud | — | fast inference, free tier |\n| Together AI | cloud | ✓ | |\n| Fireworks AI | cloud | ✓ | |\n| DeepInfra | cloud | ✓ | |\n| OpenRouter | cloud | — | routes to many models |\n| Mistral AI | cloud | ✓ | |\n| DeepSeek | cloud | — | |\n| SiliconFlow | cloud | ✓ | |\n| Perplexity | cloud | — | |\n| xAI (Grok) | cloud | — | |\n| Azure OpenAI | cloud | ✓ | see `azure_api_version` |\n| Custom | any | — | enter URL manually |\n\nRAG (embeddings) requires a provider that supports `\u002Fv1\u002Fembeddings`. The default index-based query works with all providers.\n\n---\n\n## Model recommendations\n\n| Role | Ollama | Cloud |\n|------|--------|-------|\n| Fast (analysis + routing) | `gemma4:e4b`, `llama3.2:3b` | `llama-3.1-8b-instant` (Groq), `mistral-7b` |\n| Heavy (article writing) | `qwen2.5:14b`, `llama3.1:8b` | `llama-3.3-70b` (Groq), `mistral-large` |\n| Single model (everything) | `llama3.1:8b`, `mistral:7b` | any 7B+ |\n\nAny model with JSON format \u002F `response_format: json_object` support works. The tool degrades gracefully with smaller models.\n\n---\n\n## Obsidian tips\n\n- **Graph view** — concept pages link to source pages and each other via `[[wikilinks]]`; before approval use `-path:raw -path:wiki\u002Fsources -path:_resources -file:Welcome`, after approval add `-path:wiki\u002F.drafts`\n- **Source citations** — when inline citations are enabled, the default style stays graph-quiet as `[S1](#Sources)` links while source pages link once in `## Sources`; set `source_citation_style = \"inline-wikilink\"` if you want every citation to create a source edge\n- **Media** — source pages preserve `![[media]]` embeds; generated drafts default to plain media references to avoid attachment nodes dominating the graph (`draft_media = \"reference\"`)\n- **Draft review** — drafts live in `wiki\u002F.drafts\u002F` and may not appear in Obsidian's default graph filters; use `olw doctor` for the recommended draft-review and published-only filters\n- **Dataview** — query by `status: published`, `confidence: > 0.7`, `tags: [physics]`, etc.\n- **Backlinks** — every concept page shows which source pages mention it\n- **Web Clipper** — save web articles directly to `raw\u002F` (see [docs\u002Fweb-clipper-setup.md](docs\u002Fweb-clipper-setup.md))\n\n## Quality principles for contributors and AI agents\n\n- Prefer deterministic, auditable cleanup over broad LLM-driven merging.\n- Do not use LLM aliases as automatic merge authority; aliases are weak evidence.\n- Keep concept extraction language-agnostic. Avoid hard-coded English or other language-specific word lists unless the feature is explicitly scoped to that language.\n- Preserve weak entity references as knowledge item candidates rather than generating unsupported concept articles.\n- Source pages and `[S1](#Sources)` citations should remain graph-quiet by default; source-page edges belong in `## Sources`.\n- Generated drafts should avoid media embeds by default. Source pages can preserve embeds; draft articles should usually contain plain media references.\n- Raw notes are immutable. All generated state belongs under `wiki\u002F` and `.olw\u002F`.\n\n---\n\n## Running the tests\n\nAll tests are offline — no Ollama required.\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fkytmanov\u002Fobsidian-llm-wiki-local\ncd obsidian-llm-wiki-local\nuv sync --group dev\nuv run pytest\n```\n\nFor the full end-to-end smoke test (requires a running provider):\n\n```bash\n# Ollama (default)\nbash scripts\u002Fsmoke_test.sh\n\n# LM Studio or any other OpenAI-compatible endpoint\nPROVIDER=lm_studio bash scripts\u002Fsmoke_test.sh\n\n# LM Studio with the validated local baseline model\nPROVIDER=lm_studio FAST_MODEL=gemma4:e4b HEAVY_MODEL=gemma4:e4b \\\nbash scripts\u002Fsmoke_test.sh\n\n# Compare smoke test\nPROVIDER=lm_studio FAST_MODEL=gemma4:e4b HEAVY_MODEL=gemma4:e4b \\\nbash scripts\u002Fcompare_smoke.sh\n```\n\nIf LM Studio rejects the short alias, use the exact loaded model id it reports, for example `google\u002Fgemma-4-e4b`.\n\n---\n\n## FAQ\n\n**Q: I ran `olw compile` but nothing appears in Obsidian.**\n\nDrafts land in `wiki\u002F.drafts\u002F` — Obsidian hides dotfolders by default so they won't show in the graph yet. Run:\n\n```bash\nolw review        # interactive review\n# or\nolw approve --all\n```\n\nArticles move to `wiki\u002F` and become fully visible.\n\n---\n\n**Q: Compile says \"2 article(s) failed: Methodology, Sprints\" — what do I do?**\n\nFailed concepts are retried automatically on the next run. Or force a retry:\n\n```bash\nolw compile --retry-failed\n```\n\nIf the same concepts keep failing, the LLM is likely struggling with JSON output for those specific titles. Try increasing `heavy_ctx` in `wiki.toml` (see [Tuning context windows](#tuning-context-windows)).\n\n---\n\n**Q: I see `structured_output attempt N failed` messages during compile — is something broken?**\n\nNo. This is the built-in 3-tier retry system working as designed. The model occasionally echoes the JSON schema structure instead of flat output — the retry corrects it. Articles are still generated. A real failure surfaces as `article(s) failed: ...` in the summary line.\n\n---\n\n**Q: `olw ingest --all && olw compile` gives \"Missing option '--vault'\".**\n\nRun `olw setup` first to configure a default vault, or pass it explicitly:\n\n```bash\nexport OLW_VAULT=~\u002Fmy-wiki\nolw ingest --all && olw compile\n```\n\n---\n\n**Q: I changed models in `olw setup` but `olw compile` still uses the old model.**\n\nRe-run `olw init` on your vault — it syncs the model settings from your global config into `wiki.toml`:\n\n```bash\nolw init ~\u002Fmy-wiki\n```\n\n---\n\n**Q: A concept keeps getting rejected — how do I stop it from recompiling?**\n\nAfter 5 rejections with feedback (`olw reject --feedback \"…\"`), the concept is auto-blocked and excluded from future compiles. `olw status` lists blocked concepts. To re-enable one:\n\n```bash\nolw unblock \"Concept Name\"\n```\n\n---\n\n**Q: Can I use a cloud provider like Groq or Together AI instead of Ollama?**\n\nYes. Run `olw setup` and select the provider from the numbered list. Enter your API key when prompted — it is stored only in `~\u002F.config\u002Folw\u002Fconfig.toml`. Alternatively set the provider-specific env var before each command:\n\n```bash\nexport GROQ_API_KEY=gsk_...\nolw run\n```\n\nThe pipeline, vault structure, and all `olw` commands work identically regardless of provider.\n\n---\n\n**Q: I changed providers in `olw setup` but `wiki.toml` still shows `[ollama]`.**\n\nRe-run `olw init` on your vault to sync the global config into `wiki.toml`:\n\n```bash\nolw init ~\u002Fmy-wiki\n```\n\nFor existing vaults with a `[ollama]` section you can also add a `[provider]` block manually — it takes precedence over `[ollama]` when present.\n\n---\n\n## Why not just use a chatbot?\n\nChatbots forget. Every conversation starts fresh. This tool builds a **persistent artifact** — a wiki that grows with every note you add, that you can open in Obsidian, search, query, and edit by hand.\n\nThe LLM is a compiler, not a conversation partner. You give it raw material; it produces structured knowledge. The output is plain markdown files you own forever.\n\n---\n\n## Feedback\n\n`olw` does not collect telemetry.\n\nIf something was confusing, useful, annoying, or missing, please tell us:\n- Bug reports: https:\u002F\u002Fgithub.com\u002Fkytmanov\u002Fobsidian-llm-wiki-local\u002Fissues\n- Suggestions and experience reports: https:\u002F\u002Fgithub.com\u002Fkytmanov\u002Fobsidian-llm-wiki-local\u002Fdiscussions\n- Source code: https:\u002F\u002Fgithub.com\u002Fkytmanov\u002Fobsidian-llm-wiki-local\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","该项目旨在将你的Markdown笔记转化为一个自我完善的、互相关联的维基系统，由本地大语言模型驱动。其核心功能包括自动提取概念并创建或更新维基文章，支持用户反馈以持续优化生成内容。技术上，它完全基于本地运行（默认使用Ollama），同时也兼容其他OpenAI API接口的服务提供商，确保了数据隐私和灵活性。适用于个人知识管理、构建第二大脑等场景，特别适合希望在本地环境中利用AI增强笔记整理与学习效率的用户。",2,"2026-06-11 02:40:27","CREATED_QUERY"]