AI Wiki

Русская версия →

Automatically builds and maintains a knowledge-base wiki from your notes using an AI assistant.

Why AI Wiki:

• Offline by default — works with Ollama or any local AI server; your notes never leave your machine
• Grows with your notes — every Ingest adds new topics and updates existing ones automatically
• Transparent — watch every AI step in real time in the sidebar panel
• Two AI backends — local (Ollama / OpenAI-compatible) or Claude AI; switch any time in settings

Supported backends: Ollama / OpenAI-compatible (fully local) · Claude Agent (Anthropic cloud)

What it does

AI Wiki reads your notes and maintains a structured knowledge base (wiki) alongside them. Think of it as an assistant that reads what you write and keeps a living reference document up to date.

Fix, Format, and Chat are launched from sidebar buttons, not the Command Palette. Export OKF is available both as a sidebar button and a Command Palette command.

Mobile: only Query works on mobile. Ingest, Lint, Init, Format, and Export OKF are desktop-only.

OKF frontmatter: wiki pages use Google's Open Knowledge Format — a mandatory type (the entity-type subfolder) plus description/resource/timestamp/tags/status. The knowledge graph lives in ## Related / ## External links body sections (Obsidian [[wikilinks]] on disk, rewritten to markdown links only in the OKF export).

Security

Shell execution

The Claude Agent backend starts an external process to run the Claude CLI:

• What is executed: the absolute path you configure in Settings → "Path to Claude Code" (e.g. /home/user/iclaude.sh). The path is validated to be absolute and free of traversal sequences before each spawn.
• Why it's required: the Claude Agent backend calls claude / iclaude.sh as a subprocess. There is no alternative to child_process.spawn for this architecture.
• Your permissions: the subprocess inherits your OS user's permissions — the same as running Claude CLI manually in a terminal.
• First-run consent: on first launch with Claude Agent selected, a confirmation dialog appears before anything runs. You can revoke consent by removing shellConsentGiven from the plugin's local.json.

Vault access

The plugin reads only the folders you set as sources for each domain. It does not scan your entire vault.

Quick start: Ollama (fully local)

No accounts or cloud services required — AI runs on your computer.

1. Install Ollama

Download from ollama.com and pull a model:

ollama pull llama3.2

2. Install the plugin

Copy the plugin folder into your vault:

# symlink for development
ln -s /path/to/obsidian-ai-wiki ~/.config/obsidian/Plugins/obsidian-ai-wiki

Or copy the folder to <vault>/.obsidian/plugins/obsidian-ai-wiki/ manually.

3. Enable the plugin

Obsidian → Settings → Community plugins → find "AI Wiki" → enable.

4. Configure

Settings → AI Wiki:

5. Create a knowledge area (domain)

A domain is a pair: "source folder → wiki folder". The AI reads files from the source folder and writes wiki pages to the wiki folder.

Open the AI Wiki sidebar panel (ribbon icon or Command Palette → "Open panel"), then:

1. Click the Init button in the "Create" section
2. Enter a domain name (e.g. work)
3. Add source folder paths — the folders containing notes you want to turn into wiki
4. Click Run — the plugin creates the wiki folder and starts building pages

6. First Ingest

1. Open any note in Obsidian
2. In the sidebar, select your domain from the dropdown
3. Click the Ingest button
4. Watch progress in the sidebar — new wiki pages appear in the domain folder

Quick start: Claude Agent

For users with Claude Code CLI installed.

1. Requirements

• Installed iclaude.sh / iclaude / claude (Claude Code CLI)

2. Install and enable the plugin

Same as steps 2–3 of the Ollama section above.

3. Configure

Settings → AI Wiki:

4. First Ingest

Same as step 6 of the Ollama section above.

Sidebar panel

The sidebar is the main interface for AI Wiki. Open it via the ribbon (🧠 icon) or Command Palette → "Open panel".

Sections

Create — click Init to set up a new knowledge domain (name, wiki folder, source paths).

Fill / Maintain — manage and populate an existing domain:

• Domain selector — choose which domain to work with
• ↻ refresh the domain list
• 📁+ manage source folders (add or remove)
• ♻ full re-init: remove and recreate the complete domain tree, then rebuild from sources
• 📜 open the domain log file
• 🗒 open the domain index file
• Ingest — process the currently open note
• Lint — review wiki quality and find gaps
• Format — clean up the currently open note's formatting

Query — type a question and click Ask. The answer appears in the sidebar with wiki cross-links. Use the Chat section below the result to refine or follow up.

Model progress and Re-init

Each model request uses one human-readable sidebar lifecycle: Preparing request → Request sent to model → Waiting for model response → Model is producing a response → Validating response → Applying result → Completed (or a terminal retry, failure, or cancellation). Reasoning remains available in its expandable block. Call sites, transport details, attempts, budgets, and provider data stay in agent.jsonl, not sidebar labels. The waiting timer shows UI elapsed time; it is not a provider heartbeat and does not extend the idle deadline. Agent-log reasoning is retained in ordered bounded records up to 4 MiB per operation; excess text is replaced by a metadata-only truncation marker.

For Native Agent, a replacement transport attempt starts a fresh human lifecycle at Preparing request. The sidebar does not show retry counters or HTTP details. agent.jsonl records metadata-only transport_retry_scheduled, transport_retry_recovered, and transport_retry_exhausted events with the logical request ID, lifecycle ID, status/classification, delay, attempt bound, and timeout values; request bodies, response content, authorization headers, and API keys are never retry diagnostics.

Background structured work—Init bootstrap, evidence map/reduce, Ingest synthesis, and bounded Lint batches—uses atomic non-stream responses. Interactive Chat, the Query answer, and Format use SSE so reasoning or answer text can appear as it arrives.

Full Re-init validates bootstrap output and source snapshots before mutation, then removes the entire !Wiki/<domain> tree exactly once: pages, metadata, indexes, logs, temporary content, nested type folders, and obsolete empty directories. It recreates fresh metadata and index state before ingest. A deletion or concurrent-write conflict aborts source ingest; the transaction restores the prior snapshot when safe and never overwrites a concurrently recreated domain tree.

Commands (Command Palette)

Settings reference

General (both backends)

Domains

List of created domains with Edit / Delete buttons. Domain map is stored in !Wiki/_config/_domain.json.

Backend selector

Claude Agent

Claude output limits are owned by the external Claude CLI configuration. AI Wiki bounds and packs Claude input, but does not send or expose a plugin-owned Claude output budget. Claude keeps its existing guarded operation-level idle retry behavior; it does not use Native Agent's request executor, HTTP status matrix, or connection-timeout transport.

Native Agent

Native transient request recovery

Native Agent retries only the current identical OpenAI-compatible request, up to the configured number of additional attempts. It never replays Init, Re-init, Ingest, a source read, WipeDomain, completed evidence, or page/index application. Eligible failures are connection errors/timeouts and HTTP 408, 409, 429, and 5xx. Provider x-should-retry: true can opt in another transient response; x-should-retry: false always opts out. HTTP 400, 401, 403, 404, and 422, context-limit and schema failures, cancellation, permanent TLS/certificate errors, and application/index/embedding failures are not transport-retried.

Persisted retry diagnostics accept only connection, connection-timeout, allowlisted temporary-transport, retryable-HTTP, and explicit provider-override classifications. Transport classifications carry no HTTP status; HTTP classifications must carry a consistent valid status, and recovered/exhausted diagnostics must match the scheduled failure they close.

Retry stops after nonblank reasoning or content, or when the additional-attempt bound is exhausted. Connection timeout (15 seconds), model idle timeout (300 seconds), and retry count (3) are independent top-level settings; existing persisted values are preserved. A healthy response may take longer than 15 seconds because that value applies only to desktop connection establishment. On Mobile, Native Agent keeps the host-provided transport, so an exact DNS/TCP/TLS-only timeout cannot be guaranteed; request retry and model-idle handling remain separate from that limitation.

Vision

Bounded processing and storage

These controls cover different parts of a call: Input budget tokens bound the prepared request, Output budget tokens cap the generated response, and Thinking budget tokens separately allow native-model reasoning when the provider supports it. Native Agent owns all three controls; Claude input is governed by AI Wiki while Claude output remains CLI-owned.

The input budget governs the complete prepared request, including system/schema instructions—not just note text. When content does not fit, AI Wiki packs complete context units and uses operation-specific batching or splitting instead of silently truncating required content. Provider context errors can trigger a smaller repack. The configured budget remains explicit; AI Wiki does not automatically discover a model's context window.

Ingest splits oversized Markdown at stable section, paragraph, line-window, and fenced-code boundaries. Bounded map calls produce source-anchored evidence; reduction calls preserve coverage before synthesis. New pages are complete documents. Existing pages receive page/section-hash-guarded add, append, or replace patches, so untouched sections are preserved and stale content is not overwritten.

index.jsonl is structured storage: page records hold retrieval metadata, while chunk records hold embedding metadata and vectors. Serialized vectors and raw index records never enter model prompts; prompt builders project only the selected evidence, Markdown sections, and allowlisted metadata they need. Unchanged chunk embeddings are reused when their embedding-text hash, model, and dimensions still match.

Small sources keep the short path. Oversized sources, pages, histories, notes, or PDFs can require extra bounded model calls, increasing latency and provider cost in exchange for complete processing within the configured input budget. Vision Check is also a real provider request and may incur a small charge.

Destructive Re-init acceptance must use a private copied vault, never the working vault. The protected replay root must be a recent /tmp/ai-wiki-bounded-ingest-replay.* directory with an owner-only .replay-provenance marker that records the resolved source and replay root. Install the build into its run copy, visibly confirm that vault path in Obsidian, and only then perform the human Re-init checkpoint. The read-only replay auditor rejects duplicate wipe/source/page/index effects, invalid retry lifecycles, timeout drift, retry after content, and recovery that does not continue to the next step. A recovered transport response may enter a correlated structured-repair lifecycle before successful validation/application/completion. Page mutations count only after the matching successful tool_result; metadata-only index checkpoints correlate both index reconciliation stages to the active source and selected domain.

Proxy (native-agent only)

Graph

Developer (desktop only)

Sync

local.json (inside the plugin folder) stores machine-specific settings: the path to Claude CLI, API key, and selected backend. Exclude local.json from sync when using Obsidian Sync / git / Syncthing — otherwise settings will be overwritten on other machines.

The domain map (!Wiki/_config/_domain.json) lives inside the vault and syncs normally with your notes.

Performance reference

Real-world measurements from a homelab inference server running deepseek-v4-flash:cloud via Native Agent (OpenAI-compatible endpoint). Numbers show what to expect at roughly 100–130 output tokens/second — a mid-range local or self-hosted GPU.

Init and Lint scale with the number of source files and wiki pages. A domain with 6 files takes ~6 min; 24 files — ~27 min. Lint scanned a large domain (69 LLM calls) in about 60 min.

What affects speed

• Model — smaller/quantized models are faster; larger models produce better wiki quality
• Inference server — a local GPU is fastest; cloud APIs add network latency
• Domain size — Init and Lint time grows linearly with the number of files
• Oversized inputs — bounded map/reduce, batching, and segmentation add calls to preserve complete coverage

Documentation

• docs/dev.md — build, install, smoke-test checklist for developers
• docs/README.ru.md — Russian version of this README