Prerequisites

• macOS or Linux (systemd or cron)
• Node.js 20+
• Claude Code (sessions at ~/.claude/projects/)
• Obsidian vault
• A distill provider — any one of:
• Anthropic API key (predictable per-session cost, no effect on your Claude Code limits)
• Your Claude Code subscription (provider: "claude-cli" — free and keyless; distills consume your Claude Code usage limits)
• Kie.ai API key (~72% cheaper, third-party proxy — used for testing and calibration runs, not recommended for your real vault)
• Optional: Ollama + nomic-embed-text for semantic search

Quick start

npm install -g @djolex999/vir-cli
vir init
vir run

vir init is a wizard: provider, models, vault path. vir run does one pass over your sessions and writes notes. When you like the output, vir schedule install registers a daemon that keeps the vault current.

The zero-dollar option: `claude-cli`

With provider: "claude-cli" vir shells out to your installed claude binary instead of calling an API — no key, no per-session dollars. The trade: every distill consumes your Claude Code subscription quota (the same limits your interactive sessions use), and that quota has no meter. vir therefore caps claude-cli runs at 25 sessions per run (the rest are picked up next cycle), halts immediately if your subscription limit is hit (with the reset time; nothing is retried against the wall), and records these calls in cost.log with cost marked not-applicable — never a fake $0.00. The API path remains the default.

Semantic search (optional)

Vir works out of the box with keyword search (TF-IDF). No embedding setup is required, ever. For semantic search, pick one of two providers; vir detects whichever is present:

One command, no Ollama:

vir embed --setup      # installs fastembed + bge-small-en-v1.5 into ~/.vir
                       # (~233 MB + ~128 MB model; states cost, asks first)

Or Ollama (768d, slightly larger model):

brew install ollama
ollama pull nomic-embed-text
ollama serve

Then:

vir embed
vir query "how do I handle rate limiting in Next.js"

Every stored vector records the model that produced it. Vectors from different models are never compared; if you switch providers, vir embed --force re-embeds the index after telling you what it costs. Falls back to keyword search automatically when no provider is available, and says so: via tfidf (no provider). MMR reranking balances relevance against diversity, tunable via retrievalDiversity (default 0.3).

Config reference

Located at ~/.vir/config.json.

MCP server (Claude Code integration)

Vir runs as an MCP server, letting Claude Code consult your vault mid-session instead of relying on static CLAUDE.md content.

vir mcp install

Restart Claude Code. The vault is now queryable mid-session via six tools: vir_query, vir_status, vir_recent_notes, vir_recent_articles, vir_project_summary, vir_compose. vir_query takes a type filter (session | article | topic | pdf | all). Human-verified notes (approved via vir review) rank first; pass verified_only: true to see only those. The server is read-only: it never spends tokens and never writes files.

To unregister: vir mcp uninstall.

How vir compares

The LLM Wiki space has grown fast. Honest comparison:

vs other LLM Wiki implementations

vs Claude Code memory tools

Different tools for different needs:

- If you want a polished cross-platform desktop app for general document knowledge bases, use lucasastorian/llmwiki or nashsu/llm_wiki. - If you want multi-agent support with a rich entity/concept page taxonomy and don't care about Obsidian integration depth, use Pratiyush/llm-wiki. - If you want a heavyweight Claude Code memory plugin with real-time capture and vector storage, use claude-mem. - If you're building AI applications that need to remember users long-term, use mem0 (different layer entirely). - If you want an Obsidian-native LLM Wiki that reads your existing Claude Code sessions, use vir.