obsidian-wiki

A knowledge mgmt system inspired by gist published by Andrej Karpathy about maintaining a personal knowledge base with LLMs : the "LLM Wiki" pattern.

Instead of asking an LLM the same questions over over (or doing RAG every time), you compile knowledge once into interconnected markdown files and keep them current. In this case Obsidian is the viewer and the LLM is the maintainer.

We took that and built a framework around it. The whole thing is a set of markdown skill files that any AI coding agent (Claude Code, Cursor, Windsurf, whatever you use) can read and execute. You point it at your Obsidian vault and tell it what to do.

git clone https://github.com/Ar9av/obsidian-wiki.git
cd obsidian-wiki
bash setup.sh

setup.sh asks for your vault path, writes the config to ~/.obsidian-wiki/config, symlinks skills into all your agents, and installs wiki-update globally so you can use it from any project.

OBSIDIAN_VAULT_PATH is just any directory where you want your wiki documents to live. It can be a new empty folder or an existing Obsidian vault. Obsidian will read from it directly.

Open the project in your agent and say "set up my wiki". That's it.

This framework works with any AI coding agent that can read files. The setup.sh script automatically configures skill discovery for each one:

How it works: Each agent has its own convention for discovering skills. setup.sh symlinks the canonical .skills/ directory into each agent's expected location, and creates the bootstrap file that tells the agent about the project. You write skills once, every agent can use them.

If you don't want to run setup.sh, you can configure your agent manually:

cd /path/to/obsidian-wiki && claude "set up my wiki"

cd /path/to/obsidian-wiki && codex "set up my wiki"

cd /path/to/obsidian-wiki && openclaw "set up my wiki"

Every ingest runs through four stages:

1. Ingest — The agent reads your source material directly. It handles whatever you throw at it: markdown files, PDFs (with page ranges), JSONL conversation exports, plain text logs, chat exports, meeting transcripts, and images (screenshots, whiteboard photos, diagrams — vision-capable model required). No preprocessing step, no pipeline to run. The agent reads the file the same way it reads code.

2. Extract — From the raw source, the agent pulls out concepts, entities, claims, relationships, and open questions. A conversation about debugging a React hook yields a "stale closure" pattern. A research paper yields the key idea and its caveats. A work log yields decisions and their rationale. Noise gets dropped, signal gets kept. Each page also gets a 1–2 sentence summary: in its frontmatter at write time — later queries use this to preview pages without opening them.

3. Resolve — New knowledge gets merged against what's already in the wiki. If a concept page exists, the agent updates it — merging new information, noting contradictions, strengthening cross-references. If it's genuinely new, a page gets created. Nothing is duplicated. Sources are tracked in frontmatter so every claim stays attributable.

4. Schema — The wiki schema isn't fixed upfront. It emerges from your sources and evolves as you add more. The agent maintains coherence: categories stay consistent, wikilinks point to real pages, the index reflects what's actually there. When you add a new domain (a new project, a new field of study), the schema expands to accommodate it without breaking what exists.

A .manifest.json tracks every source that's been ingested — path, timestamps, which wiki pages it produced. On the next ingest, the agent computes the delta and only processes what's new or changed.

• Delta tracking. A manifest tracks every source file that's been ingested: path, timestamps, which wiki pages it produced. When you come back later, it computes the delta and only processes what's new or changed. You're not re-ingesting your entire document library every time.

• Project-based organization. Knowledge gets filed under projects when it's project-specific, globally when it's not. Both are cross-referenced with wikilinks. If you're working on 10 different codebases, each one gets its own space in the vault.

• Archive and rebuild. When the wiki drifts too far from your sources, you can archive the whole thing (timestamped snapshot, nothing lost) and rebuild from scratch. Or restore any previous archive.

• Multi-agent ingest. Documents, PDFs, Claude Code history (~/.claude), Codex sessions (~/.codex/), Windsurf data (~/.windsurf), ChatGPT exports, Slack logs, meeting transcripts, raw text. There's a specific skill for Claude history that understands the JSONL format and memory files, and a catch-all skill that figures out whatever format you throw at it.

• Audit and lint. Find orphaned pages, broken wikilinks, stale content, contradictions, missing frontmatter. See a dashboard of what's been ingested vs what's pending.

• Automated cross-linking. After ingesting new pages, the cross-linker scans the vault for unlinked mentions and weaves them into the knowledge graph with [[wikilinks]]. No more orphan pages.

• Tag taxonomy. A controlled vocabulary of canonical tags stored in _meta/taxonomy.md, with a skill that audits and normalizes tags across your entire vault.

• Provenance tracking. Every claim on a wiki page is tagged: extracted (default), ^[inferred] (LLM synthesis), or ^[ambiguous] (sources disagree). A provenance: block in the frontmatter summarizes the mix per page, and wiki-lint flags pages that drift into mostly speculation. You can always tell what your wiki actually knows from what it guessed.

• Multimodal sources. Screenshots, whiteboard photos, slide captures, and diagrams ingest the same way as text — the agent transcribes any visible text verbatim and tags interpreted content as inferred. Requires a vision-capable model.

• Wiki insights. Beyond delta tracking, wiki-status can analyze the shape of your vault itself: top hubs, bridge pages (nodes whose removal would partition the graph), tag cluster cohesion scores, scored surprising connections, a graph delta since last run, and suggested questions the wiki structure is uniquely positioned to answer. Output goes to _insights.md.

• Graph export. wiki-export turns the vault's wikilink graph into graph.json (queryable), graph.graphml (Gephi/yEd), cypher.txt (Neo4j), and a self-contained graph.html interactive browser visualization — no server required.

• Tiered retrieval. wiki-query reads titles, tags, and page summaries first and only opens page bodies when the cheap pass can't answer. Say "quick answer" or "just scan" to force index-only mode. Keeps query cost roughly flat as your vault grows from 20 pages to 2000.

• QMD semantic search (optional). QMD is a local MCP server that indexes your wiki and source documents for fast semantic search. When QMD_WIKI_COLLECTION is set in .env, wiki-query runs a lex+vec pass against the collection before falling back to Grep — enabling concept-level matches that exact-string search misses. When QMD_PAPERS_COLLECTION is set, wiki-ingest queries your indexed sources before writing a new page, surfacing related work, detecting contradictions, and deciding whether to create or merge. Without QMD, both skills fall back to Grep/Glob and remain fully functional.

• _raw/ staging directory. Drop rough notes, clipboard pastes, or quick captures into _raw/ inside your vault. The next wiki-ingest run promotes them to proper wiki pages and removes the originals. Configured via OBSIDIAN_RAW_DIR in .env (defaults to _raw).

By default, wiki-ingest and wiki-query use Grep/Glob for search — fully functional, no extra setup. If your vault grows large or you want concept-level matches across your sources, you can plug in QMD: a local MCP server that runs lex+vec queries against indexed collections.

Setup:

1. Install QMD and add it to your MCP config (see the QMD repo for instructions).
2. Index your wiki and/or source documents:

   qmd index --name wiki /path/to/your/vault
   qmd index --name papers /path/to/your/sources

3. Set the collection names in your .env:

   QMD_WIKI_COLLECTION=wiki      # used by wiki-query
   QMD_PAPERS_COLLECTION=papers  # used by wiki-ingest (source discovery)

What changes with QMD enabled:

• wiki-query runs a semantic pass (lex+vec) against your wiki collection before falling back to Grep. Finds conceptually related pages even when the exact terms don't match.
• wiki-ingest queries your papers collection before writing a new page — surfaces related sources, spots contradictions, and decides whether to create a new page or merge into an existing one.

Both skills degrade gracefully: if QMD_WIKI_COLLECTION / QMD_PAPERS_COLLECTION are not set, they skip the QMD step silently and use Grep instead.

_raw/ is a staging area inside your vault for unprocessed captures — rough notes, clipboard pastes, quick voice-memo transcripts. Drop files there and the next wiki-ingest run will promote them to proper wiki pages and remove the originals.

The directory is created automatically by wiki-setup. The path is configurable via OBSIDIAN_RAW_DIR in .env (defaults to _raw).

Everything lives in .skills/. Each skill is a markdown file the agent reads when triggered:

Note: Slash commands (/skill-name) work in Claude Code, Cursor, and Windsurf. In other agents, just describe what you want and the agent will find the right skill.

obsidian-wiki/
├── .skills/                          # ← Canonical skill definitions (source of truth)
│   ├── wiki-setup/SKILL.md
│   ├── wiki-ingest/SKILL.md
│   ├── claude-history-ingest/SKILL.md
│   ├── data-ingest/SKILL.md
│   ├── wiki-status/SKILL.md
│   ├── wiki-rebuild/SKILL.md
│   ├── wiki-query/SKILL.md
│   ├── wiki-lint/SKILL.md
│   ├── cross-linker/SKILL.md
│   ├── tag-taxonomy/SKILL.md
│   ├── wiki-update/SKILL.md
│   ├── llm-wiki/SKILL.md
│   ├── wiki-export/SKILL.md
│   └── skill-creator/SKILL.md
│
├── CLAUDE.md                         # Bootstrap → Claude Code / Kilocode
├── GEMINI.md                         # Bootstrap → Gemini / Antigravity
├── AGENTS.md                         # Bootstrap → Codex / OpenAI / Kilocode
├── .cursor/rules/obsidian-wiki.mdc   # Bootstrap → Cursor
├── .windsurf/rules/obsidian-wiki.md  # Bootstrap → Windsurf
├── .github/copilot-instructions.md   # Bootstrap → GitHub Copilot
│
├── .claude/skills/   → symlinks to .skills/*  (created by setup.sh)
├── .cursor/skills/   → symlinks to .skills/*  (created by setup.sh)
├── .windsurf/skills/ → symlinks to .skills/*  (created by setup.sh)
├── .agents/skills/   → symlinks to .skills/*  (created by setup.sh)
│
├── ~/.gemini/antigravity/skills/  → global symlinks (created by setup.sh)
├── ~/.codex/skills/               → global symlinks (created by setup.sh)
├── ~/.agents/skills/              → global symlinks (OpenClaw + AGENTS.md-aware agents)
│
├── setup.sh                          # One-command agent setup
├── .env.example                      # Configuration template
├── README.md                         # You are here
└── SETUP.md                          # Detailed setup guide

The whole point is that your wiki should stay up to date as you work across different codebases. You don't want to come back to the obsidian-wiki repo every time. So setup.sh installs two global skills that work from any project: wiki-update and wiki-query.

When you run bash setup.sh, two things happen:

1. It writes a config to ~/.obsidian-wiki/config with your vault path and the repo location. This is how the skills know where to read and write.
2. It symlinks wiki-update and wiki-query into ~/.claude/skills/ so they're available everywhere.
3. It symlinks all skills into ~/.gemini/antigravity/skills/ for global Gemini/Antigravity access.
4. It symlinks all skills into ~/.codex/skills/ for global Codex access.
5. It symlinks all skills into ~/.agents/skills/ — the discovery path used by OpenClaw and other AGENTS.md-aware agents.

After that, you're in some project, say ~/projects/my-cool-app, working with Claude. Two commands:

# You're working on some project
cd ~/projects/my-cool-app
claude

# Write to the wiki: distill what you've learned
> /wiki-update

# Read from the wiki: pull context about anything you've captured before
> /wiki-query what do I know about rate limiting?

/wiki-update reads your project, figures out what's worth keeping, and distills it into your Obsidian vault. Architecture decisions, patterns you discovered, key concepts, trade-offs you evaluated. It doesn't copy code or dump file listings. It distills the stuff you'd forget in 3 months. Next time you run it from the same project, it checks what changed since last sync (via git log) and only processes the delta.

/wiki-query goes the other direction. You're working on something and you want to know what your wiki says about a topic. Maybe you solved a similar problem 2 months ago in a different project and the answer is already in your vault. The agent searches the wiki, reads the relevant pages, and gives you a synthesized answer with citations.

Both skills follow the same Karpathy pattern as everything else. If a concept page already exists in the vault, it merges into it. Everything gets cross-linked with [[wikilinks]], tracked in .manifest.json, and logged.

This is early. The skills work but there's a lot of room to make them smarter — better cross-referencing, smarter deduplication, handling larger vaults, new ingest sources. If you've been thinking about this problem or have a workflow that could be a skill, PRs are welcome.

1. Create a folder in .skills/your-skill-name/
2. Add a SKILL.md with YAML frontmatter (name, description) and markdown instructions
3. Run bash setup.sh to symlink into all agent directories
4. Test with your agent by saying something that matches the description

See .skills/skill-creator/SKILL.md for the full guide on writing effective skills.