Skip to content

1.14 Obsidian Vault Guide

Jump to bottom
Frédéric Clavert edited this page May 17, 2026 · 10 revisions

Obsidian Vault Guide

New in v1.0.0-rc.2. ClioDeck can point at an Obsidian vault folder, index the notes inside it, and treat them as a first-class RAG source alongside your PDFs (secondary) and Tropy archives (primary).

This integration was absorbed from the ClioBrain project during the RC2 fusion.

What you get

  • Indexing. ClioDeck walks the vault, parses markdown notes (frontmatter, wikilinks, tags), chunks them and stores embeddings in .cliodeck/obsidian-vectors.db.
  • Retrieval. Every Brainstorm turn pulls notes from the vault into its retrieval system prompt, with a citation back to the note path. The retrieval scope toggles in the chat panel let you mix biblio + primary + notes in any combination.
  • MCP exposure. The vault is queryable from external MCP clients via the search_obsidian tool on ClioDeck's MCP server (BM25 / FTS5).
  • Partial-success reporting. Indexing is never binary: the index report shows indexed / skipped / failed counts.

The vault is read-only from ClioDeck's point of view. Notes are not modified; nothing is written back to your .md files.

Linking a vault

Settings → Obsidian Vault (VaultConfigSection):

  1. Click Link vault.
  2. Pick the vault folder — that's the folder Obsidian itself opens (the one containing the .obsidian/ directory, not a subfolder).
  3. The path appears in the status block.
  4. Click Index to start the first build.

The index is per-project. If you switch ClioDeck projects, the vault link doesn't follow — each project decides whether it wants a vault and which one.

Indexing

  • Index — incremental: only notes that changed since the last run are reprocessed.
  • Reindex — forces a full rebuild. Use it after you change embedding model in Settings → LLM, or if you suspect drift.
  • Unlink — drops the link to the vault folder; the index file (.cliodeck/obsidian-vectors.db) is left in place. Re-linking the same folder reuses the index.

While indexing runs, the section shows live progress (<stage> — <processed>/<total>). When it finishes:

✓ Indexed: 412 · Skipped: 7 · Failed: 0

The Skipped count includes notes the parser intentionally left out (empty notes, frontmatter-only files, binary files masquerading as .md, etc.). Failed is for I/O or parse errors — investigate those.

Using the vault in Brainstorm

In the Brainstorm chat panel, the source-type toggles control which retrievers run:

Toggle combination Effect
Biblio only Secondary sources (PDFs) only.
Primary only Tropy archives only.
Notes only Vault only.
Biblio + notes PDFs + vault.
Primary + notes Tropy + vault.
All three PDFs + Tropy + vault (the default).

Vault chunks come into the prompt with type : note and the relative path (e.g. Reading notes/Hobsbawm-1962.md) as the TITLE field. Clicking a note citation in the assistant's reply opens it via the configured sources:open-note handler (typically the system's default markdown app — Obsidian itself, if it's registered).

Using the vault from external MCP clients

If you've enabled ClioDeck's MCP server (see the MCP Integration Guide), the vault is reachable from Claude Desktop / Claude Code as the search_obsidian tool:

search_obsidian(query: string, topK?: int = 10)

The search is BM25 over FTS5, returning the top-K matching notes with a short snippet. It does not use dense embeddings — that's only for in-app Brainstorm retrieval.

What's indexed, what isn't

The parser handles:

  • Standard markdown body.
  • YAML frontmatter (used for metadata; not embedded as content).
  • [[wikilinks]] and #tags (preserved in the text; useful as anchors).
  • ![[embeds]] (the link itself is preserved; the embed is not followed).

The parser ignores:

  • Files outside the vault root.
  • The .obsidian/ directory.
  • Non-.md files (images, PDFs inside the vault, etc.). For PDFs you keep in your vault, add them to ClioDeck's bibliography to index them as secondary sources.
  • Notes flagged with a known-skippable frontmatter field (project-specific; check the indexer logs in DevTools if a note isn't showing up).

Storage and migration

The vault index is stored in .cliodeck/obsidian-vectors.db at the project root (flat layout, not nested under v2/). It sits alongside the other workspace databases (vectors.db for PDFs, primary-sources.db for Tropy). On project load, ClioDeck auto-migrates older nested layouts (.cliodeck/v2/*) to the flat scheme via migrateWorkspaceToFlat.

The index is purely derived data — you can delete obsidian-vectors.db at any time and rebuild from Settings → Obsidian Vault → Reindex.

See also

Clone this wiki locally