Overview

Relevant source files

• .devin/wiki.json
• .github/scripts/update-changelog.sh
• AGENTS.md
• ARCHITECTURE.md
• CHANGELOG.md
• README.md
• cli/package.json
• package-lock.json
• package.json
• server.json

Vault Cortex is a standalone, remote-capable Model Context Protocol (MCP) server that provides AI assistants with hybrid search, task management, structured memory, and bidirectional read/write access to Obsidian vaults.

Unlike traditional integrations that require the Obsidian desktop application to be running alongside a REST API plugin, Vault Cortex operates directly on the filesystem. It runs headless in Docker, making your personal knowledge base accessible from any MCP-compatible client (such as Claude Desktop, Claude Code, or Cursor) across mobile and desktop devices via HTTPS ARCHITECTURE.md3-6 It is listed on the official MCP server registry and provides a full tool suite plus guided prompts README.md18-20

Value Proposition

Vault Cortex packs the entire vault-to-agent chain into one always-on Docker container. It replaces the typical Obsidian + MCP setup — a local-only chain involving Obsidian running, the Local REST API plugin, and a separate MCP server wrapping that API ARCHITECTURE.md21-34

Key Capabilities

• Plugin-Free & Headless: Works directly with .md files on disk. No Obsidian instance or plugins required at runtime README.md40
• Hybrid Search Engine: FTS5 keyword matching fused with sqlite-vec vector KNN via Reciprocal Rank Fusion (RRF), refined by cross-encoder reranking (ms-marco-MiniLM-L-6-v2) for intent-heavy queries README.md41 server.json79-88
• Kanban-Aware Task Management: A vault-wide task index parsing both Tasks plugin emoji and Dataview inline-field formats. Supports structured filters across status, dates, and priority README.md43 ARCHITECTURE.md143-144
• Structured Memory Layer: A heading-aware "About Me/" system for AI personalization, supporting dated bullet entries and entry-granular hybrid retrieval README.md42 server.json95-108
• Non-Markdown File Reading: Direct access to images (with server-side downscaling), PDFs (text extraction or rendered pages), JSON Canvases (linearized outlines), and data files README.md45 server.json100-103
• OAuth 2.1 Authentication: Implements OAuth 2.1 with JWT tokens to protect personal notes during remote access ARCHITECTURE.md58 server.json5
• Comprehensive Security: Maintained with a rigorous toolchain including OpenSSF Scorecard, Trivy (containers), Gitleaks (secrets), and CodeQL (SAST) README.md7-12

System Architecture

Vault Cortex is structured into four internal layers that separate domain knowledge from protocol implementation and I/O AGENTS.md102-124

Natural Language to Code Entity Mapping

The following diagrams map high-level AI capabilities to the specific code entities that implement them.

NL Space to Code Entity Space: Search & Discovery

Sources: ARCHITECTURE.md118-121 ARCHITECTURE.md143-144

NL Space to Code Entity Space: Content & Memory

Sources: ARCHITECTURE.md47 server.json95-108

High-Level Data Flow

Data Flow: MCP Request to Vault Filesystem

Sources: ARCHITECTURE.md63-108 server.json46-65

Implementation Layers

1. obsidian-markdown/ (Pure Parsers)

This layer contains pure functions for parsing Obsidian-flavored Markdown with no I/O AGENTS.md108-111

• Link Engine: Resolution for wikilinks, markdown links, embeds, and relative paths.
• Grammar Parsers: Specialized parsers for callouts, H1-H6 headings, and memory-entry dated bullets.
• Task Parser: Faithful reimplementation of the Tasks plugin parser and Dataview fields.
• Canvas Linearizer: JSON Canvas 1.0 parser that produces a readable outline for AI agents.

2. vault-operations/ (Filesystem I/O)

The layer that reads, writes, and transforms vault content using safety primitives AGENTS.md112-116

• Atomic Writes: Temp-then-rename strategies to prevent data loss.
• Surgical Patching: Heading-targeted edits (prepend/append/replace) and vault-wide link rewriting.
• File Operations: Read dispatch for non-markdown files, including image downscaling and PDF text extraction.

3. search/ (Indexing & Retrieval)

• Hybrid Index: SQLite factory managing FTS5, sqlite-vec, and dedicated tasks tables AGENTS.md117-120
• Embedding Pipeline: Local ONNX pipeline for bge-small-en-v1.5 with content-hash gating.
• File Watcher: Chokidar-based watcher that keeps the index and embeddings current on every file change.

4. mcp-core/ (Protocol Surface)

Exposes the internal logic to MCP clients via tools and prompts AGENTS.md121-124

• Tool Orchestrator: Composes domain-grouped tools (CRUD, Search, Memory, Tasks, Daily Note, Files).
• Guided Prompts: Assembles real-time vault data into actionable context (e.g., vault-orientation).

Deployment Modes

Vault Cortex supports three primary deployment paths, all running the vault-cortex Docker image AGENTS.md7-17:

1. Local Docker: Bind-mounts a local vault folder to a single container README.md53-87
2. Remote with Obsidian Sync: Uses the :remote image tag which bundles the MCP server and Obsidian Sync under s6-overlay supervision for mobile/remote access README.md89-107
3. AWS Reference: Full defense-in-depth deployment with API Gateway, Lambda authorizer, and Lightsail containers, scaffolded by SST ARCHITECTURE.md37-40

The CLI (npx vault-cortex@latest init) provides the fastest path to a working setup for all modes README.md58-61 cli/package.json4

Sources: README.md18-20 ARCHITECTURE.md24-31 server.json13-162 AGENTS.md7-17