# Vault Query

> Search a local Markdown / Obsidian 'second brain' vault via an MCP filesystem server, with freshness and search-scope gotchas handled. Use when the user asks about their notes, knowledge base, documented decisions, references, or 'what do I know about X?'

- Skill: `quietdaemon/vault-query` (Agent Skill)
- Install (CLI): `npx skillmds@latest add quietdaemon/vault-query`
- Raw SKILL.md: https://api.skillmd.com/api/skills/quietdaemon/vault-query/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: quietdaemon (https://skillmd.com/u/quietdaemon)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/quietdaemon/vault-query

---


# Vault Query

Give your assistant read access to a personal Markdown vault (Obsidian or plain
`.md` files) through an MCP filesystem server, and let it actually *find and
surface* what's in there. The hard-won part isn't the search call — it's the
two failure modes below that make searches silently come back empty.

## Setup

Run an MCP filesystem server scoped to your vault, e.g.:

```yaml
# in your agent's MCP config
vault_filesystem:
  command: npx
  args: ["-y", "@modelcontextprotocol/server-filesystem", "<VAULT_PATH>"]
```

This exposes `mcp_vault_filesystem_*` tools (read/search/list). If your vault is
a git clone kept fresh by a pull cron, see Step 0.

## When to activate

The user asks about:
- Their notes, wiki, or anything they've documented
- Concepts, frameworks, protocols, references, sources
- People, places, or entities they track
- Their decision log, action items, priorities
- "What do I know about X?" / "Pull up my notes on Y"

## How to query

### Step 0 — Check freshness FIRST (if the vault is a git clone)

If the user writes to the vault from other machines, your local copy is only as
fresh as the last pull. **Before concluding something isn't there:**

```bash
cd <VAULT_PATH> && git fetch origin && git log --oneline origin/main -5
```

If `origin/main` is ahead, pull before searching:

```bash
git pull --rebase origin main
```

This is the single most common cause of a false "I couldn't find it."

### Step 1 — Locate files

`mcp_vault_filesystem_search_files` with a glob `pattern` (e.g. `*labs*`) and the
vault `path`. ⚠️ **This matches FILENAMES, not file contents.**

### Step 2 — Content search fallback

When the term lives *inside* a page (not in its filename), glob search misses it.
Use grep:

```bash
grep -ril "keyword" <VAULT_PATH>/
```

### Step 3 — Read + answer

`mcp_vault_filesystem_read_file` on the 2–3 most relevant hits, then answer in
your own words from the content.

**Always surface the actual findings.** Deliver the specific entries / values /
dates / names — don't just say "I found it." A lookup the user never sees the
result of is worthless.

## Pitfalls (the reason this skill exists)

- **Stale cache is the #1 false-empty.** Run the Step 0 `git fetch` *every* time
  the vault is a synced clone, not only when something looks missing.
- **MCP glob search ≠ content search.** `search_files` matches filename patterns
  only. For words inside files, use `grep -ril`.
- **Filesystem search is case-sensitive on Linux.** `*Protocols*` and `*protocols*`
  can return different results — prefer lowercase unless you know the casing.
- **Don't over-read.** On a broad hit, read the top 2–3 files, not everything.
- **Mind privacy scope.** Only point the MCP server at directories you intend the
  assistant to read; it can read everything in scope.