Ar9av/obsidian-wiki: a markdown vault your AI agent compiles and maintains

The problem obsidian-wiki is aimed at

The README opens with a scenario rather than a feature list: you solve a hard problem on a Tuesday, and three months later you solve it again from scratch in a different repository, because the answer lived in a chat log you will never find again. The stated fix is to point the tool at a folder, tell your agent what to remember, and let it compile what you learn into interconnected markdown. The design lineage is explicit: the project cites Andrej Karpathy's LLM Wiki gist, whose argument is that you should compile knowledge once and keep it current rather than asking an LLM the same questions forever or re-running RAG on every query. The audience is developers who already use an agent such as Claude Code, Cursor, Codex, Windsurf or Gemini CLI and who want the output to live in files rather than in a vendor's index. If you do not already work inside one of those agents, the project has no interface for you.

Skills as markdown files, and what the CLI actually does

The architecture is unusual in a way that is easy to miss. Every skill is a markdown file that the agent reads and executes, so there is no runtime, no API keys and no vendor in the loop. The repository carries a .skills/ directory that is symlinked into each agent you use, and the top-level entries show per-agent directories for Claude, Cursor, Windsurf, Kiro, Gemini and others. The Python package is the other half: pyproject.toml declares a pure-stdlib CLI with an empty dependencies list and the comment that installing skills needs no third-party runtime dependencies. Optional extras pull in heavier machinery when you want it: ast adds tree-sitter for real AST extraction instead of the regex fallback, graph adds leidenalg and igraph for Leiden community detection instead of greedy label propagation, and server adds FastAPI, uvicorn and mcp for the HTTP and MCP memory server. Versioning is dynamic through hatch-vcs, so the version comes from the git tag rather than a hand-edited field. The consequence is a split you should understand before adopting: the CLI handles setup, ingestion plumbing, session indexing and sync, while the reasoning about your notes happens in the agent, driven by the skill files.

Installing obsidian-wiki and running a first ingest

The README gives a two-command path. The first installs the package from PyPI and the second points it at a vault directory, creating one if it does not exist.

pip install obsidian-wiki
obsidian-wiki setup --vault ~/brain

After that, the README says to open any project in your agent and say "set up my wiki". If you would rather not touch a terminal, the README offers an alternative: hand the agent the repository URL and the same instruction, and it performs the setup itself. For a containerised memory service there is a Dockerfile and a compose file. The compose service builds the image, maps port 8080, mounts a named volume at /vault and requires WIKI_API_KEY to be set in .env, with the variable written as ${WIKI_API_KEY:?set WIKI_API_KEY in .env} so the compose file fails fast when it is missing.

services:
  wiki:
    build: .
    ports: ["8080:8080"]
    environment:
      WIKI_API_KEY: ${WIKI_API_KEY:?set WIKI_API_KEY in .env}
    volumes:
      - wiki-data:/vault
    restart: unless-stopped

The image sets OBSIDIAN_VAULT_PATH to /vault, WIKI_PORT to 8080 and WIKI_HOST to 0.0.0.0, since the default host is loopback and a container has to listen on every interface. A healthcheck polls http://127.0.0.1:8080/health every 30 seconds. Note the build argument: because .git is excluded from the build context, hatch-vcs cannot read the tag, so the Dockerfile defaults VERSION to 0.0.0 and expects CI to pass the real one. Once installed, the working loop is a set of slash commands the agent runs, including /wiki-ingest on a directory, /wiki-update to distil the repository you are standing in, /wiki-capture to save the current conversation, and /wiki-query to ask questions. The README states that answers come back with [[wikilink]] citations.

What keeps the vault from turning into a pile of duplicates

The claims that matter here are about maintenance rather than capture. The README says new knowledge merges into existing pages, contradictions get flagged, and nothing gets duplicated, with /wiki-lint reporting broken links, orphans and contradictions and /wiki-dedup collapsing near-duplicate pages such as "RSC" and "React Server Components". Every claim in a page is tagged extracted, inferred or ambiguous, and lint flags pages drifting into speculation. Incremental behaviour comes from a manifest that tracks every source already ingested, so a second run processes the delta rather than the whole library. Query cost is addressed by reading titles, tags and summaries before page bodies, which the README argues keeps cost roughly flat between 20 and 2000 pages. Configuration for all of this sits in environment variables: OBSIDIAN_VAULT_PATH is required, OBSIDIAN_SOURCES_DIR lists comma-separated directories to ingest, OBSIDIAN_CATEGORIES defaults to concepts,entities,skills,references,synthesis,journal, and OBSIDIAN_MAX_PAGES_PER_INGEST caps pages per operation at 15. One detail worth copying: if a directory in OBSIDIAN_SOURCES_DIR contains a .git folder it is enumerated with git ls-files, so whatever the repository's own .gitignore excludes is skipped automatically rather than by a hardcoded list.

The benchmark table, and why you should read the method note

The README publishes a comparison that is unusually specific: same model, same vault, same questions, with and without the tool. It reports time to answer dropping from 81s to 19s, correct answers rising from 44% to 83%, tool calls falling from 9.9 to 4.6, and API cost essentially unchanged at $0.202 versus $0.208. The stated failure of the plain agent is concrete and worth understanding: asked to trace a connection, it routed through index.md, which links to every page, so it found a short path that means nothing, and it named index as one of the most important pages. The skills exclude bookkeeping files from the graph, so that answer is not reachable. The method note is candid and should temper the numbers. It is Claude Sonnet, headless, on a real 38-page vault, with four questions, two conditions and two repetitions per cell, run serially. Ground truth came from networkx rather than from the project's own code, with betweenness matching to 3.5e-18 and all 630 shortest-path pairs agreeing. The README itself says to treat the exact percentages as indicative because n=2 per cell, that the wall-clock gaps are larger than the run-to-run spread, and that one run in the "with" column failed outright when the model ignored the CLI, grepped by hand and got it wrong. That last admission is the most useful sentence in the table's vicinity.

Where obsidian-wiki is the wrong choice

The dependency-free core is a strength and a boundary. Because the skills are markdown that an agent interprets, the quality of ingestion, deduplication and query answering depends on the model you point at the vault, not on code the project controls. The failed run described in the README is the shape of that risk: an agent that ignores the CLI and greps by hand gets none of the graph benefits. The benchmark is also small, one 38-page vault, so there is no published evidence about behaviour at the scale where a manifest and summary-first retrieval would matter most. There is no documented rollback path for a bad ingest, and no documented conflict resolution when two sources disagree beyond the claim that contradictions get flagged. If your corpus is large and mostly static, a conventional RAG pipeline with an embedding index is a better fit: it retrieves over document text directly and does not depend on an agent choosing to run the right skill. If you want a hosted product with a web UI, accounts and sharing, this is not that. The vault is a folder of markdown and the interface is a terminal plus your agent.

Alternatives and the real difference in approach

The README names the alternative itself: re-running RAG, or asking an LLM the same questions repeatedly. The distinction is compile versus retrieve. A RAG system leaves your documents where they are, chunks and embeds them, and reconstructs an answer at query time from retrieved passages; nothing is rewritten, so the source of truth never changes and the same question costs roughly the same every time. obsidian-wiki instead asks the agent to produce and maintain a second artefact, the wiki, where knowledge is merged into pages, deduplicated and cross-linked, and where retrieval reads titles, tags and summaries first. That buys you a browsable graph in Obsidian and citations in the form of wikilinks, at the cost of a write step that can be wrong, a vault that needs linting, and a hard dependency on an agent that follows instructions. The project also sits next to plain note-taking. The README's argument against a notes folder is that this compiles rather than accumulates, and that the graph view plus exports to graph.json, GraphML, Neo4j Cypher, Postgres SQL or a self-contained graph.html give you structure a folder does not. If you never query your notes structurally, that argument does not apply to you.

Licence, maintenance and upgrade cost

The licence is MIT, declared both in pyproject.toml and via a LICENSE file, with license-files pointing at it. MIT is permissive, so the practical implication is that you can vendor the skill files into a private repository and modify them; the usual obligation is preserving the copyright and licence text, and nothing here constitutes legal advice. The package is classified as Development Status 4 - Beta, which matches the release cadence: v2026.08.4, v2026.08.5 and v2026.08.6 all landed in August 2026, the last push was on 2026-08-26, and the repository is not archived. That is a fast-moving beta, so pinning a version is reasonable if you depend on CLI behaviour. Upgrading is cheap in one sense and not in another. The CLI is a pip install away and the skills are markdown files you can diff, but the skills are also the interface your agent learned, so a rename or a changed instruction can silently alter how your vault gets written. The version is derived from git tags through hatch-vcs, which is why the Dockerfile has to be handed a VERSION build argument. Sync is configured with obsidian-wiki sync-setup <repo-url> and has no environment variable by design: the vault's own git remote is the source of truth, so it cannot drift from a config file. The Dockerfile installs git specifically because obsidian_wiki/sync.py shells out to it.

Editorial conclusion

Adopt obsidian-wiki if you already drive a coding agent daily and want your notes to accumulate as plain markdown you can grep, diff and delete. Do not adopt it if you expect a hosted service, a GUI, or retrieval over a corpus of thousands of documents; the skills are the product and the agent is the runtime. Before committing, verify that your agent actually picks up the .skills/ directory, then run obsidian-wiki setup against a throwaway vault and inspect the categories the setup creates.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes