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, modularRust SDKfor building applications that consume markdown directories, and afull-featured MCP serverthat works out of the box with Claude and other AI agents.

Build your own applications, search engines, or custom MCP servers using our modular crates. TurboVault handles the heavy lifting of parsing.mdand.ofmfiles, 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 gain74 specialized toolsfor 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.

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

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

- Full-text searchacross all notes with BM25 ranking
- Link graph analysisto discover relationships, hubs, orphans, and cycles
- Vault intelligencewith health scoring and automated recommendations
- Validated operation batchesfor fewer round trips and fail-fast execution
- Multi-vault supportwith instant context switching
- Runtime vault addition— no vault required at startup, add them as needed

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

# 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

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

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

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

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

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

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]

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 withturbovault --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.

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

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

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

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

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

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

- 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 withwrite_backend: git; direct stays sequential

- 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

- 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

- 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

- 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— 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_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

- 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

- okf_validate— Validate the vault as anOKFv0.1 bundle (conformance + concepttypevocabulary); usable as a CI/pre-publish gate
- generate_index— Generate/refreshindex.mdfiles for progressive disclosure (idempotent)
- append_log_entry— Append a dated entry to a directory'slog.mdupdate history (§7)
- visualize— Render the concept graph as a shareable, self-contained HTML file (force-directed graph + rendered notes + backlinks)

# 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

# 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"})

# 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

# 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"})

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

TurboVault can reducetools/listcontext by applying TurboMCP visibility rules from~/.turbovault/config.yamlor--config:

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

Usehiddenfor advanced tools that should stay callable by exact name,disabledfor tools that should fail closed, andallowedwhen you want an explicit allowlist. Equivalent env/CLI overrides are available viaTURBOVAULT_HIDDEN_TOOLS,TURBOVAULT_DISABLED_TOOLS,TURBOVAULT_ALLOWED_TOOLS, and--hidden-tools,--disabled-tools,--allowed-tools.

TurboVault is designed for two primary audiences: developers building on top of theRust SDKand users looking for astandalone 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

The core of TurboVault is a collection of modular crates. Use them to build your own search engines, knowledge management tools, or evenyour 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.

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 tocrates.iofor public use.

- 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

- 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_notedetects concurrent modifications
- File size limits— Default 5MB per file (configurable)
- No shell execution— Zero command injection risk
- Security auditing— Detailed logs in production mode

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

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

make build # Debug build make release # Production build make test # Run tests make clean # Clean build artifacts

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)"

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

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

- Real-time vault watching (VaultWatcher framework ready)
- Cross-vault link resolution
- Encrypted vault support
- Collaborative locking
- WebSocket transport (beyond MCP stdio)

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

- Repository:https://github.com/epistates/turbovault
- Issues:https://github.com/epistates/turbovault/issues
- MCP Protocol:https://modelcontextprotocol.io
- Obsidian:https://obsidian.md
- Related:TurboMCP

Standalone Obsidian MCP server with semantic search, knowledge graph analytics (PageRank, Louvain, shortest path), and vault editing — no plugin, no REST API, works when Obsidian is closed.