Vault Cortex

{
  "mcpServers": {
    "vault-cortex": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--header",
        "Authorization: Bearer "
      ]
    }
  }
}

claude.ai (web and mobile) connects to the remote setup only — its connectors are fetched server-side and can never reach localhost.

> "Remote MCP server" refers to the connection type (HTTP) — in the local setup the server still runs entirely on your machine.

See [Authentication](#authentication) for both methods and token lifetimes.

How It Works

graph LR
    Client["MCP Client"] -->|OAuth 2.1 / Bearer| Server["vault-mcp"]
    Server -->|read/write| Vault[("/vault.md files")]
    Server -->|FTS5 + vector| SQLite[("SQLite\nFTS5 + sqlite-vec")]
    Sync["obsidian-sync"] |Obsidian Sync| Vault

The search index is rebuildable derived state — FTS5 keyword tables rebuild on startup, vector embeddings persist across restarts with content-hash gating (only changed notes re-embed). A file watcher keeps both current, and queries fuse both signals via Reciprocal Rank Fusion. obsidian-sync keeps the vault in sync with your Obsidian apps (remote deployments only).

See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full design, auth flow diagrams, and component breakdown.

Hybrid Search

Keyword search alone fails when your vocabulary doesn't match the vault's — "aspirations" won't find a note about "targets", "coworkers" won't surface your "references" file. In testing against a real vault, 30% of natural-language queries returned zero or tangential results with keywords alone. Hybrid search eliminated those misses — vectors bridge the vocabulary gap, and the reranker rescues intent-heavy queries where neither signal is strong on its own.

Hybrid search combines three ranking signals via [Reciprocal Rank Fusion](./ARCHITECTURE.md#hybrid-search-r8):

• Keywords (FTS5) stay precise on exact terms, jargon, and property values
• Vectors (sqlite-vec) bridge the vocabulary gap by matching on meaning
• Reranker (cross-encoder) refines ordering by scoring each query-document pair jointly — rescues intent-heavy queries where keywords and vectors both miss

All models run locally (~45MB total, no external API). Set EMBEDDING_ENABLED=false for keyword-only search, or RERANK_MODE=none to skip reranking for lower latency.

See [ARCHITECTURE.md → Hybrid Search](./ARCHITECTURE.md#hybrid-search-r8) for model details, blend weights, and the full pipeline breakdown.

Tools (26)

| Category | Tool | Description | | --------------- | ---------------------------- | ---------------------------------------------------------- | | Vault CRUD | vault_read_note | Read a note — full body, properties, outline, or a section | | | vault_write_note | Create or overwrite a note with properties | | | vault_patch_note | Heading-targeted edit (append, prepend, replace, insert) | | | vault_replace_in_note | Find-and-replace text in a note | | | vault_delete_span | Delete a block of lines by short anchors, no full re-quote | | | vault_list_notes | List notes with optional glob/folder filter | | | vault_delete_note | Delete a note (protected paths enforced) | | | vault_move_note | Move or rename a note, rewriting links across the vault | | Search | vault_search | Hybrid search with tag/folder/property filters | | | vault_search_by_tag | Find notes by tag (exact or prefix match) | | | vault_search_by_folder | Browse notes in a folder with metadata | | | vault_recent_notes | Recently modified or created notes | | | vault_list_tags | All tags with usage counts | | | vault_list_tasks | Vault-wide task triage — status, date, priority filters | | Memory | vault_get_memory | Read structured memory (file, section, or all) | | | vault_update_memory | Append a dated entry to a memory section | | | vault_delete_memory | Remove a specific memory entry by date | | | vault_list_memory_files | Discover memory files and their sections | | Properties | vault_list_property_keys | All property keys with sample values | | | vault_list_property_values | Distinct values for a property key | | | vault_search_by_property | Find notes by property key-value | | | vault_update_properties | Add or update properties without touching the body | | Links | vault_get_backlinks | Notes linking to a given path | | | vault_get_outgoing_links | Links from a given note | | | vault_find_orphans | Notes with no incoming links | | Daily Notes | vault_get_daily_note | Today's (or any date's) daily note |

Prompts (3)

Tools are model-driven — the assistant calls them. Prompts are workflows you trigger. Each one queries the search index, link graph, and memory layer at invocation time, then assembles the results with guided instructions — so the session starts grounded in your vault's actual state, not assumptions.

| Prompt | Arguments | What it does | | ------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | vault-orientation | — | Surveys vault stats, folder distribution, property adoption rates (flags low adoption), orphans, broken link count, tags, recent notes, and the memory layer — with contextual tool suggestions | | memory-review | file?, max_chars? | Structural overview (scope callouts, section entry counts) + dated content as a timeline. Guided reflection: evolution narrative, scope-fit, backfill gaps, and coverage analysis. Hidden when MEMORY_ENABLED=false. | | daily-review | date?, max_chars? | Reconciles a day — daily note, vault-wide task status (due/overdue, scheduled), modified notes, outgoing links (broken-link detection), and backlinks — surfaces what happened, what's open, and what needs follow-up |

Prompts adapt to your configuration (MEMORY_DIR, daily-notes settings) and work for any vault out of the box. Pass max_chars to cap embedded content if your client has payload limits.

> Client support: Prompts work in Claude Desktop (Chat and Cowork — via the + menu under your connector), Claude Code (slash commands), and OpenCode. Support in other clients (Cursor, Windsurf) varies — see the MCP clients matrix for the latest.

Properties

Vault Cortex indexes every property in your notes, but five get promoted treatment — dedicated columns for fast filtering, and top-level fields in every search and discovery result:

| Property | What you can do | | --------- | ------------------------------------------------------------------------------------------------------------ | | title | Display name in search results; falls back to the filename when missing | | tags | Search and filter by tag, including parent-child hierarchies (project matches project/vault-cortex) | | type | Filter by note type — meeting, person, session-log, or any value your vault uses | | created | Sort by creation date and see when each note was created alongside every search result | | related | Filter for notes that cross-reference a specific link — surfaces connections invisible without a graph query |

All other properties are still fully queryable — use vault_search with filters.properties for combined text + metadata queries, or vault_search_by_property for metadata-only lookups. vault_list_property_keys and vault_list_property_values discover what properties exist across your vault.

These are conventions, not requirements — Vault Cortex works with any property schema. Promoted properties just give you richer filtering and cleaner results out of the box.