How do I install Vault Cortex?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Vault Cortex need an API key?

The publisher lists these environment variables: MCP_AUTH_TOKEN, PUBLIC_URL, EMBEDDING_ENABLED, RERANK_MODE, WINDOWS_MODE, MEMORY_ENABLED, FILE_TOOLS_ENABLED, READONLY_MODE, DISABLED_TOOLS, MEMORY_DIR, DAILY_NOTES_FOLDER, DAILY_NOTES_FORMAT, TRUST_PROXY_HOPS, TRUST_FORWARDED_HOPS, TZ, LOG_LEVEL, LOG_DIR, LOG_RETENTION_DAYS, LOG_MAX_DAILY_MB, PROTECTED_PATHS, ORPHAN_EXCLUDE_FOLDERS, SERVICE_DOCUMENTATION_URL, MAX_FILE_BYTES, MAX_IMAGE_OUTPUT_BYTES, MAX_PDF_RENDER_PAGES.

What transport does Vault Cortex use?

Vault Cortex runs locally over stdio.

When was Vault Cortex last checked?

Last checked 2026-11-10. Standalone MCP server for Obsidian vaults — hybrid search, notes & files, memory, tasks, OAuth 2.1

Vault Cortex MCP server

Vault Cortex is a standalone MCP server that gives any AI agent hybrid search, task management, structured memory, and read/write access to your Obsidian vault. No plugins, no running Obsidian, no separate bridge. One Docker container, your vault folder, a full tool suite + guided prompts. Run it on a remote server with Obsidian Sync, and the same vault is accessible from your phone, claude.ai, or any remote MCP client, secured with OAuth 2.1. Deploy it with one click or self-host it; either way, the vault is always yours.

Contents — What you get · Quick Start · How It Works · Hybrid Search · Memory · Tasks · Files · Tools · Prompts · Properties · Config · Daily Notes · Data Integrity · Auth · Deployment · One-click Deploy · Community Deployments

What you get

Tested across a 15-day trip through Europe. 30+ sessions from a phone, 216 tool calls, zero laptop access needed. Writes in one session were immediately available in the next, across cities and days.

Quick Start

Local (2 minutes — Docker + your vault folder)

Prerequisites: Docker (or a Docker-compatible runtime, e.g. OrbStack, Colima, Podman), Node.js >= 22.12 (only for the CLI — the server itself runs in Docker), and an Obsidian vault (or any folder of .md files).

npx vault-cortex@latest init

That's it — the CLI asks for your vault path, generates the auth token and config files, starts the server, and prints the connection details for your MCP client (CLI reference →). Set up with the CLI? It manages the server from here on — configure, upgrade, start, restart, logs, down (CLI reference →).

Set up with Compose? Stick with Compose for updates too (docker compose pull && docker compose up -d) — the CLI and Compose manage the container independently.

# 1. Get the quickstart files
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/local/docker-compose.yml
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/local/.env.example

# 2. Configure
cp .env.example .env
# Edit .env — set MCP_AUTH_TOKEN (openssl rand -hex 32) and VAULT_PATH

# 3. Start
docker compose up

Full local guide → (includes Windows setup)

Remote (access from anywhere)

Your vault on a server, kept current by Obsidian Sync, reachable from your phone, claude.ai, or any MCP client. The one-click options ask for your vault name and timezone (plus the vault password if your vault is encrypted), then handle HTTPS, restarts, a generated MCP token, and persistent storage. Once deployed, a setup page walks you through signing in to Obsidian Sync in your browser. On your own server the CLI asks for the public URL and vault name, captures the Sync token for you, and generates the MCP token; HTTPS is yours to set up.

	Railway	Render	Self-hosted
			CLI setup →
Account	Railway on the Hobby plan or higher — the 5 GB volume is included	Render with a card on file	A VPS with Docker
Cost	Usage-metered: typically $20–30 USD/mo for a personal vault — a little under Render for a quiet vault, a little over for a busy one	Flat: about $26 USD/mo for the Standard instance (2 GB) and 5 GB disk, billed by the second	Whatever your VPS costs
Pick it if	You want the easier start — the template lands you in a configured project	A predictable bill matters more than setup polish	You already run a server or want full control
Guide	Railway guide →	Render guide →	Remote guide →

All three need an Obsidian Sync subscription. Whichever you pick, the server is replaceable and your vault isn't — it stays in plain Markdown in Obsidian Sync and on your devices; the container only holds a copy.

The setup page. Deploy without an Obsidian Sync token and the server starts in setup mode: opening its URL in a browser lands on a sign-in page at /setup. Enter your Obsidian account credentials once (two-factor supported) — you sign in with Obsidian directly; the server keeps only the Sync token from that sign-in, restarts, and downloads your vault.

Self-hosted: your own VPS

The Vault Cortex CLI sets up the same container on any Linux box you run — you manage the server, the image, and updates. You need Node.js >= 22.12 for the CLI itself; the server runs in Docker.

# On your VPS:
npx vault-cortex@latest init --mode remote

That's it — the CLI walks through the public URL, Obsidian Sync token (it can run get-sync-token for you), vault name, the vault password for an encrypted vault, and auth config, then starts the server (CLI reference →).

Set up with the CLI? It manages the server from here on — configure, upgrade, start, restart, logs, down (CLI reference →).

Set up with Compose? Stick with Compose for updates too (docker compose pull && docker compose up -d) — the CLI and Compose manage the container independently.

# On your VPS:
mkdir -p /opt/vault-cortex && cd /opt/vault-cortex
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/remote/docker-compose.yml
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/remote/.env.example
cp .env.example .env
# Edit .env — set MCP_AUTH_TOKEN, PUBLIC_URL, VAULT_NAME (OBSIDIAN_AUTH_TOKEN optional — /setup handles it)
docker compose up -d

Left OBSIDIAN_AUTH_TOKEN empty? Once the container is up, open <PUBLIC_URL>/setup in your browser and sign in — set up HTTPS first, since the page sends your Obsidian password to the server (full walkthrough →).

Connect your MCP client

Setup	Server URL
Local	`http://localhost:8000/mcp`
Remote (one-click)	`https://<host>/mcp` — `<host>` is the domain Render or Railway shows on the service page
Remote (self-hosted)	`<PUBLIC_URL>/mcp`

Add the server URL in any MCP client — Claude Code, Claude Desktop, Cursor, OpenCode, or any other. OAuth clients open a consent page in your browser — approve with your token, and the client handles token renewal from then on. Clients without OAuth (MCP Inspector, scripts) send the token directly as an Authorization: Bearer header.

Claude Code:

claude mcp add --scope user --transport http vault-cortex http://localhost:8000/mcp   # local (or <PUBLIC_URL>/mcp)

--scope user registers the server for every project; omit it to scope it to the current directory only.

A remote server with a publicly reachable https URL adds directly in Claude Desktop's "Add custom connector" dialog — no file editing. Any http URL — localhost included — is rejected by that dialog, so register it in claude_desktop_config.json instead (Claude Desktop → Settings → Developer → Edit Config opens the file) through the mcp-remote stdio bridge:

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

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 for both methods and token lifetimes.

How It Works

Everything runs in one Docker container, working directly with the .md files on disk:

Your vault stays the source of truth — the server reads and writes the same plain Markdown files your Obsidian apps do.
Search is derived data — a file watcher keeps the index (keywords + vectors) current as notes change, and it can be rebuilt from your notes at any time.
The remote image adds a sync loop — a bundled Obsidian Sync service keeps the container's vault current with every device: edit a note on your phone and it's searchable moments later; an agent writes a note and it shows up in Obsidian.

graph LR
    subgraph container ["One Docker container"]
        Sync["sync service<br/>(remote image)"]
        Vault[("/vault<br/>.md files — source of truth")]
        Index[("search index<br/>keywords + vectors")]
        Server["MCP server"]
        Sync <-->|read/write| Vault
        Vault -->|file watcher| Index
        Server <-->|read/write| Vault
        Server -->|query| Index
    end
    Obsidian["Your Obsidian apps<br/>(phone, laptop)"] <-->|Obsidian Sync| Sync
    Client["Any MCP client<br/>(Claude, Cursor, claude.ai)"] -->|OAuth 2.1 / Bearer| Server

See 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 in the same test.

Hybrid search fuses the keyword and vector rankings via Reciprocal Rank Fusion, then the reranker refines the fused result:

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 for model details, blend weights, and the full pipeline breakdown.

Memory

A memory layer that only grows is only useful if agents can retrieve the right entries without reading everything back every time. Once you have hundreds of dated entries across multiple files — preferences, principles, communication style, ongoing commitments — whole-file reads bury the signal in irrelevant material. The memory system is designed for targeted retrieval.

The layer is a folder of plain Markdown files (default: About Me/) holding dated entries under topic headings — auto-created with starter templates on first run, grown by agents through vault_update_memory. Three properties make it work:

Append-only — entries are never overwritten; corrections arrive as new dated entries. The layer becomes a personal knowledge base that captures your current state and the evolution behind it
Topic recall — vault_memory_recall retrieves every relevant entry across all memory files at once, matched by keyword and by meaning, oldest first. Ask "what do I think about X?" and get the current take plus the dated history of how it developed — no need to read entire files or guess which file holds what
Grows without degrading — capping results (limit) drops the least-relevant entries, never a slice of the timeline. A memory layer with 500 entries serves a targeted query as well as one with 50

Files that describe what's current rather than what has been true (routines, active commitments) can declare entry-policy: living in frontmatter — their expired entries are prunable rather than preserved, keeping the current-state picture accurate.

The whole layer is optional — set MEMORY_ENABLED=false to hide the memory tools and skip the folder auto-creation entirely.

See ARCHITECTURE.md → Memory for the recall pipeline, indexing model, auto-initialization, and opt-out behavior, and templates/memory for the file format, entry-policy convention, and starter templates.

Tasks

Task metadata lives in plain markdown — scattered across files, encoded in emoji signifiers or inline fields, organized under Kanban headings. An agent answering "what's overdue?" would need to parse every file and understand your chosen format; completing a task on a Kanban board means knowing the board's lane structure, the date syntax, and which heading is the done lane.

The task layer handles this so agents don't have to:

Find — filter by status, six date fields (due, scheduled, start, created, done, cancelled), priority, folder, or Kanban lane. Each result carries its note path, line number, and nearest heading when the task sits under one (the lane on a Kanban board) — no follow-up reads needed to locate a task
Create — add a correctly-formatted task in one step: description, priority, dates, recurrence, "On completion" action, dependencies, block ID (^id), and checklist sub-items (text only, no dates), placed under a heading at the top, the bottom, or an exact position, or nested under a parent task as a sub-task with its own dates. On a Kanban board a sub-task gets no block ID, since the Kanban plugin copies it onto the card when it saves the board
Update — complete, reprioritize, edit the text, set or clear dates, recurrence, and the "On completion" action, add checklist items, move tasks between headings, and reorder within a lane in a single call
Complete — marking a task done auto-detects the done lane and stamps the completion date, honoring the plugin's "Set done date" setting; reversing it removes the date. Completion also runs the Tasks plugin's own behaviors:
- a recurring task spawns its next occurrence, dates advanced the way the plugin computes them
- a task set to delete "On completion" disappears from the note
Both formats — whichever format you use, Tasks plugin emoji signifiers or Dataview inline fields, the server reads both and writes in the format your Tasks plugin is configured for — read from the plugin's settings when your vault syncs .obsidian/, with emoji signifiers as the default otherwise

See ARCHITECTURE.md → Tasks for the indexing model, date cascade sorting, and Kanban lane detection.

Files

Your notes embed screenshots, reference architecture diagrams, and link out to canvases and data files — but to an agent reading markdown, ![[diagram.png]] is just text. Vault Cortex treats files as part of the vault rather than clutter around it — linked, sized, and readable, each in the form an agent can use:

Images — the image itself, not the filename. Screenshots and diagrams are downscaled and recompressed server-side when they exceed what MCP clients accept, so even a phone session can look at a 5MB architecture diagram
Canvases — a Canvas board arrives as a readable outline: its groups, each card's content in reading order, and the connections between them. Canvas content is full-text searchable, and file references on the board appear in the link graph — backlinks and outgoing links work just like note-to-note links. The exact JSON source is one flag away when full fidelity matters
PDFs — text is extracted with heading hierarchy, code blocks, and hyperlinks preserved; PDF content is full-text searchable alongside your notes. Set raw: true to render pages as images instead, showing layout, diagrams, and tables that text extraction can't preserve — scanned and image-only PDFs work in this mode
Text and data files — TXT, SVG, JSON, XML, CSV, YAML, logs, and Bases files return exactly as written; the first 100 KB of content is full-text searchable. Big data files and logs can be read a line range at a time, with each page reporting where you are and how much file remains
Browse — list any visible folder's files with per-extension counts and file sizes; files a note links to report their size in the link graph too

Set FILE_TOOLS_ENABLED=false to hide the file tools — useful when your remote vault syncs without attachments.

See ARCHITECTURE.md → Files for the image pipeline and dispatch model.

Tools

Category	Tool	Description
Vault CRUD	`vault_read_note`	Read a note — full body, properties, outline, or a section
	`vault_write_note`	Create a note (fails if it already exists; set `overwrite` to replace)
	`vault_patch_note`	Heading-targeted edit (append, prepend, replace with `include_children` guard, insert)
	`vault_replace_in_note`	Find-and-replace text in a note (first match or `replace_all_occurrences`)
	`vault_delete_span`	Delete a block of lines by short anchors, no full re-quote
	`vault_replace_span`	Replace a block of lines by short anchors with new content
	`vault_insert_at_anchor`	Insert content before or after a line identified by a short anchor
	`vault_list_notes`	List notes with optional glob/folder filter
	`vault_delete_note`	Delete a note, honoring the vault's trash setting (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/date 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
Tasks	`vault_list_tasks`	Vault-wide task index with sub-task depth — Kanban-aware, date/priority/heading filters

Prompts

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 — append-only by default, pruning proposed only for `entry-policy: living` files. Hidden when `MEMORY_ENABLED=false`, `READONLY_MODE=true`, or `DISABLED_TOOLS` includes `vault_update_memory`.
`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 give you richer filtering and cleaner results out of the box.

Leading callouts get the same treatment. When a note's first body content is an Obsidian callout (> [!type]) — either right after frontmatter or right after the title heading — it's indexed and surfaced alongside every discovery result (on vault_search, ask for it with include_leading_callout). This makes notes self-describing: an agent scanning results can see what each note is for before deciding which to read. The memory templates use > [!info] Scope of this file callouts for this, and any note in your vault can use the same pattern.

Configuration

All settings are environment variables with sensible defaults. Some defaults derive from other settings — the Default column shows each derivation, and a value you set replaces the whole derived default. Remote deployments also forward Obsidian Sync's own settings — DEVICE_NAME, SYNC_MODE, CONFLICT_STRATEGY, SYNC_CONFIGS, SYNC_EXCLUDED_FOLDERS, SYNC_FILE_TYPES — documented in the remote guide's configuration table.

Variable	Required?	Default	Description
`MCP_AUTH_TOKEN`	Yes	—	Bearer token for authentication (also the JWT signing key)
`VAULT_PATH`	Local only	—	Host path to your vault (bind mount source; remote uses a named volume). Must not contain `*`, `?`, or `[` — rejected at startup.
`PUBLIC_URL`	Remote only	—	Public URL for OAuth discovery metadata. Filled in automatically on Render and Railway (from `RENDER_EXTERNAL_URL` or `RAILWAY_PUBLIC_DOMAIN`) when left unset
`OBSIDIAN_AUTH_TOKEN`	—	—	Obsidian Sync auth token. Leave empty to sign in through the `/setup` page after deploy; or the CLI's `get-sync-token` captures it for you
`VAULT_NAME`	Remote only	—	Exact name of your Obsidian vault (case-sensitive)
`VAULT_PASSWORD`	Remote only	—	End-to-end encryption password, if your vault has one. Leave empty otherwise.
`STORAGE_ROOT`	—	—	One directory for everything that must persist — the vault, the search index, and Obsidian Sync state — for container hosting platforms that allow a single persistent volume (Railway, Render). Mount the volume there and set this to the same path. Must not contain `*`, `?`, or `[` — rejected at startup.
`EMBEDDING_ENABLED`	—	`true`	Set `false` to disable the embedding pipeline — skips model download, vector tables, embedding passes, and hybrid search. Search falls back to FTS5 keyword matching.
`RERANK_MODE`	—	`blended`	Cross-encoder reranking mode: `blended` applies position-aware score blending after RRF fusion (~200ms added latency), skips reranking. Only takes effect when is true.

See templates/memory/ for memory file examples and the dated-entry design philosophy.

Daily notes

vault_get_daily_note and the daily-review prompt find your daily notes using the folder and filename date format configured in Obsidian, read from your vault's .obsidian/daily-notes.json:

Local mode reads the file straight from your bind-mounted vault — nothing to set up.
Remote mode receives it through Obsidian Sync's vault configuration syncing. The server pulls it by default (the SYNC_CONFIGS setting in .env), but your devices must also send it: turn on Obsidian Settings → Sync → Vault configuration sync on each device. Details: the remote guide's Daily notes section.

When the file isn't available — or if you use the Periodic Notes plugin, whose settings daily-notes.json doesn't hold — set the values yourself:

DAILY_NOTES_FOLDER — any vault-relative path: Journal, Planner/Daily, or / for the vault root
DAILY_NOTES_FORMAT — same tokens as Obsidian's date format setting: YYYY-MM-DD-dddd, YYYY/MM/DD, MMM D, YYYY, …

You can set one or both — a set value always wins over the config file. A value you leave unset comes from daily-notes.json; when that file is missing, the server uses Daily Notes and YYYY-MM-DD.

Changes in Obsidian apply on the next call when .obsidian/daily-notes.json is available in the server's vault.
Apply environment changes with the CLI's restart command, recreate the Compose container, or redeploy on your hosting platform.
If you leave the folder empty in Obsidian's Daily notes options, the server follows Obsidian's Default location for new notes setting (Settings → Files and links), read from .obsidian/app.json. Same folder as current file counts as the vault root, because Obsidian creates a daily note without reference to an open note and so has no folder to follow. When app.json isn't in the server's vault, as in remote mode with the default SYNC_CONFIGS, the server uses the vault root.
If your daily notes live in the vault root, or in the new-note folder because the folder setting is empty, delete and move don't protect them and orphan results can include them. Protecting or excluding that folder would also cover every other note in it.

Note: A few date format tokens are unsupported — ordinals (Do, Mo, DDDo, wo), dd (2-letter weekday), d (weekday number), e, k/kk, w (week number), Q (quarter), Z/ZZ (UTC offset), and the localized formats (L–LLLL, LT, LTS). The server can't reproduce the filenames Obsidian creates with these tokens, so it could never find the notes. If your format uses any of them, vault_get_daily_note returns a clear error — change the format in Obsidian or set DAILY_NOTES_FORMAT to a supported alternative.

Data Integrity

Vault Cortex writes to personal notes — the file safety layer is built to prevent corruption, not just errors.

Atomic writes — every file write stages to a temp file, then renames. Readers never see a partial or 0-byte note. Exclusive creates use link() (POSIX no-clobber) to close the TOCTOU window on note moves.
Per-file mutex — concurrent MCP tool calls serialize or fail-fast per file. Moves lock the source, destination, and every backlink source as one unit.
Properties are protected — an edit refuses a note whose properties block it can't keep (invalid YAML, a list, a single value, or a value with an explicit YAML tag such as !!str) and leaves the file unchanged, and a write that would leave a note opening with --- lines it can't keep is refused too. The error says how to repair the note; vault_update_properties with replace: true replaces the whole block. A rewrite keeps every property but not YAML comments in the block.
Notes with broken properties stay searchable — search reads a note whose properties block is not valid YAML as if it had no properties. The note still appears in search results and task lists, its body links still count as backlinks, and the server log names it as needing repair.
Path traversal blocked — resolveSafePath() resolves then prefix-checks every path. Protected-path deletion is refused after normalization. Memory file names reject separators at the boundary.
Hidden paths are off-limits — files and folders starting with a dot (.obsidian/, .trash/) never appear in listings or search, and any tool call that targets one directly is rejected, matching Obsidian. Plugin configs and their API keys stay out of reach.
Deletes honor Obsidian's trash setting — with "Deleted files" at Obsidian's default "Move to system trash" or at "Move to Obsidian trash", a deleted note moves to .trash/ inside the vault instead of being removed (a container has no system trash; .trash/ is Obsidian's own fallback for that). "Permanently delete" removes the note for good.
Obsidian Sync deployments delete permanently — the delete syncs to every device, and recovery is Sync's version history rather than a trash folder.
Bounded trash with a retention sweep — notes the server moves to .trash/ under the system-default setting are cleaned up after TRASH_RETENTION_DAYS (default 30 days; none keeps them forever). The sweep removes only files it recorded — notes Obsidian itself trashed, and "Move to Obsidian trash" deletes, are never touched.
Injection prevention — search queries are parameterized and FTS5-sanitized; prompt content is wrapped in XML data markers with closing-tag escaping to prevent tag-breakout injection.

See ARCHITECTURE.md → Data Integrity for mechanism details and SECURITY.md → Runtime Hardening for how each part of the server is hardened.

Authentication

For a server with read/write access to personal notes, authentication is not optional. Vault Cortex implements the full OAuth 2.1 specification, including PKCE and refresh-token rotation. The AWS (SST) deployment adds defense-in-depth: requests are validated at two independent layers (API Gateway Lambda authorizer + Express middleware). Per BlueRock's 2026 MCP security analysis, only 8.5% of MCP servers implement OAuth; 41% have no authentication at all.

Two methods:

Method	Used by	Token format
OAuth 2.1	Claude Desktop, Claude Code, claude.ai, any OAuth client	JWT (HS256, 6h)
Static bearer	Claude Code, MCP Inspector, curl	Raw `MCP_AUTH_TOKEN`

The method follows from your client — OAuth when it supports it, the raw token in a header otherwise (Connect your MCP client shows both).

OAuth uses dynamic client registration — no manual Client ID or Secret needed:

Your client registers automatically and receives a client ID and secret.
Enter your MCP_AUTH_TOKEN on the browser consent page to approve access.
Your client includes the issued secret in subsequent token requests automatically.

Refresh tokens have a 60-day sliding expiry. Access tokens are bound to your server's URL, so a token minted for one deployment is never accepted by another. Rotating MCP_AUTH_TOKEN ends every session — each client re-authorizes through the consent page.

See ARCHITECTURE.md → Auth for the full flow diagram.

Deployment Options

Local runs on your machine. Remote deployments run on a VPS or a hosted container platform — your vault is accessible even when your laptop is closed.

Whichever path you pick, the server is replaceable and your vault isn't. Your notes are plain Markdown files, synced by Obsidian to every device you own; the container holds a copy and an index it can rebuild from scratch. Shut down the VPS, delete the Render or Railway service, switch hosts — the same files are still on your machine and in Obsidian Sync, readable by anything. That's the difference from an AI notebook whose real home is the vendor's database: here the host is a convenience, not a custodian.

Path	What	Guide
Local	Your vault on your machine — free, no cloud	`deploy/local/`
Remote · one-click	Render or Railway — one persistent volume, no server to manage	`deploy/render/` · `deploy/railway/`
Remote · self-hosted	VPS + Obsidian Sync — access from any device	`deploy/remote/`
Remote · AWS (SST)	IaC reference deployment — automated infra, defense-in-depth auth	`DEPLOY.md`

The AWS path includes CI/CD workflows built for this repo — forkers need to configure their own credentials and stage before deploying.

Every path runs the same image, ghcr.io/aliasunder/vault-cortex — :latest is the MCP server alone (local), :remote bundles Obsidian Sync in the same container under s6-overlay supervision (one-click, self-hosted, and AWS). One container means any OCI runtime works: docker run, Podman, nerdctl — Docker Compose is optional.

Also on Docker Hub: the same images are mirrored to aliasunder/vault-cortex. GHCR is the primary source; Hub tags are identical.

Cost: A remote setup needs a VPS or a hosted platform plan, plus $4 USD/mo for Obsidian Sync. A 2 GiB instance handles semantic search fine for a typical vault; 4 GiB adds headroom for concurrent search and larger vaults. Skip semantic search entirely to go smaller still. Local-only is free. The reference AWS deployment runs ~$17–29 USD/mo all-in.

One-click deploy

Buttons and prerequisites are in Quick Start → Remote. Each guide walks through the deploy, where to find your URL and token, how to update, and how to delete: deploy/render/ (from the render.yaml Blueprint at the repo root) · deploy/railway/ (from a published template).

Community deployments

Deployment templates built and maintained by the community — not tested here, and they may lag behind releases.

vault-cortex-aca — Bicep template for Azure Container Apps by @flytzen. Runs the :remote image behind Container Apps ingress with free managed HTTPS; storage is deliberately ephemeral, with Obsidian Sync as the source of truth.

Built a deployment for another platform? Open a PR to add it here.

Development

# Run locally with hot reload
PUBLIC_URL=http://localhost:8000 MCP_AUTH_TOKEN=local-dev-token VAULT_PATH=~/Vault npm run dev:mcp

# Tests
npm test

# Full check suite
npm run prettier:check && npm run lint && npm run markdownlint && npm run lint:shell && npm run knip && npm test && npm run build

npm test includes integration tests that boot a real server and call every tool and prompt over HTTP — verifying auth enforcement, config-gated tool surfaces, write mutation integrity (each write is read back), and boot rejection on misconfiguration. See SECURITY.md for the security-relevant coverage.

MCP Inspector — interactive browser UI for testing tools:

# Start server (terminal 1), then:
npx @modelcontextprotocol/inspector
# Enter http://localhost:8000/mcp as URL, local-dev-token as Bearer token

See CONTRIBUTING.md for the full development setup.

Companion: obsidian-vault skill

The MCP server works on its own with any client. For agents that support skills (Claude Code, Cursor, Windsurf, Cline, and 70+ others), the obsidian-vault skill adds deeper knowledge of Obsidian-flavored markdown — frontmatter conventions, callout syntax, and plugin-specific formats like Dataview, Tasks, and Kanban.

npx skills add aliasunder/agent-skills --skill obsidian-vault

Skill source →

Roadmap

Planned work, what's being explored, and explicit non-goals live in ROADMAP.md.

Acknowledgments

Obsidian sync is powered by obsidian-headless — containerization approach inspired by @Belphemur's obsidian-headless-sync-docker. The :remote image's s6-overlay supervision scaffolding was absorbed from that project's maintained fork and now lives in this repo.

The hybrid search pipeline draws on patterns from @tobi's qmd — RRF fusion with rank bonuses, position-aware score blending for cross-encoder reranking, content-hash gating, and heading-aware chunking.

Contributing

See CONTRIBUTING.md for development setup, code conventions, and PR guidelines.

License

MIT

The :remote image bundles obsidian-headless (the ob CLI), which is proprietary — its package.json declares "license": "UNLICENSED" (© Dynalist Inc. / Obsidian). It is installed from public npm at build time; the MIT license here does not cover it, and using it requires an active Obsidian Sync subscription. The :latest (local) image contains no proprietary components.

Security

Report vulnerabilities privately — see SECURITY.md.

Vault Cortex

Add this server

Tools

Questions

Host a copy with our keys and logs.

Server facts

How do I install Vault Cortex?

Does Vault Cortex need an API key?

What transport does Vault Cortex use?

When was Vault Cortex last checked?

Documentation

What you get

Quick Start

Local (2 minutes — Docker + your vault folder)

Remote (access from anywhere)

Self-hosted: your own VPS

Connect your MCP client

How It Works

Hybrid Search

Memory

Tasks

Files

Tools

Prompts

Properties

Configuration

Daily notes

Data Integrity

Authentication

Deployment Options

One-click deploy

Community deployments

Development

Companion: obsidian-vault skill

Roadmap

Acknowledgments

Contributing

License

Security