Vulcan

A local-first information hub that makes Markdown searchable, queryable, and programmable.

Vulcan turns an Obsidian vault or plain Markdown directory into a knowledge base you can work with from the terminal, scripts, and agent tools. Search your notes, query structured records, follow links, manage tasks, make precise edits, and publish selected content—all while keeping ordinary files as the source of truth. Obsidian does not need to be installed or running.

Knowledge bases remain Vulcan's focus. Registered directories have a versioned, device-local knowledge or files-only capability profile. knowledge remains the backward-compatible default; files-only lets the daemon manage a full Git working tree without indexing Markdown or running knowledge services. Both profiles currently use full-tree materialization. Selective materialization, partial clone, shallow-history handling, and selective LFS transfer remain planned in 12.20.

Pre-alpha: Vulcan is moving fast and contains a large amount of LLM-written code. Treat it as experimental, keep backups, and use Git or another versioning system before pointing it at important vaults.

Getting started · Installation · CLI reference · Architecture · Roadmap

What you can do today

Work with a knowledge base

Search note text with full-text and optional semantic search; explore backlinks, outgoing links, and the note graph; find unresolved links and other diagnostics. Query frontmatter, tags, inline fields, and file metadata using Vulcan's query language, Dataview DQL, or Obsidian Bases views.

Read and patch individual sections of long notes, rename files with link rewriting, and preview bulk property edits and refactors. Terminal browsers and interactive Bases views complement the scriptable commands.

Start with the query guide, filter reference, and workflow recipes.

Use Markdown as a database

Keep tasks, projects, contacts, and other records in readable Markdown with structured metadata. Vulcan supports inline tasks, TaskNotes task files, recurring tasks, dependencies, Kanban boards, periodic notes, templates, and capture workflows.

The explicit mdbase commands add typed collection discovery, schema validation, record reads, CEL queries, link semantics, effective-schema reports, and saved views (including Obsidian .base sources) against a pinned mdbase v0.3 specification. Writes to collection records go through one validated, journaled pipeline. Compatibility is scoped to tested profiles and features, which vulcan mdbase conformance reports; the Collection Studio App backend remains planned. Ordinary vaults do not need mdbase schemas.

See the mdbase guide and its example collection, the CLI reference for task and metadata workflows, and the mdbase roadmap for remaining work.

Automate with scripts and agents

Use the CLI directly from shell or Python scripts, request JSON output, or run JavaScript against Vulcan's vault API. The same local workflows support agent tool discovery, MCP clients, reusable skills, and typed skill commands. Direct CLI operation does not require a daemon.

Surface	Best suited to
CLI with --output json	Shell scripts, CI, and programs invoking Vulcan
vulcan run	JavaScript scripts using the vault API
Skills and skill commands	Reusable agent guidance and typed callable workflows
Plugins	Event-driven lifecycle hooks
MCP	Tool clients using permission profiles and selected tool packs
Rust crates	Native integration with shared semantics and application workflows

Read the automation overview, scripting guide, JavaScript API, and sandbox guide. For remote agent access with per-connection consent, see named MCP remotes (vulcan help mcp-remotes) and the ChatGPT MCP setup guide.

Publish and synchronize

Export selected notes as documents, datasets, books, or archives; build static sites; or publish to Outline. Outline integration includes explicit pull and publication workflows, exact note/document bindings, and named subtree routes with conflict handling.

Git-backed synchronization replicates the complete working tree across registered directories. The knowledge profile preserves existing vault behavior; files-only skips indexing, knowledge-specific validation, scripts, semantic history, and agent conflict resolution while using the same file reconciliation. Concurrent automatic merges on files-only registrations remain preserved for review. An optional multi-vault daemon schedules synchronization, performs a bounded final sync on graceful shutdown, and reconciles again after detecting resume from suspend; the Obsidian companion exposes status, sync, and file-conflict review. Files-only unattended sync checks repository shape, but external Git processes are outside Vulcan's lock; active development checkout workflows need a separate contract. File replication does not by itself provide a complete backup of refs, history, or Git LFS payloads. Device synchronization and external wiki publication have separate responsibilities: external documents pass through an inspectable local vault.

Follow the guides for static sites, Outline publishing, Git synchronization, device keys for Git over SSH, unattended conflict resolution, and the Obsidian companion.

Quick start

Install a release using the installation guide, which covers Linux, macOS, Windows, and Android/Termux, plus upgrades and optional daemon services. Place vulcan on your PATH. Git is a separate dependency for synchronization.

To build from this checkout instead, use the toolchain selected by rust-toolchain.toml (Rust 1.90 minimum):

cargo build --release --locked -p vulcan-cli --bin vulcan
export PATH="$PWD/target/release:$PATH"

Initialize an existing Markdown directory and build its local index:

vulcan --vault ~/notes index init
vulcan --vault ~/notes index scan

Search, query, and inspect it:

# Search note contents.
vulcan --vault ~/notes search 'meeting notes'

# Select records by metadata and return JSON for a script.
vulcan --vault ~/notes query \
  'from notes where status = "open" order by file.path asc limit 20' \
  --output json

# Browse interactively, or inspect indexing and link diagnostics.
vulcan --vault ~/notes browse
vulcan --vault ~/notes doctor

For an existing note, use its vault-relative path to read or preview an edit:

vulcan --vault ~/notes note get 'Projects/Alpha.md' --output json
vulcan --vault ~/notes note patch 'Projects/Alpha.md' \
  --find 'TODO' --replace 'DONE' --dry-run

For an external agent runtime or MCP client:

vulcan --vault ~/notes agent install
vulcan --vault ~/notes describe --format mcp
vulcan --vault ~/notes mcp --transport stdio --tool-pack notes-read,search,status

Explore commands with vulcan --help and topic guides with vulcan help. The getting-started guide and CLI reference cover additional workflows and configuration prerequisites.

How your data is stored

Vulcan follows three layers:

Markdown, attachments, and collection definitions   ← canonical vault files
                      ↓ parse and index
              Rebuildable SQLite cache             ← metadata and link graph
                      ↓ derive
             Full-text and vector indexes          ← search and retrieval

You can edit the files with your existing editor and rebuild the cache from disk. .obsidian/ is optional. Compatibility adapters interpret supported plugin formats and settings; they do not require the plugins to run or promise complete desktop behavior parity.

Vault-local configuration and state live under .vulcan/:

Path	Purpose
config.toml	Shared vault configuration, usually committed with the vault
config.local.toml	Device-local overrides, ignored by default
cache.db	Rebuildable SQLite cache
publish/	Durable publisher identity mappings
integrations/	Durable import identities, reconciliation snapshots, conflict journals, and route state

The cache is disposable; remote identities and recovery state are not. Keep durable workflow state when backing up or moving an integration. See the configuration reference and information-hub guide for the boundaries. Supported Obsidian settings can be imported explicitly with vulcan config import --all.

Where the project is going

The roadmap tracks implementation separately from design targets. Major directions include a web wiki, broader external knowledge connectors, and Vulcan Apps: installable applications with browser views, typed commands, and explicitly granted access to vault data.

Further selective-materialization work is tracked in 12.20: sparse checkouts, selective Git LFS downloads, partial clones, and separately scoped shallow-history handling. These capabilities are not advertised for sync. The design separates a directory's logical file tree from the subset available on each device; excluded files must never become accidental deletions. Managing a development checkout or retaining a complete backup requires an explicit policy beyond synchronizing its working files.

For wiki-native structured data, the accepted direction is one portable mdbase model with one Vulcan execution and mutation engine. Markdown and mdbase definitions remain canonical; SQLite supplies rebuildable, indexed query projections. Equivalent mdbase and collection-bound native queries should share optimized execution, while managed writes should share schema validation, lifecycle rules, and Markdown persistence.

That integration is planned. The current mdbase query path still performs collection-wide work, and the documented latency targets are acceptance criteria, not measured guarantees. The target profile includes warm App reads below 50 ms at p95 and direct CLI queries below 100 ms at p95 under defined workloads. Standalone scripts remain useful independently of the App platform.

• mdbase performance and native integration: execution strategy, shared writes, benchmark workloads, and readiness gates.
• Vulcan App specification and example App designs: planned package, API, storage, and application model.
• Local information hub: current Outline integration and planned routes to additional knowledge systems.
• Performance notes: optimization evidence and remaining work.

Documentation map

If you want to…	Read
Install, upgrade, or run a service	Installation
Learn commands and selection syntax	CLI reference, queries, filters
Write scripts or extend automation	Scripting, JS API, custom tools, skill commands
Configure permissions and script access	Configuration, sandboxing, MCP setup
Publish or exchange knowledge	Static sites, Outline, external wikis
Sync devices and use Obsidian alongside Vulcan	Git sync, device keys, companion plugin
Understand or contribute to the implementation	Design document, roadmap, hardening and verification

Development

The Rust workspace separates reusable synchronous semantics and workflows from UI and async transports:

Crate	Responsibility
vulcan-core	Parsing, indexing, SQLite cache, queries, graph, tasks, permissions, and compatibility semantics
vulcan-app	Reusable application workflows, including mutations, publication, configuration, and plugin dispatch
vulcan-cli	CLI, terminal UIs, output formatting, and local MCP stdio adapter
vulcan-daemon	Async service, multi-vault registry, MCP HTTP/OAuth hosting, and background scheduling
vulcan-secrets	Device-local secret custody and protected-file storage
vulcan-sync	Synchronous Git synchronization engine and backend boundaries
vulcan-embed	Embedding providers and vector-store abstractions

The vulcan-app crate is the shared workflow layer used today; the planned Vulcan Apps platform is a separate product capability.

Run the required checks before committing:

cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo check --workspace --no-default-features

See hardening for feature combinations and architecture boundary checks.