CLI tool
Ar9av/obsidian-wiki avatar
Ar9av/obsidian-wiki

obsidian-wiki: A Markdown Vault Your AI Agent Maintains, Not Just Fills

Project brief: Framework for AI agents to build and maintain a digital brain through Obsidian wiki. obsidian-wiki A digital brain you grow with your AI agent.

3,744 stars375 forksPythonMIT

At a glance

What is it?
obsidian-wiki turns an Obsidian folder into a compiled knowledge base that AI agents query and update via 39 skill files. It trades a runtime for plain markdown and promises faster, more accurate structural answers, with real trade-offs in setup and trust.
Who is it for?
Adopt obsidian-wiki if you live in Obsidian, want to own your knowledge as plain markdown, and already use an AI agent that can read skill files. Skip it if you need a managed service, if your team expects a GUI, or if you cannot tolerate occasional agent missteps that require manual correction.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • Ar9av/obsidian-wiki3,744 ★ · +630
Star history
Repository2026-08-042026-11-15
Ar9av/obsidian-wiki3.1k3.7k

630 Stars in the last 103 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The Problem: Re-solving Problems You've Already Solved

The README opens with a familiar pain: you solve a hard problem, then months later in a different repo you solve it again from scratch because the answer lives in a chat log you will never find. obsidian-wiki targets exactly that. It is for developers, researchers, and technical writers who use AI agents like Claude Code, Cursor, or Codex, and who want a persistent, queryable memory that is not a pile of chat transcripts. The framework compiles what you learn into interconnected markdown files that you own. It is not a notes app and not a vector database. It is a set of skill files that any agent can read and execute, turning your Obsidian vault into a structured knowledge graph.

How It Works: Skills, Not a Runtime

The core mechanism is deceptively simple. Every skill is a markdown file that an agent reads and runs. There is no separate runtime, no API keys, and no vendor. The README lists 39 skills, each a command like /wiki-ingest, /wiki-update, or /wiki-query. When you ask a question, the agent executes the relevant skill, which likely calls into the Python package's CLI. The package tracks every source ingested in a manifest, so subsequent runs only process the delta, not your whole library. This is a compile step, not an accumulate step: new knowledge merges into existing pages, contradictions get flagged, and duplicates are resolved. Claims are tagged as extracted, inferred, or ambiguous, giving you a way to distinguish known facts from model speculation.

Getting Started: The 60-Second Install

The README claims a 60-second setup. You run pip install obsidian-wiki, then obsidian-wiki setup --vault ~/brain. That creates a vault folder with the necessary structure. The next step is to open any project in your agent and say "set up my wiki". If you prefer not to touch a terminal, you can give your agent a URL and it will do the whole thing. The installation docs cover other paths: git clone, a Skills CLI, and multiple vaults. There is also a sessions-build command to index past chat sessions, and a sessions-query to find a specific conversation by description. The design keeps everything local: no service, no lock-in, plain markdown in a folder.

The Honesty Layer: Lint, Dedup, and Contradiction Flags

A vault that accumulates without discipline becomes a mess. obsidian-wiki includes maintenance skills that keep it honest. /wiki-lint checks for broken links, orphans, and contradictions. /wiki-dedup merges pages that refer to the same concept, like "RSC" and "React Server Components". /cross-linker weaves new pages into the existing graph. The claim-tagging system (extracted, inferred, ambiguous) is a deliberate design choice to flag pages that drift into speculation. This is a meaningful difference from a plain notes folder, where you cannot tell what you actually know versus what an LLM guessed. The lint skill is the mechanism that enforces that distinction.

The Benchmark: Faster and More Accurate, With Caveats

The README includes a small benchmark comparing a plain agent against one with obsidian-wiki installed. On a 38-page vault, with Claude Sonnet, the framework answered structural questions 4.4x faster (19s vs 81s) and got 83% correct versus 44%. Tool calls dropped from 9.9 to 4.6, while API cost stayed roughly unchanged at $0.208. The method section is unusually honest: n=2 per cell, one run failed outright because the model ignored the CLI and grepped by hand. The accuracy gap is attributed to the plain agent routing through index.md, which links to every page, so it found meaningless short paths. The framework's graph excludes bookkeeping files, so that error is unreachable. Treat the exact percentages as indicative; the wall-clock gaps are more robust.

Limitations and Failure Modes

The most glaring limitation is that the framework depends on the agent following instructions. The benchmark's failed run proves that a model can ignore the CLI and fall back to ad-hoc grep, producing wrong answers. There is no enforcement mechanism; the skill files are just markdown. If your agent does not read them, you get no benefit. Second, the setup requires a terminal or agent interaction, which may deter non-technical users. Third, the delta manifest only helps if it is accurate; a corrupted manifest could cause re-ingestion or missed updates. Fourth, the claim tags are only as good as the model's confidence estimation, which is not calibrated. Finally, the README does not detail how the graph is built or how contradictions are detected, so you cannot verify the reliability without reading the source.

Alternatives: RAG vs. Compiled Knowledge

The obvious alternative is retrieval-augmented generation (RAG), where you index documents into a vector store and query it each time. The README explicitly contrasts with this: it compiles knowledge once and keeps it current, instead of asking an LLM the same questions forever or re-running RAG. RAG is better for unstructured, ever-changing corpora where you want to retrieve raw chunks. obsidian-wiki is better for structured knowledge that you want to maintain and reason over. Another alternative is a plain notes folder with manual links, but that lacks the dedup and contradiction checking. The choice comes down to whether you want a living document that evolves or a retrieval system that stays static.

Maintenance and License

Maintenance cost is low if you trust the skills, but the README suggests the vault gets messy on its own, so you need to run lint and dedup periodically. The project is under the MIT license, which gives you freedom to modify and redistribute, but you get no warranty. The repository is actively developed, with releases every few days in August 2026, suggesting a fast iteration cycle. That also means you may need to track updates to the skill files if you rely on them. The docs mention a Skills Reference and an Architecture page, which you should read before adopting. There is no mention of a migration path for existing vaults, so you may need to re-ingest everything.

Editorial conclusion

Adopt obsidian-wiki if you live in Obsidian, want to own your knowledge as plain markdown, and already use an AI agent that can read skill files. Skip it if you need a managed service, if your team expects a GUI, or if you cannot tolerate occasional agent missteps that require manual correction. Before committing, verify that your agent actually follows the skill instructions, test the delta manifest on a large vault, and confirm that the inferred tags match your domain's confidence needs. The project's own benchmark shows one run where the model ignored the CLI and failed, so plan for that failure mode. The core judgement: this is a promising, cost-effective pattern for individual knowledge workers, not a turnkey enterprise solution.

Frequently asked questions

what is obsidian wiki?

A framework of markdown skills that let an AI coding agent build and maintain a knowledge base in an Obsidian vault. The vault is plain markdown on disk, and the pattern is credited to an LLM wiki gist: compile knowledge once and keep it current instead of re-running retrieval every time.

how to use obsidian wiki?

Install the package and run the setup command with a path to your vault, which also registers two session hooks unless you pass the flag that skips them. Then open a project in your agent and ask it to set up the wiki, or use the ingest, query, capture and history skills to feed it and ask it questions.

Does obsidian-wiki need an API key or a vector database?

Not for the core command line tool, whose dependency list is empty: the README states there is no API key, no embedding model, no vector store and no network, since the vault is markdown on disk. The optional server extra does add an HTTP and MCP service that takes a key, and the shipped compose file will not start without one.

How does obsidian-wiki separate facts from guesses?

Every claim is tagged as extracted, as inferred or as ambiguous, and a lint skill flags pages drifting into speculation. Contradictions are flagged rather than silently resolved, and a separate skill collapses pages that describe the same thing, such as an acronym page and its long form.

What happens if two agents write to the same vault?

The shared files, including the index, the log, the hot list, the owner profile and the todo index, all go through a single writer that takes a lock and writes atomically, so parallel agents cannot drop each other's updates.

How does obsidian-wiki compare with RAG?

The README's stated position is that knowledge should be compiled once and kept current rather than re-running retrieval every time, with a manifest recording every ingested source so a second run processes only the delta. The document's own comparison section is not reproduced here, so treat that as the framing rather than a full comparison.

Official sources

  1. Official README
  2. Project repository
  3. Release notes
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/ar9av-obsidian-wiki.svg)](https://hysenlabs.com/projects/ar9av-obsidian-wiki)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/ar9av-obsidian-wiki.svg)](https://hysenlabs.com/projects/ar9av-obsidian-wiki)

Was this useful?