Obsidian Reader

Read notes from an Obsidian vault so the agent can answer questions about, summarize, search, or reuse the user's personal knowledge base. The bundled script handles vault resolution, note lookup, full-vault search, frontmatter extraction, and conversion of Obsidian-specific syntax into LLM-friendly text.

When to use

• The user says "in Obsidian", "my vault", "my notes", or names a note like "open the Project Alpha note".
• The user wants to search personal notes ("do I have anything about X?"), summarize a note, or pull note content into a reply.
• Do NOT use for writing/syncing back to Obsidian — this skill is read-only. (For bidirectional sync see the obsidian-ontology-sync skill.)

Setup (one-time)

Point at a vault. Recommended: set the OBSIDIAN_VAULT environment variable to the vault root (the folder containing .obsidian). Otherwise pass --vault <path> to any command. If neither is set, common locations are auto-detected. Confirm with:

python scripts/obsidian_reader.py vault

Full command reference (including --plain, --include-frontmatter, search flags): see references/usage.md.

Workflow

1. Confirm the vault — run vault (or just attempt a read; if it errors, ask the user for the vault path and suggest setting OBSIDIAN_VAULT).
2. Locate the note — read "Note Title" (fuzzy by filename) or read "Folder/Note" (vault-relative path). If unsure of the name, list or search --name.
3. Read / normalize — default output rewrites [[Wiki]] links to standard Markdown and keeps tags. Use --plain for distraction-free text, --include-frontmatter to also see YAML metadata.
4. Search the vault — search "<regex>" to find content across all notes; --name to match filenames; --max N to cap results.
5. Act on the content — summarize, answer, or fold into the user's request.

Command cheatsheet

python scripts/obsidian_reader.py vault                         # print vault path
python scripts/obsidian_reader.py read "Note Title"              # read a note
python scripts/obsidian_reader.py read "Note Title" --plain      # plain text
python scripts/obsidian_reader.py read "Note Title" --include-frontmatter
python scripts/obsidian_reader.py search "keyword" --ignore-case --max 20
python scripts/obsidian_reader.py search "Daily" --name          # match filenames
python scripts/obsidian_reader.py list Projects                  # list a folder
python scripts/obsidian_reader.py frontmatter "Note Title"       # metadata as JSON

Add --vault <path> to any command when OBSIDIAN_VAULT is not set.

Output conventions

• read prepends a <!-- source: path.md --> comment so provenance is clear.
• Wikilinks [[A]] / [[A|alias]] / [[A#H]] become [alias](A.md#h).
• Embeds ![[Note]] become links; ![[img.png]] become image links (dropped in --plain); ![[img.png]] keeps the filename.
• Tags (#tag) are preserved in normal output, degraded to bare words in --plain.

Notes / limits

• Read-only: never modifies vault files.
• Note-title resolution matches on filename only and returns the first hit; for ambiguous titles, use the full vault-relative path.
• Frontmatter parsing is a dependency-free YAML subset (scalars, quoted values, simple lists). For deeply nested YAML, install PyYAML and parse the raw block.