vault-cortex

Vault Cortex is a standalone MCP (Model Context Protocol) server that provides AI agents with hybrid search, task management, structured memory, and read/write access to Obsidian vaults. It operates directly on `.md` files on disk, requiring no Obsidian plugins or running instance. The server runs in a single Docker container and can be deployed locally, self-hosted on a VPS, or via one-click deployment on Railway or Render for remote access. **Key Features:** - **Hybrid Search**: Combines FTS5 keyword matching with vector semantic similarity via Reciprocal Rank Fusion (RRF), refined by cross-encoder reranking for intent-heavy queries. All models run locally (~45MB total, no external API). - **Structured Memory**: An append-only, dated entry system stored in plain Markdown files (default `About Me/` folder). Topic recall retrieves relevant entries across all memory files, showing current state and historical evolution. Supports `entry-policy: living` for prunable current-state entries. - **Task Management**: Kanban-aware task queries and updates. Supports filtering by status, dates, priority, folder, or lane. Handles both Tasks plugin emoji signifiers and Dataview inline-field formats. Completing recurring tasks spawns next occurrences; supports "On completion" actions. - **File Access**: Reads non-markdown files including images (downscaled server-side), PDFs (text extraction or rendered pages), canvases (readable outlines), and data files (TXT, SVG, JSON, XML, CSV, YAML, logs, Bases). - **Link Graph**: Backlinks, outgoing links, and orphan detection across the vault. - **Obsidian-Native**: Understands frontmatter, wikilinks, tags, headings, and daily notes. - **Guided Workflows**: Built-in prompts for vault health, memory review, and daily reconciliation, assembled from live vault data. **Authentication**: Supports OAuth 2.1 for remote access with consent pages, plus Bearer token for clients without OAuth. Token renewal is handled automatically for OAuth clients. **Deployment Options**: - Local: Docker + vault folder, set up via `npx vault-cortex@latest init` - Remote: One-click deploy on Railway or Render, or self-hosted on any Linux VPS with Docker - Remote deployments use Obsidian Sync to keep the vault current across devices **Setup**: The CLI manages server lifecycle (`configure`, `upgrade`, `start`, `restart`, `logs`, `down`). Manual Docker Compose setup is also available. A setup page at `/setup` handles Obsidian Sync sign-in for remote deployments. **Security**: Includes CI with Gitleaks and Trivy scans, OpenSSF Scorecard and Best Practices badges. The vault remains the source of truth in plain Markdown; the container only holds a copy. **Use Cases**: Tested across a 15-day trip through Europe with 30+ sessions from a phone, 216 tool calls, zero laptop access. Writes in one session were immediately available in the next across cities and days.