vault-cortex

<p align="center">
  <img src="./assets/banner.svg" width="720" alt="Vault Cortex">
</p>

<div align="center">

[![CI](https://img.shields.io/github/actions/workflow/status/aliasunder/vault-cortex/ci.yml?branch=main&logo=github&label=CI&cacheSeconds=43200)](https://github.com/aliasunder/vault-cortex/actions/workflows/ci.yml)
[![Gitleaks](https://img.shields.io/github/actions/workflow/status/aliasunder/vault-cortex/gitleaks.yml?branch=main&logo=github&label=Gitleaks&cacheSeconds=43200)](https://github.com/aliasunder/vault-cortex/actions/workflows/gitleaks.yml)
[![Trivy](https://img.shields.io/github/actions/workflow/status/aliasunder/vault-cortex/trivy.yml?branch=main&logo=github&label=Trivy&cacheSeconds=43200&v=1)](https://github.com/aliasunder/vault-cortex/actions/workflows/trivy.yml)
[![GitHub Release](https://img.shields.io/github/v/release/aliasunder/vault-cortex?cacheSeconds=43200)](https://github.com/aliasunder/vault-cortex/releases)
[![License: MIT](https://img.shields.io/github/license/aliasunder/vault-cortex?v=1&cacheSeconds=43200)](https://github.com/aliasunder/vault-cortex/blob/main/LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D24-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-6-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)

</div>

<div align="center">

[![vault-cortex MCP server](https://glama.ai/mcp/servers/aliasunder/vault-cortex/badges/card.svg)](https://glama.ai/mcp/servers/aliasunder/vault-cortex)

</div>

<!-- TODO: Uncomment when demo GIF is recorded (see ^demo-gif task)
<p align="center">
  <img src="./assets/demo.gif" width="600" alt="Vault Cortex demo — vault_get_memory and vault_update_memory round-trip">
</p>
-->

## What is this?

**Vault Cortex** gives any MCP client — Claude Desktop, Claude Code, Cursor, OpenCode — full access to your [Obsidian](https://obsidian.md) vault. Search notes, read and write content, query the link graph, manage structured memory, and resolve daily notes — all through 23 tools over a single Docker container.

The typical Obsidian + MCP setup requires three moving parts running simultaneously: Obsidian open → Local REST API plugin → a separate MCP server wrapping the REST API. **Vault Cortex** replaces all of that with Docker and your vault folder.

- **Plugin-free** — Obsidian doesn't need to be running; headless sync keeps the vault current, and the server works directly with `.md` files on disk
- **Remote access** — works from your phone, a remote server, or any MCP client via OAuth 2.1
- **Ranked search** — SQLite FTS5 with BM25 scoring, stemming, phrase matching, and tag/property/folder filtering
- **Structured memory** — dated entries, section targeting, auto-initialization for AI personalization
- **Obsidian-native** — understands frontmatter, wikilinks, tags, headings, and daily notes

### Roadmap

| Phase | What                                                                                | Status   |
| ----- | ----------------------------------------------------------------------------------- | -------- |
| **1** | Vault CRUD, full-text search (FTS5), memory layer, OAuth 2.1                        | Complete |
| **2** | Semantic search + knowledge graph via [LightRAG](https://github.com/HKUDS/LightRAG) | Planned  |

## Quick Start

### Local (2 minutes — Docker + your vault folder)

**Prerequisites:** [Docker](https://docs.docker.com/get-docker/), Node.js >= 20.12 (only for the CLI — the server itself runs in Docker), and an Obsidian vault (or any folder of `.md` files).

```bash
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.

<details>
<summary><strong>Manual setup</strong> (no Node.js needed)</summary>

```bash
# 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
```

</details>

**[Full local guide →](./deploy/local/)**

### Remote (access from anywhere — Docker + Obsidian Sync)

**Prerequisites:** a VPS with [Docker](https://docs.docker.com/engine/install/), an [Obsidian Sync](https://obsidian.md/sync) subscription, and Node.js >= 20.12 (only for the CLI — the server itself runs in Docker).

```bash
# 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 the token generator for you), and auth config, then starts the server.

<details>
<summary><strong>Manual setup</strong> (no Node.js needed)</summary>

```bash
# 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, OBSIDIAN_AUTH_TOKEN, VAULT_NAME
docker compose up -d
```

</details>

**[Full remote guide →](./deploy/remote/)**

### Connect your MCP client

| Setup      | Server URL                  |
| ---------- | --------------------------- |
| **Local**  | `http://localhost:8000/mcp` |
| **Remote** | `<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:**

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

**Claude Desktop:** the "Add custom connector" dialog only accepts `https` URLs. With an `https` PUBLIC_URL, add it directly in the connector dialog; for a localhost server, register it in `claude_desktop_config.json` through the [mcp-remote](https://github.com/geelen/mcp-remote) stdio bridge instead:

```json
{
  "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](#authentication) for both methods and token lifetimes.

## Tools (23)

| Category        | Tool                         | Description                                              |
| --------------- | ---------------------------- | -------------------------------------------------------- |
| **Vault CRUD**  | `vault_read_note`            | Read a note by path                                      |
|                 | `vault_write_note`           | Create or overwrite a note with frontmatter              |
|                 | `vault_patch_note`           | Heading-targeted edit (append, prepend, replace, insert) |
|                 | `vault_replace_in_note`      | Find-and-replace text in a note                          |
|                 | `vault_list_notes`           | List notes with optional glob/folder filter              |
|                 | `vault_delete_note`          | Delete a note (protected paths enforced)                 |
| **Search**      | `vault_search`               | Full-text 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                               |
| **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 frontmatter keys with sample values                  |
|                 | `vault_list_property_values` | Distinct values for a property key                       |
|                 | `vault_search_by_property`   | Find notes by frontmatter 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                       |

## Configuration

All settings are environment variables with sensible defaults.

| Variable                    | Required?   | Default                              | Description                                                             |
| ------------------------