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:

Crate	Purpose	Docs
turbovault-core	Core models, MultiVault management & types
turbovault-parser	High-speed .md & .ofm parser
turbovault-graph	Link graph analysis & relationship discovery
turbovault-vault	Vault management, file I/O & atomic writes
turbovault-tools	74 MCP tool implementations
turbovault-plugin-api	Stable facade, provider contract & bounded hooks for compiled-in plugins
turbovault-sql	SQL frontmatter queries (GlueSQL)
turbovault-batch	Validated fail-fast operation batches
turbovault-export	Export & reporting (JSON/CSV/MD)
turbovault	Main MCP server binary / SDK orchestrator

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 (<500ms on 100k notes)
advanced_search — Search with tag, frontmatter, path, and limit filters
search_by_frontmatter — Find notes by frontmatter key-value pair
recommend_related — ML-powered recommendations based on content similarity
find_notes_from_template — Find all notes using a specific template
query_metadata — Frontmatter pattern queries
inspect_frontmatter — Schema inspection for SQL queries (feature: sql)
query_frontmatter_sql — Arbitrary SQL against frontmatter via GlueSQL (feature: sql)

Semantic & Similarity (5)

semantic_search — TF-IDF semantic search with similarity scores and shared terms
find_similar_notes — Content-similar notes to a given note
find_duplicates — Near-duplicate detection (SimHash filter + TF-IDF verify)
compare_notes — Similarity score, shared vocabulary, diff, and merge recommendation
diff_notes — Unified diff between two notes

Vault Health & Quality (10)

quick_health_check — Fast 0-100 health score (<100ms)
full_health_analysis — Comprehensive vault audit with recommendations
get_broken_links — All links pointing to non-existent notes
detect_cycles — Circular reference chains (sometimes intentional)
explain_vault — Holistic overview replacing 5+ separate calls
evaluate_note_quality — Per-note quality score with improvement recommendations
vault_quality_report — Vault-wide quality assessment (worst-N notes)
find_stale_notes — Notes not modified within a threshold of days
analyze_note_grounding — Grounding primitives for a note (claims, citations, uncited flag) to feed an external LLM judge
find_ungrounded_notes — Find hallucination-risk notes that make claims but cite no source

Open Knowledge Format (4)

okf_validate — Validate the vault as an OKF v0.1 bundle (conformance + concept type vocabulary); usable as a CI/pre-publish gate
generate_index — Generate/refresh index.md files for progressive disclosure (idempotent)
append_log_entry — Append a dated entry to a directory's log.md update history (§7)
visualize — Render the concept graph as a shareable, self-contained HTML file (force-directed graph + rendered notes + backlinks)

Templates & OFM (6)

list_templates — Discover available templates
get_template — Template details and required fields
create_from_template — Render and write templated notes
get_ofm_syntax_guide — Focused Obsidian Flavored Markdown reference
get_ofm_quick_ref — Quick OFM cheat sheet
get_ofm_examples — See all Obsidian Flavored Markdown features

Vault Lifecycle (8)

create_vault — Programmatically create a new vault
add_vault — Register and auto-initialize a vault at runtime
remove_vault — Unregister vault (safe, doesn't delete files)
list_vaults — All registered vaults with status
get_vault_config — Inspect vault settings
set_active_vault — Switch context between multiple vaults
get_active_vault — Current active vault
get_vault_context — Meta-tool: single call returns vault status, available tools, OFM guide

Audit & History (5)

audit_log — Chronological change log with operation IDs for rollback
audit_stats — Audit overview: operation breakdown + snapshot disk usage
diff_note_version — Diff a note against a past audited version
rollback_preview — Preview what a rollback would change (read-only)
rollback_note — Undo a change by operation ID (atomic, audited)

Export (4)

export_health_report — Export vault health as JSON/CSV
export_broken_links — Export broken links with fix suggestions
export_vault_stats — Statistics and metrics export
export_analysis_report — Complete audit trail

Real-World Workflows

Initialize Without a Vault

# Server starts with NO vault required
response = client.call("get_vault_context")
# Returns: "No vault registered. Call add_vault() to get started."

response = client.call("add_vault", {
    "name": "personal",
    "path": "~/Documents/Obsidian"
})
# Auto-initializes: scans files, builds link graph, indexes for search

Multi-Vault Workflow

# Add multiple vaults
client.call("add_vault", {"name": "work", "path": "/work/notes"})
client.call("add_vault", {"name": "personal", "path": "~/notes"})

# Switch context instantly
client.call("set_active_vault", {"name": "work"})
search_results = client.call("search", {"query": "Q4 goals"})

client.call("set_active_vault", {"name": "personal"})
recommendations = client.call("recommend_related", {"path": "AI/ML.md"})

Vault Maintenance & Repair

# Quick diagnostic
health = client.call("quick_health_check")
if health["data"]["score"] < 60:
    # Deep analysis if needed
    full_analysis = client.call("full_health_analysis")

# Find and fix issues
broken = client.call("get_broken_links")
# Process broken links...

# Atomic bulk repair
client.call("batch_execute", {
    "operations": [
        {"type": "DeleteNote", "path": "old/deprecated.md"},
        {"type": "MoveNote", "from": "old/notes.md", "to": "new/notes.md"},
        # ... more operations
    ]
})

# Verify improvement
client.call("explain_vault")  # Holistic view

Content Discovery

# Find what matters
hubs = client.call("get_hub_notes")  # Top concepts
orphans = client.call("get_dead_end_notes")  # Incomplete topics

# Deep search
results = client.call("search", {"query": "machine learning"})

# Explore relationships
related = client.call("get_related_notes", {
    "path": "AI/ML.md",
    "max_hops": 3
})

# Get suggestions
suggestions = client.call("suggest_links", {"path": "AI/ML.md"})

Performance Profile

Operation	Time	Notes
`read_note`	<10ms	Instant with caching
`get_backlinks`, `get_forward_links`	<50ms	Graph lookup
`write_note`	<50ms	Includes graph update
`search` (10k notes)	<100ms	Tantivy BM25
`quick_health_check`	<100ms	Heuristic score
`full_health_analysis`	1–5s	Exhaustive, use sparingly
`explain_vault`	1–5s	Aggregates 5+ analyses
Vault initialization	100ms–5s	Depends on vault size

Key insight: Fast operations (<100ms) for common tasks, slower operations (1–5s) for exhaustive analysis. Claude uses smart fallbacks.

Configuration Profiles

Profile	Use Case
`development`	Local dev with verbose logging
`production`	Production with security auditing and optimized logging
`readonly`	Read-only access for safe exploration
`high-performance`	Large vaults (10k+ notes) with aggressive caching

Tool Visibility

TurboVault can reduce tools/list context by applying TurboMCP visibility rules from ~/.turbovault/config.yaml or --config:

tool_visibility:
  hidden:
    - full_health_analysis
    - explain_vault
  disabled:
    - delete_note

Use hidden for advanced tools that should stay callable by exact name, disabled for tools that should fail closed, and allowed when you want an explicit allowlist. Equivalent env/CLI overrides are available via TURBOVAULT_HIDDEN_TOOLS, TURBOVAULT_DISABLED_TOOLS, TURBOVAULT_ALLOWED_TOOLS, and --hidden-tools, --disabled-tools, --allowed-tools.

SDK and Server Implementation

TurboVault is designed for two primary audiences: developers building on top of the Rust SDK and users looking for a standalone MCP server.

As a Standalone MCP Server

The quickest way to get started is using the pre-built binary. It's fully self-contained and optimized for performance:

Link-time optimization (LTO) for maximum speed
Configurable transports (STDIO, HTTP, WebSocket, TCP)
Zero external dependencies (just point it at your vault)

# Build the optimized binary
cargo build --release --features full

# Run it
./target/release/turbovault --vault /path/to/vault --profile production

As a Rust SDK (Library)

The core of TurboVault is a collection of modular crates. Use them to build your own search engines, knowledge management tools, or even your own specialized MCP servers.

// Use in your own Rust projects
use turbovault_core::MultiVaultManager;
use turbovault_vault::VaultManager;
use turbovault_tools::SearchEngine;

#[tokio::main]
async fn main() -> 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 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 5MB per file (configurable)
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

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:
     - get_related_notes() -> related topics
     - get_backlinks() -> importance/connectivity
  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

Roadmap

Real-time vault watching (VaultWatcher framework ready)
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 for details

turbovault

安装

快速入门

安全报告

README.md