TurboVault

The ultimate Rust SDK and high-performance MCP server for Obsidian-flavored Markdown (.ofm) and standard .md vaults.

TurboVault is a dual-purpose toolkit designed for both developers and users. It provides a robust, modular Rust SDK for building applications that consume markdown directories, and a full-featured MCP server that works out of the box with Claude and other AI agents.

Two Ways to Use TurboVault

1. As a Rust SDK (For Developers)

Build your own applications, search engines, or custom MCP servers using our modular crates. TurboVault handles the heavy lifting of parsing `.md` and `.ofm` files, building knowledge graphs, and managing multi-vault environments.

• Modular Architecture: Use only what you need (Parser, Graph, Search, etc.).
• High Performance: Sub-100ms operations for most tasks.
• Extensible: Easily build your own specialized MCP servers on top of our core logic.
• SOTA Standards: Fully supports Obsidian-flavored Markdown (wikilinks, embeds, callouts).

2. As a Ready-to-Use MCP Server (For Users)

Transform your Obsidian vault into an intelligent knowledge system immediately. Connect TurboVault to Claude Desktop or any MCP-compatible client to gain 74 specialized tools for your notes.

• Zero Coding Required: Install the binary and point it at your vault.
• 74 Specialized Tools: Searching, link analysis, atomic Git-backed writes, SQL frontmatter queries, health checks, and more.
• Multi-Vault Support: Switch between personal and work notes seamlessly at runtime.

Core Crates (The SDK)

TurboVault is a modular system composed of specialized crates. You can depend on individual components to build your own tools:

Why TurboVault?

Unlike basic note readers, TurboVault understands your vault's knowledge structure:

• Full-text search across all notes with BM25 ranking
• Link graph analysis to discover relationships, hubs, orphans, and cycles
• Vault intelligence with health scoring and automated recommendations
• Validated operation batches for fewer round trips and fail-fast execution
• Multi-vault support with instant context switching
• Runtime vault addition — no vault required at startup, add them as needed

Powered by TurboMCP

TurboVault is built on **TurboMCP**, a Rust framework for building production-grade MCP servers. TurboMCP provides:

• Type-safe tool definitions — Macro-driven MCP tool implementation
• Standardized request/response handling — Consistent envelope format
• Transport abstraction — HTTP, WebSocket, TCP, Unix sockets (configurable features)
• Middleware support — Logging, metrics, error handling
• Zero-copy streaming — Efficient large payload handling

This means TurboVault gets battle-tested reliability and extensibility out of the box. Want to add custom tools? TurboMCP's ergonomic macros make it straightforward.

Quick Start

Installation

From crates.io

# Minimal install (7.0 MB, STDIO only - perfect for Claude Desktop)
cargo install turbovault

# With HTTP server (~8.2 MB)
cargo install turbovault --features http

# With all cross-platform transports (~8.8 MB)
# Includes: STDIO, HTTP, WebSocket, TCP (Unix sockets only on Unix/macOS/Linux)
cargo install turbovault --features full

# With SQL frontmatter queries (adds GlueSQL-powered query_frontmatter_sql tool)
cargo install turbovault --features sql

# Binary installed to: ~/.cargo/bin/turbovault

From source:

git clone https://github.com/epistates/turbovault.git
cd turbovault
make release
# Binary: ./target/release/turbovault

Option 1: Static Vault (Recommended for Single Vault)

turbovault --vault /path/to/your/vault --profile production

Then add to `~/.config/claude/claude_desktop_config.json`:

{
  "mcpServers": {
    "turbovault": {
      "command": "/path/to/turbovault",
      "args": ["--vault", "/path/to/your/vault", "--profile", "production"]
    }
  }
}

Option 2: Runtime Vault Addition (Recommended for Multiple Vaults)

Start the server without a vault:

turbovault --profile production

Then add vaults dynamically:

{
  "mcpServers": {
    "turbovault": {
      "command": "/path/to/turbovault",
      "args": ["--profile", "production"]
    }
  }
}

Once connected to Claude:

You: "Add my vault at ~/Documents/Notes"
Claude: [Calls add_vault("personal", "~/Documents/Notes")]

You: "Search for machine learning notes"
Claude: [Uses search() across the indexed vault]

You: "What are my most important notes?"
Claude: [Uses get_hub_notes() to find key concepts]

Atomic Git-Backed Writes

For vaults already managed by Git, enable the transactional backend in the

TurboVault YAML config:

vaults:
  - name: personal
    path: ~/Documents/Notes
    is_default: true
    write_backend: git
    git:
      include_ignored: false
      require_commit_message: false

Start with `turbovault --config ~/.turbovault/config.yaml`. Every mutation is

then a Git commit. Multi-operation batches build one isolated tree and advance

the branch with compare-and-swap, so a stale path aborts the entire batch and

concurrent TurboVault processes cannot interleave commit/materialization. The

backend also refuses to overwrite dirty or untracked touched paths and refuses

to reset an index containing staged changes.

What Can Claude Do?

Search & Discovery

You: "Find all notes about async Rust and show how they connect"
Claude: search() -> recommend_related() -> get_related_notes() -> explain relationships

Vault Intelligence

You: "What's the health of my vault? Any issues I should fix?"
Claude: quick_health_check() -> full_health_analysis() -> get_broken_links() -> generate fixes

Knowledge Graph Navigation

You: "What are my most important notes? Which ones are isolated?"
Claude: get_hub_notes() -> get_isolated_clusters() -> suggest connections

Structured Note Creation

You: "Create a project note for the TurboVault launch with status tracking"
Claude: list_templates() -> create_from_template() -> write auto-formatted note

Batch Content Operations

You: "Move my 'MLOps' note to 'AI/Operations' and identify links to update"
Claude: get_backlinks() -> move_note() -> edit_note() for each affected reference

Link Suggestions

You: "Based on my vault, what notes should I link this to?"
Claude: suggest_links() -> get_link_strength() -> recommend cross-references

74 MCP Tools Organized by Category

File Operations & Batch (8)

• `read_note` — Get note content with hash for conflict detection
• `write_note` — Create/overwrite notes (auto-creates directories)
• `edit_note` — Surgical edits via SEARCH/REPLACE blocks
• `delete_note` — Safe deletion with link tracking
• `move_note` — Rename/relocate a note; Git-backed vaults atomically rewrite incoming wikilinks
• `move_file` — Move/rename non-note files (e.g. attachments, images)
• `get_notes_info` — Metadata for multiple notes in a single call
• `batch_execute` — One all-or-nothing commit with `write_backend: git`; direct stays sequential

Git Fanout (4)

• `begin_fanout` — Open an isolated worktree for parallel agent writes
• `commit_fanout` — Merge an active fanout back into its base vault
• `abandon_fanout` — Discard a fanout without changing the base vault
• `list_orphan_fanouts` — Diagnose worktrees left by interrupted sessions

Metadata & Tags (3)

• `update_frontmatter` — Patch frontmatter fields (merge or replace)
• `get_metadata_value` — Extract frontmatter values (dot notation support)
• `manage_tags` — Add, remove, or list note tags

Link Analysis (6)

• `get_backlinks` — All notes that link TO this note
• `get_forward_links` — All notes this note links TO
• `get_related_notes` — Multi-hop graph traversal (find non-obvious connections)
• `get_hub_notes` — Top 10 most connected notes (key concepts)
• `get_dead_end_notes` — Notes with incoming but no outgoing links
• `get_isolated_clusters` — Disconnected subgraphs in your vault

Graph Metrics & Suggestions (3)

• `suggest_links` — AI-powered link suggestions for a note
• `get_link_strength` — Connection strength between notes (0.0–1.0)
• `get_centrality_ranking` — Graph centrality metrics (betweenness, closeness, eigenvector)

Search (8)

• `search` — BM25-ranked search across all notes ( anyhow::Result {

// 1. Initialize the MultiVault manager

let manager = MultiVaultManager::new();

// 2. Add and initialize a vault (scans files, builds graph)

manager.add_vault("notes", "/home/user/notes").await?;

// 3. Perform high-level operations

let vault = manager.get_vault("notes")?;

let results = vault.search("machine learning")?;

// 4. Use these components to build your own custom MCP server

// or integrate into existing Rust applications.

Ok(())

}

Each crate is published to crates.io, so you can depend on individual components or the full stack.

## Architecture

Built as a modular Rust workspace:

turbovault-core — Core types, MultiVaultManager, configuration

turbovault-parser — OFM (Obsidian Flavored Markdown) parsing

turbovault-graph — Link graph analysis with petgraph

turbovault-vault — Vault operations, file I/O, atomic writes

turbovault-batch — Validated sequential batch operations

turbovault-export — JSON/CSV/Markdown export

turbovault-sql — SQL frontmatter queries (GlueSQL, feature-gated)

turbovault-tools — 74 MCP tool implementations

turbovault-plugin-api — Curated plugin facade, provider contract, event hooks

turbovault (binary) — CLI and MCP server entry point

All crates are published to [crates.io](https://crates.io/crates/turbovault-core) for public use.

## Obsidian Flavored Markdown (OFM) Support

TurboVault fully understands Obsidian's syntax:

- **Wikilinks**: `[[note]]`, `[[note|alias]]`, `[[note#section]]`, `[[note#^block]]`
- **Embeds**: `![[image.png]]`, `![[note]]`, `![[note#section]]`
- **Tags**: `#tag`, `#parent/child/tag`
- **Tasks**: `- [ ] Task`, `- [x] Done`
- **Callouts**: `> [!type] Title`
- **Frontmatter**: YAML metadata with automatic parsing
- **Headings**: Hierarchical structure extraction

## Security

- **Path traversal protection** — No access outside vault boundaries
- **Type-safe deserialization** — Rust's type system prevents injection
- **Atomic writes** — Temp file → atomic rename (never corrupts on failure)
- **Hash-based conflict detection** — `edit_note` detects concurrent modifications
- **File size limits** — Default 10MB per file (configurable), enforced on reads and writes
- **Protected directories** — `.obsidian/`, `.git/`, `node_modules/`, and TurboVault's own `.turbovault/` state are unreachable through the note APIs on both write backends
- **No shell execution** — Zero command injection risk
- **Security auditing** — Detailed logs in production mode

## System Requirements

- **Rust**: 1.90.0 or later
- **OS**: Linux, macOS, Windows
- **Memory**: 100MB base + ~80MB per 10k notes
- **Disk**: Negligible (index is in-memory)

## Building from Source

git clone https://github.com/epistates/turbovault.git

cd turbovault

Development build

cargo build

Production build (optimized)

cargo build --release

Run tests

cargo test --all

Or use the Makefile:

make build # Debug build

make release # Production build

make test # Run tests

make clean # Clean build artifacts

## Documentation

[Docs](./docs/README.md)

## Examples

### Example 1: Search-Driven Organization

You: "What topics do I have the most notes on?"

Claude:

1. get_hub_notes() -> [AI, Project Management, Rust, Python]

2. For each hub:

3. Report: "Your core topics are AI (23 notes) and Rust (18 notes)"

### Example 2: Vault Health Improvement

You: "My vault feels disorganized. Help me improve it."

Claude:

1. quick_health_check() -> Health: 42/100

2. full_health_analysis() -> Issues: 12 broken links, 8 orphaned notes

3. get_broken_links() -> List of specific broken links

4. suggest_links() -> AI-powered link recommendations

5. Apply fixes individually, or use batch_execute() after reviewing its fail-fast semantics

6. explain_vault() -> New health: 78/100

### Example 3: Template-Based Content Creation

You: "Create project notes for Q4 initiatives"

Claude:

1. list_templates() -> "project", "task", "meeting"

2. create_from_template("project", {

"title": "Q4 Planning",

"status": "In Progress",

"deadline": "2024-12-31"

})

3. Creates structured note with auto-formatting

4. Returns path for follow-up edits

## Benchmarks

M1 MacBook Pro, 10k notes, production build:

- **File read**: <10ms
- **File write**: <20ms
- **Simple search**: <50ms
- **Graph analysis**: <200ms
- **Vault initialization**: ~500ms
- **Memory usage**: ~80MB
- **External-change reconciliation**: ~19ms per pass, at most once per 500ms

## Keeping up with edits you did not make

A vault is a shared directory. Obsidian is usually open on it, and an editor, a
`git pull`, or a sync client may touch it while TurboVault is running. Search,
the link graph, similarity, and vault stats are all derived from the notes, so
none of that would reach them on its own.

Before serving any of those, TurboVault compares a `(size, mtime)` scan against
what it last recorded and applies whatever moved. Comparing state cannot miss a
change the way filesystem notifications can, which matters most on exactly the
setups where notifications are weakest: network shares, and iCloud, Dropbox, or
Syncthing vaults, none of which report a peer's edits at all.

The pass is debounced, so a burst of tool calls costs one scan and an idle
server costs nothing. Worst-case staleness is the interval, at least 500ms and
scaled up only on a vault large enough to need it. Set
`reconcile_external_changes: false` to turn it off for a vault nothing else
writes.

## Roadmap

- [ ] Cross-vault link resolution
- [ ] Encrypted vault support
- [ ] Collaborative locking
- [ ] WebSocket transport (beyond MCP stdio)

## Contributing

Contributions welcome! Please ensure:

- All tests pass: `cargo test --all`
- Code formats: `cargo fmt --all`
- No clippy warnings: `cargo clippy --all -- -D warnings`

## License

MIT License - See [LICENSE](LICENSE) for details

## Links

- **Repository**: https://github.com/epistates/turbovault
- **Issues**: https://github.com/epistates/turbovault/issues
- **MCP Protocol**: https://modelcontextprotocol.io
- **Obsidian**: https://obsidian.md
- **Related**: [TurboMCP](https://github.com/epistates/turbomcp)

---

**Get started now**: `./target/release/turbovault --profile production`