vaultdb

Markdown vaults, queryable everywhere you want to use them. vaultdb is a Rust library for treating folders of .md files with YAML frontmatter as a queryable database, plus the frontends that sit on it: a CLI (vaultdb), an MCP server for LLM agents (vaultdb-mcp), and a stable library API (vaultdb-core) that any markdown-vault tool can build on.

The thesis: a markdown vault is both a relational table (frontmatter is rows × columns) and a graph ([[wikilinks]] are edges). vaultdb's query AST treats both as first-class — you filter records by frontmatter, by graph predicates ("links to anything tagged X"), or by any combination.

use vaultdb_core::{Expr, Predicate, Query, Value, Vault};

let vault = Vault::discover(std::path::Path::new("."))?;
let records = vault.query(&Query {
    folder: "notes".into(),
    filter: Some(Expr::Predicate(Predicate::Equals {
        field: "status".into(),
        value: Value::String("active".into()),
    })),
    select: None,
    sort: None,
    limit: Some(10),
    recursive: false,
})?;

Or from the CLI:

$ vaultdb query 3-Notes --where "tags contains topic/ai" --select "_name,_backlink_count" --sort _backlink_count --desc --limit 5

+-----------------------------+-----------------+
| _name                       | _backlink_count |
+==============================================+
| BERT                        | 43              |
| Machine Learning            | 39              |
| Transformer Architecture    | 38              |
| Natural Language Processing | 35              |
| Deep Learning               | 29              |
+-----------------------------+-----------------+

What it does

Treats folders of .md files as database tables
YAML frontmatter fields are queryable columns
[[wiki-links]] form a citation graph with backlink tracking
Supports relational joins across the link graph
Graph traversal (BFS) with depth limits and filtering
Bulk mutations (set fields, add/remove tags) with --dry-run safety
Rename with automatic wiki-link updates across the vault
Schema inference and validation
Library + CLI + MCP server in one workspace — pick whichever fits

No daemon, no cache, no state files. Every command reads the current .md files directly. Edit in Obsidian, query with vaultdb — they coexist without conflict.

Workspace

Crate	What it is	Use for
`vaultdb-core`	Library: parse, query, link graph, mutation builders	Building a markdown-vault tool in Rust
`vaultdb`	CLI binary (this is what `cargo install vaultdb` ships)	Command-line use over an existing vault
`vaultdb-mcp`	Model Context Protocol server (stdio)	Letting LLM agents (Claude, Cursor, etc.) query a vault

See ARCHITECTURE.md for the design rules these frontends follow (library scope discipline, state boundaries, public API contract).

Install

# From crates.io
cargo install vaultdb

# Or from source
git clone https://github.com/rusenbb/vaultdb.git
cd vaultdb
cargo install --path .

Requires Rust 1.75+. Published at https://crates.io/crates/vaultdb.

Quick start

# Auto-detects vault root by finding .obsidian/ directory
cd ~/Documents/my-vault

# Or specify explicitly
vaultdb --vault ~/Documents/my-vault query 3-Notes ...

Data model

Folder             =  Database / Table
.md file           =  Record / Row
Frontmatter fields =  Columns
[[wiki-links]]     =  Relations / Edges

Every record automatically has virtual fields:

Field	Description
`_name`	Filename without `.md`
`_path`	Relative path from vault root
`_folder`	Parent folder name
`_modified`	File modification time
`_created`	File creation time
`_links`	Outgoing wiki-link targets
`_link_count`	Number of outgoing links
`_backlinks`	Notes that link to this note
`_backlink_count`	Number of incoming links
`_body`	The full body text (everything after the closing `---` of the frontmatter) — use with `contains`, `matches`, etc. for body search
`_length`	Total file size in bytes
`_body_length`	Body length in bytes (excluding frontmatter)
`_body_links`	Markdown links `[label](url)` in the body, as `{label, url}` maps. Query element-wise with `matches`, e.g. `_body_links matches "example\.com"`

Commands

Query

# Basic query with filtering, sorting, limiting
vaultdb query 3-Notes --where "tags contains topic/movies" --select "_name,director,year" --sort year --desc --limit 10

# Multiple --where flags are AND-ed
vaultdb query 3-Notes --where "tags contains topic/chinese" --where "hsk = 1" --select "_name,pinyin,anlam"

# OR within a single --where using ||
vaultdb query 3-Notes --where "status = to-watch || status = to-read" --select "_name,status"

# NOT with ! prefix
vaultdb query 3-Notes --where "tags !contains topic/movies" --where "status exists"

# Output formats: table (default), json, csv, yaml
vaultdb query 3-Notes --where "tags contains topic/ai" --format json

Where expression syntax

FIELD = VALUE            # exact match
FIELD != VALUE           # not equal
FIELD > VALUE            # numeric/string comparison
FIELD < VALUE
FIELD >= VALUE
FIELD <= VALUE
FIELD contains VALUE     # list membership or substring
FIELD !contains VALUE    # negated
FIELD startswith VALUE
FIELD endswith VALUE
FIELD matches REGEX      # regex match
FIELD IN (a, b, c)       # SQL-style list membership
FIELD NOT IN (a, b, c)   # negated
FIELD IS NULL            # alias for `missing`
FIELD IS NOT NULL        # alias for `exists`
FIELD exists             # field is present and non-null
FIELD missing            # field is absent or null
FIELD !exists            # negated exists (same as missing)

Boolean composition inside a single --where:

# AND with && (SQL-conventional: binds tighter than ||)
--where "tags contains topic/ai && status = active"

# OR with ||
--where "status = active || status = pending"

# Mixed: AND binds tighter, so a || b && c parses as a || (b && c)
--where "status = draft || status = active && hsk = 1"

# Parenthesised grouping for explicit precedence
--where "(status = draft || status = active) && hsk = 1"

# Word-prefix NOT for negating a whole sub-expression
--where "NOT (status = archived || status = deleted)"

# Quoted string values for needles with spaces or special chars
--where 'title = "Two-word title"'
--where "status IN (\"in review\", \"needs follow-up\")"

Multiple --where flags are also AND-ed:

--where "status = active || status = pending" --where "tags contains topic/ai"

Body search

Use the _body virtual field to search inside note bodies (the text after the frontmatter):

# Find every note that mentions "Stanford" in its body
vaultdb query 3-Notes --where '_body contains "Stanford"'

# Combined with frontmatter filtering — runs through the streaming
# query path, so it's cheap on large vaults.
vaultdb query 3-Notes --where 'status = active && _body contains "machine learning"'

# Regex on the body
vaultdb query 3-Notes --where '_body matches "^# Conclusion"'

Body content is loaded only when a body predicate is referenced; queries that don't need it stay on the fast frontmatter-only path.

Export query results to a file

Use --output <vault-relative path> to save results into the vault. The format is inferred from the extension — .csv, .tsv, .json, .yaml/.yml, .xlsx are all supported. The path must stay inside the vault; absolute paths, .. escapes, and .md extensions are rejected.

# CSV (default delimiter is comma)
vaultdb query 3-Notes --where "tags contains topic/ai" --output exports/ai-notes.csv

# Semicolon-delimited CSV (European convention)
vaultdb query 3-Notes --output exports/ai.csv --csv-delimiter semicolon

# Tab-separated; .tsv extension also forces tab by default
vaultdb query 3-Notes --output exports/ai.tsv

# JSON / YAML
vaultdb query 3-Notes --where "tags contains topic/ai" --output exports/ai.json
vaultdb query 3-Notes --where "tags contains topic/ai" --output exports/ai.yaml

# XLSX — typed cells (numbers as numbers, booleans as booleans)
vaultdb query 3-Notes --where "tags contains topic/ai" --output exports/ai.xlsx

On filename collision the file is auto-suffixed (1), (2), ... — no overwrite mode by design. When --output is set, the resolved path is printed and stdout no longer carries the result body. The same renderer powers MCP's export parameter on every read tool (see below), so a CLI export and an MCP export of the same query produce byte-identical files.

Create

# Create a note from a template
vaultdb create 3-Notes --template "templates/Movie Notes.md" --name "Arrival" --set "director=Denis Villeneuve" --set "year=2016"

# Create without a template (minimal frontmatter)
vaultdb create 3-Notes --name "Computer Vision" --set "tags=type/concept"

# Batch create from unresolved links
vaultdb unresolved 3-Notes --from BERT --depth 2 | ... | while read name; do
  vaultdb create 3-Notes --template templates/concept.md --name "$name"
done

The --template path is relative to vault root. Any .md file works as a template — vaultdb reads it, applies --set overrides to frontmatter, and writes the result.

Count, Fields, Tags

# Count matching records
vaultdb count 3-Notes --where "tags contains topic/chinese"

# List all frontmatter fields with types and frequencies
vaultdb fields 3-Notes

# List all tags with usage counts
vaultdb tags 3-Notes

Graph: Links, Traverse, Unresolved

# Show outgoing and incoming links for a note
vaultdb links React

# Find the most referenced notes
vaultdb query 3-Notes --select "_name,_backlink_count" --sort _backlink_count --desc --limit 10

# Find orphan notes (no links in or out)
vaultdb query 3-Notes --where "_backlink_count = 0" --where "_link_count = 0"

# BFS traversal from a starting note
vaultdb traverse Microservices --depth 2
vaultdb traverse Database --depth 1 --direction incoming

# Filter traversal results
vaultdb traverse BERT --depth 2 --where "tags contains type/concept" --select "_backlink_count"

# Find [[wiki-links]] pointing to non-existent files
vaultdb unresolved 3-Notes

# Scoped to a neighborhood
vaultdb unresolved 3-Notes --from BERT --depth 3

# Verbose: show which notes reference each unresolved link
vaultdb unresolved 3-Notes -v

Relational joins

# Notes that link to React
vaultdb query 3-Notes --links-to React

# Notes that React links to
vaultdb query 3-Notes --linked-from React

# Notes linking to ANY note tagged topic/ai (the join)
vaultdb query 3-Notes --links-to-where "tags contains topic/ai" --select "_name,_backlink_count" --sort _backlink_count --desc

# Notes linked from any movie note
vaultdb query 3-Notes --linked-from-where "tags contains topic/movies" --where "tags contains type/concept"

# Notes linking to both React AND Node.js
vaultdb query 3-Notes --links-to React --links-to "Node.js" --select "_name"

Mutations

All write operations support --dry-run to preview changes without writing.

# Set a field
vaultdb update 3-Notes --where "_name = 1917" --set "status=watched" --dry-run

# Add/remove tags
vaultdb update 3-Notes --where "director contains Chaplin" --add-tag "director/charlie-chaplin" --dry-run

# Remove a field
vaultdb update 3-Notes --where "_name = React" --unset "deprecated" --dry-run

# Replace the body (bash ANSI-C quoting `$'...'` lets you embed real newlines)
vaultdb update 3-Notes --where "_name = React" --set-body $'# React\n\nRewritten.\n' --dry-run

# Append to the body (default separator: a single \n; override with --body-separator)
vaultdb update 5-Tasks --where "_name = 2026-05-28" --append-body "- [ ] follow up" --dry-run

# Append with a blank-line section break instead
vaultdb update 5-Tasks --where "_name = 2026-05-28" \
  --body-separator '\n\n' --append-body "## Notes" --dry-run

# Clear the body, keep the frontmatter
vaultdb update 3-Notes --where "_name = Scratch" --clear-body --dry-run

# Create a note with explicit body content
vaultdb create 5-Tasks --name "2026-05-28" --body $'## Today\n- [ ] write code\n'

# Move files
vaultdb move 5-Tasks --where "_name startswith 2026-02" --to 5-Tasks/archive --dry-run

# Delete (moves to .trash/ by default, --force for permanent)
vaultdb delete 3-Notes --where "_name = OldNote" --dry-run

# Rename with automatic wiki-link updates across the vault
vaultdb rename React "React.js" --folder 3-Notes --dry-run

Mutations require at least one --where condition to prevent accidental bulk changes.

Schema

# Infer a schema from existing data
vaultdb schema init 3-Notes

# Validate records against a schema file (vaultdb-schema.yaml)
vaultdb schema validate 3-Notes

# Show the current schema
vaultdb schema show 3-Notes

Performance

No caching, no indexing — reads files fresh on every command. Numbers below are best-of-3 from cargo run --release --example bench -- <N>, measured on an Intel i7-14700K desktop (full host details and methodology in BENCHMARKS.md):

Scale	Frontmatter query	Graph query	`link_graph(All)`
1 000 notes	5 ms	7 ms	6 ms
10 000 notes	59 ms	88 ms	70 ms
100 000 notes	651 ms	1 032 ms	819 ms

Scaling is roughly linear in vault size — 10× the records costs about 10–12× the time, with no superlinear cliff up through 100k. Every operation finishes in under 1.1 seconds at 100k notes.

Reproduce with:

cargo run --release -p vaultdb-core --example bench -- 10000

Two-parser architecture: serde_yaml for fast reads, line-by-line string manipulation for formatting-preserving writes.

Safety

--dry-run previews all mutations before writing
update, move, delete refuse to run without --where
delete warns about dangling wiki-links before proceeding
delete moves to .trash/ by default (with collision-safe naming)
rename auto-updates all [[wiki-links]] across the vault
Writer detects and refuses to modify flow-style YAML ([a, b]) or multiline scalars (|, >)
Files without frontmatter are loaded with empty fields (queryable by virtual fields, never silently skipped)

Library usage (vaultdb-core)

Add to your Cargo.toml:

[dependencies]
vaultdb-core = { git = "https://github.com/rusenbb/vaultdb" }

The full public surface lives at the crate root: Vault, Record, Value, Query, Expr, Predicate, LinkPredicate, LinkGraph, GraphScope, Direction, UpdateBuilder, DeleteBuilder, MoveBuilder, RenameBuilder, MutationReport, LoadResult, ParseError, VaultdbError. All public data types are Serialize/Deserialize-able.

use vaultdb_core::{
    Expr, LinkPredicate, Query, UpdateBuilder, Value, Vault,
};

let vault = Vault::discover(std::path::Path::new("/path/to/vault"))?;

// Records that link to anything tagged topic/ai
let q = Query {
    folder: "notes".into(),
    filter: Some(Expr::LinksTo(LinkPredicate::Where(Box::new(
        Expr::parse("tags contains topic/ai")?,
    )))),
    select: None,
    sort: None,
    limit: None,
    recursive: false,
};
let hits = vault.query(&q)?;

// Plan-only mutation: see what would change without writing
let filter = Expr::parse("status = draft")?;
let plan = UpdateBuilder::new("notes", filter)
    .set("status", Value::String("published".into()))
    .plan(&vault)?;
for change in &plan.changes {
    println!("{}: {}", change.path.display(), change.description);
}

Every mutation builder exposes a plan(&vault) and an execute(self, &vault). plan is read-only; execute runs the same computation and writes the result. The CLI's --dry-run flag is just plan() + render.

MCP server (vaultdb-mcp)

vaultdb-mcp exposes the library as a Model Context Protocol server over stdio, so Claude, Cursor, and other MCP-aware clients can query and reason about a vault.

cargo install --path crates/vaultdb-mcp

Wire it into Claude Desktop's config (~/.config/claude/claude_desktop_config.json on Linux, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "vaultdb": {
      "command": "vaultdb-mcp",
      "args": ["--vault", "/absolute/path/to/your/vault"]
    }
  }
}

Tools exposed:

Read — query, find_by_name, list_folders, links, traverse, unresolved. Every read tool also accepts export: "<vault-relative path>" and csv_delimiter: "comma" | "semicolon" | "tab" — when export is set, the result is also written to a file under the vault (same path-safety rules as the CLI's --output) and the response is wrapped as { "data": <result>, "exported_to": "<path>" }. When export is unset, the response shape is unchanged.

Schema — schema_show, schema_infer. Both also accept export — use .json or .yaml for these since the schema shape isn't tabular.

Plan-only mutation (preview, never writes) — plan_create, plan_update, plan_delete, plan_move, plan_rename. Default flow: agents propose, you approve, hosts execute.

Execute — execute_create, execute_update, execute_move, execute_rename, execute_delete. Disabled by default. Enable per-capability via launch flags:

--dangerously-allow-create
--dangerously-allow-update       (covers update + move + rename)
--dangerously-allow-delete       (soft-delete to .trash/)
--dangerously-allow-permanent-delete   (required in addition to -delete)

Every successful execute call appends a line to <vault>/.vaultdb/audit.log with the timestamp, tool name, params, and change count. The default mode (no flags) preserves the "propose, approve, execute via a separate path" pattern; opt-in flags shift execution to the agent for sessions where that's the desired ergonomics.

Claude Code integration

vaultdb ships with a Claude Code skill so LLM agents can use it directly. To install:

# Copy the skill to your personal skills directory
mkdir -p ~/.claude/skills/vaultdb
cp skills/vaultdb/SKILL.md ~/.claude/skills/vaultdb/SKILL.md

Then in any Claude Code session, the agent can invoke /vaultdb or use it automatically when you ask about your vault.

Not Obsidian-specific

Despite being designed for Obsidian vaults, vaultdb works with any folder of .md files with YAML frontmatter. Hugo, Jekyll, Astro, Zola, or any static site generator's content directory is a valid target.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 96 Commits
.claude-plugin		.claude-plugin
.github/workflows		.github/workflows
bindings		bindings
crates		crates
docs		docs
skills/vaultdb		skills/vaultdb
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
BENCHMARKS.md		BENCHMARKS.md
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
RELEASE.md		RELEASE.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

vaultdb

What it does

Workspace

Install

Quick start

Data model

Commands

Query

Where expression syntax

Body search

Export query results to a file

Create

Count, Fields, Tags

Graph: Links, Traverse, Unresolved

Relational joins

Mutations

Schema

Performance

Safety

Library usage (vaultdb-core)

MCP server (vaultdb-mcp)

Claude Code integration

Not Obsidian-specific

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

vaultdb

What it does

Workspace

Install

Quick start

Data model

Commands

Query

Where expression syntax

Body search

Export query results to a file

Create

Count, Fields, Tags

Graph: Links, Traverse, Unresolved

Relational joins

Mutations

Schema

Performance

Safety

Library usage (vaultdb-core)

MCP server (vaultdb-mcp)

Claude Code integration

Not Obsidian-specific

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages