Vault Cortex MCP server
2026년 11월 15일 커밋AI agent에게 하이브리드 검색, 작업 관리, 구조화된 메모리 기능을 제공하며, 플러그인 없이 Obsidian vault에 대한 읽기/쓰기 권한을 부여합니다.
다른 이름 aliasunder/vault-cortex, vault-cortex
- 스타
- 38
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- 0.57.6
- 마지막 커밋
- 2026년 11월 15일
- 라이선스
- MIT
Vault Cortex MCP란?
Vault Cortex은(는) MCP server입니다. AI agent에게 하이브리드 검색, 작업 관리, 구조화된 메모리 기능을 제공하며, 플러그인 없이 Obsidian vault에 대한 읽기/쓰기 권한을 부여합니다.
프로젝트 README에서 생성된 요약
Vault Cortex MCP server 정보
Vault Cortex는 Obsidian 사용자가 AI agent를 통해 개인 지식과 작업을 관리할 수 있도록 지원합니다. 이 독립형 MCP server는 Obsidian 애플리케이션을 실행하거나 특정 플러그인을 설치할 필요 없이 markdown 파일에 대한 읽기 및 쓰기 권한을 제공합니다. AI client가 디스크에 있는 vault 파일과 직접 상호작용할 수 있도록 돕는 headless 브리지 역할을 수행합니다.
사용자는 Docker를 사용하여 서버를 로컬에 배포하거나 Railway, Render 또는 개인 VPS와 같은 플랫폼에 원격으로 호스팅할 수 있습니다. 원격 설정 시 Obsidian Sync를 사용하여 vault를 최신 상태로 유지하며, 모바일 기기나 웹 기반 client에서의 안전한 접속을 위해 OAuth 2.1을 사용합니다. 이 서버는 키워드 매칭과 벡터 의미론적 유사성을 결합한 하이브리드 검색과 시간 경과에 따른 생각의 변화를 추적하는 구조화된 메모리를 위한 특화된 도구를 포함합니다. 또한 Kanban 기반 작업 관리를 지원하며 PDF 및 이미지와 같은 non-markdown 파일도 처리할 수 있습니다.
활용 사례
- 1과거 지식 검색AI에게 과거 노트에 기록된 특정 세부 사항이나 변화해 온 의견을 찾아달라고 요청합니다.
- 2복잡한 작업 목록 관리AI에게 작업을 분류, 우선순위 재설정 또는 서로 다른 Kanban 레인 사이로 이동하도록 지시합니다.
- 3심층 콘텐츠 검색정확한 용어가 기억나지 않더라도 의미론적 유사성을 사용하여 노트를 찾습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
Vault Cortex MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 Vault Cortex MCP 설치
$ claude mcp add --env 'MCP_AUTH_TOKEN=<YOUR_MCP_AUTH_TOKEN>' vault-cortex -- docker run -i --rm ghcr.io/aliasunder/vault-cortex:0.57.6Cursor에 Vault Cortex MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"vault-cortex": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/aliasunder/vault-cortex:0.57.6"
],
"env": {
"MCP_AUTH_TOKEN": "<YOUR_MCP_AUTH_TOKEN>"
}
}
}
}VS Code에 Vault Cortex MCP 설치
.vscode/mcp.json
{
"servers": {
"vault-cortex": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/aliasunder/vault-cortex:0.57.6"
],
"env": {
"MCP_AUTH_TOKEN": "<YOUR_MCP_AUTH_TOKEN>"
}
}
}
}VS Code CLI에 Vault Cortex MCP 설치
$ code --add-mcp '{"name":"vault-cortex","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/aliasunder/vault-cortex:0.57.6"],"env":{"MCP_AUTH_TOKEN":"<YOUR_MCP_AUTH_TOKEN>"}}'Claude Desktop에 Vault Cortex MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"vault-cortex": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/aliasunder/vault-cortex:0.57.6"
],
"env": {
"MCP_AUTH_TOKEN": "<YOUR_MCP_AUTH_TOKEN>"
}
}
}
}Codex에 Vault Cortex MCP 설치
$ codex mcp add vault-cortex --env 'MCP_AUTH_TOKEN=<YOUR_MCP_AUTH_TOKEN>' -- docker run -i --rm ghcr.io/aliasunder/vault-cortex:0.57.6Codex config.toml에 Vault Cortex MCP 설치
~/.codex/config.toml
[mcp_servers.vault-cortex] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/aliasunder/vault-cortex:0.57.6"] [mcp_servers.vault-cortex.env] MCP_AUTH_TOKEN = "<YOUR_MCP_AUTH_TOKEN>"
Gemini CLI에 Vault Cortex MCP 설치
$ gemini mcp add -s user -e 'MCP_AUTH_TOKEN=<YOUR_MCP_AUTH_TOKEN>' vault-cortex docker -- run -i --rm ghcr.io/aliasunder/vault-cortex:0.57.6Gemini settings.json에 Vault Cortex MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"vault-cortex": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/aliasunder/vault-cortex:0.57.6"
],
"env": {
"MCP_AUTH_TOKEN": "<YOUR_MCP_AUTH_TOKEN>"
}
}
}
}구성
MCP_AUTH_TOKEN필수비밀Bearer token for MCP client authentication. Must match the Authorization header sent by clients. Generate with: openssl rand -hex 32
DAILY_NOTES_FOLDERVault folder for daily notes. Overrides the folder configured in Obsidian's daily-notes plugin. When unset, read from the vault's .obsidian/daily-notes.json (an empty folder there follows Obsidian's new-note location), falling back to "Daily Notes" when that file is missing or unreadable. Set to / for the vault root.
DAILY_NOTES_FORMATFilename date format for daily notes (Moment.js tokens). Overrides the format configured in Obsidian's daily-notes plugin. When unset, read from the vault's .obsidian/daily-notes.json, falling back to "YYYY-MM-DD".
DISABLED_TOOLSHide individual tools by name, comma-separated. Subtractive only — it cannot re-enable a tool another setting hides; an unknown tool name stops the server at startup.
EMBEDDING_ENABLEDEnable or disable the embedding pipeline. When false, no ONNX model is downloaded, no vector tables are created, and search uses FTS5 only.
FILE_TOOLS_ENABLEDEnable or disable file tools (vault_read_file, vault_list_files). When false, file tools are hidden and server metadata omits file tool references.
LOG_DIRDirectory for log files that survive container re-creation. The container's own log is always written but discarded when the container is recreated; date-stamped files under LOG_DIR persist on the data volume. Default: /data/logs (remote image), $STORAGE_ROOT/data/logs (single-volume mode), none (local image). none keeps only the container log.
LOG_LEVELLogging verbosity.
LOG_MAX_DAILY_MBMaximum MB per daily log file (1 MB = 1,000,000 bytes). Whole numbers of at least 1, or none to disable the cap. File logging pauses at the cap until midnight in TZ (UTC by default); console logging continues.
LOG_RETENTION_DAYSDays to keep log files; cleanup runs at startup and each day. Only applies when LOG_DIR is a path.
MAX_FILE_BYTESLargest file vault_read_file will read, in bytes. Reading a larger file returns an error instead of content.
MAX_IMAGE_OUTPUT_BYTESByte budget for images returned by vault_read_file, in binary bytes before base64 encoding. Images exceeding the budget are downscaled/recompressed server-side to fit; raise for clients that accept larger tool responses.
MAX_PDF_RENDER_PAGESMaximum PDF pages to render as images when raw: true is set on vault_read_file. The per-page byte budget is MAX_IMAGE_OUTPUT_BYTES divided evenly across the rendered pages.
MEMORY_DIRVault folder for structured memory files (About Me-style notes). Memory tools are hidden when MEMORY_ENABLED is false, but this value still feeds the defaults for PROTECTED_PATHS and ORPHAN_EXCLUDE_FOLDERS.
MEMORY_ENABLEDEnable or disable the structured memory layer. When false, memory tools are hidden, bootstrap is skipped, and server metadata omits memory references.
ORPHAN_EXCLUDE_FOLDERSComma-separated vault folder names excluded from vault_find_orphans. Default: the daily notes folder, "Templates", and MEMORY_DIR. DAILY_NOTES_FOLDER wins; otherwise .obsidian/daily-notes.json is read per query (fallback "Daily Notes"; no daily folder when that setting is the vault root or empty). When set, replaces the defaults entirely. Set to a comma (,) to exclude nothing; an empty value uses the defaults.
PROTECTED_PATHSComma-separated vault folder names blocked from vault_delete_note and vault_move_note. Default: MEMORY_DIR plus the daily notes folder, read from DAILY_NOTES_FOLDER or .obsidian/daily-notes.json (default Daily Notes; none when that setting is the vault root or empty). When set, overrides the default entirely.
PUBLIC_URLPublic URL clients use to reach this server. Used as the OAuth issuer URL in discovery metadata. Override when exposing the server outside localhost or on a non-default port.
READONLY_MODERun the server read-only: every vault-writing tool is hidden, the memory folder is not auto-created, and server metadata omits write references.
RERANK_MODECross-encoder reranking mode: blended (position-aware score blending after RRF fusion) or none (skip reranking). Only takes effect when EMBEDDING_ENABLED is true.
SERVICE_DOCUMENTATION_URLOverride the OAuth service documentation URL exposed via discovery metadata.
TRUST_FORWARDED_HOPSHow many entries from the end of the RFC 7239 Forwarded header's for= list to count to reach the client IP for OAuth rate limiting and request logs. 0 ignores the header; 1 when the proxy in front writes it (e.g. AWS API Gateway) and is the only way to reach the server; 2 when a CDN fronts that proxy and is the only way to reach it.
TRUST_PROXY_HOPSNumber of trusted reverse-proxy hops used to derive the client IP from X-Forwarded-For for OAuth rate limiting and request logs. With 0, injected forwarding headers are ignored.
TZIANA timezone for timestamps and daily note resolution.
WINDOWS_MODEWindows bind-mount mode: enables filesystem polling for the file watcher and rename-based moves across the Docker Desktop/WSL2 bridge. Set to true when the vault lives on a Windows drive.
| 이름 | 설명 | 유형 |
|---|---|---|
| MCP_AUTH_TOKEN | Bearer token for MCP client authentication. Must match the Authorization header sent by clients. Generate with: openssl rand -hex 32 | 필수비밀 |
| DAILY_NOTES_FOLDER | Vault folder for daily notes. Overrides the folder configured in Obsidian's daily-notes plugin. When unset, read from the vault's .obsidian/daily-notes.json (an empty folder there follows Obsidian's new-note location), falling back to "Daily Notes" when that file is missing or unreadable. Set to / for the vault root. | |
| DAILY_NOTES_FORMAT | Filename date format for daily notes (Moment.js tokens). Overrides the format configured in Obsidian's daily-notes plugin. When unset, read from the vault's .obsidian/daily-notes.json, falling back to "YYYY-MM-DD". | |
| DISABLED_TOOLS | Hide individual tools by name, comma-separated. Subtractive only — it cannot re-enable a tool another setting hides; an unknown tool name stops the server at startup. | |
| EMBEDDING_ENABLED | Enable or disable the embedding pipeline. When false, no ONNX model is downloaded, no vector tables are created, and search uses FTS5 only. | |
| FILE_TOOLS_ENABLED | Enable or disable file tools (vault_read_file, vault_list_files). When false, file tools are hidden and server metadata omits file tool references. | |
| LOG_DIR | Directory for log files that survive container re-creation. The container's own log is always written but discarded when the container is recreated; date-stamped files under LOG_DIR persist on the data volume. Default: /data/logs (remote image), $STORAGE_ROOT/data/logs (single-volume mode), none (local image). none keeps only the container log. | |
| LOG_LEVEL | Logging verbosity. | |
| LOG_MAX_DAILY_MB | Maximum MB per daily log file (1 MB = 1,000,000 bytes). Whole numbers of at least 1, or none to disable the cap. File logging pauses at the cap until midnight in TZ (UTC by default); console logging continues. | |
| LOG_RETENTION_DAYS | Days to keep log files; cleanup runs at startup and each day. Only applies when LOG_DIR is a path. | |
| MAX_FILE_BYTES | Largest file vault_read_file will read, in bytes. Reading a larger file returns an error instead of content. | |
| MAX_IMAGE_OUTPUT_BYTES | Byte budget for images returned by vault_read_file, in binary bytes before base64 encoding. Images exceeding the budget are downscaled/recompressed server-side to fit; raise for clients that accept larger tool responses. | |
| MAX_PDF_RENDER_PAGES | Maximum PDF pages to render as images when raw: true is set on vault_read_file. The per-page byte budget is MAX_IMAGE_OUTPUT_BYTES divided evenly across the rendered pages. | |
| MEMORY_DIR | Vault folder for structured memory files (About Me-style notes). Memory tools are hidden when MEMORY_ENABLED is false, but this value still feeds the defaults for PROTECTED_PATHS and ORPHAN_EXCLUDE_FOLDERS. | |
| MEMORY_ENABLED | Enable or disable the structured memory layer. When false, memory tools are hidden, bootstrap is skipped, and server metadata omits memory references. | |
| ORPHAN_EXCLUDE_FOLDERS | Comma-separated vault folder names excluded from vault_find_orphans. Default: the daily notes folder, "Templates", and MEMORY_DIR. DAILY_NOTES_FOLDER wins; otherwise .obsidian/daily-notes.json is read per query (fallback "Daily Notes"; no daily folder when that setting is the vault root or empty). When set, replaces the defaults entirely. Set to a comma (,) to exclude nothing; an empty value uses the defaults. | |
| PROTECTED_PATHS | Comma-separated vault folder names blocked from vault_delete_note and vault_move_note. Default: MEMORY_DIR plus the daily notes folder, read from DAILY_NOTES_FOLDER or .obsidian/daily-notes.json (default Daily Notes; none when that setting is the vault root or empty). When set, overrides the default entirely. | |
| PUBLIC_URL | Public URL clients use to reach this server. Used as the OAuth issuer URL in discovery metadata. Override when exposing the server outside localhost or on a non-default port. | |
| READONLY_MODE | Run the server read-only: every vault-writing tool is hidden, the memory folder is not auto-created, and server metadata omits write references. | |
| RERANK_MODE | Cross-encoder reranking mode: blended (position-aware score blending after RRF fusion) or none (skip reranking). Only takes effect when EMBEDDING_ENABLED is true. | |
| SERVICE_DOCUMENTATION_URL | Override the OAuth service documentation URL exposed via discovery metadata. | |
| TRUST_FORWARDED_HOPS | How many entries from the end of the RFC 7239 Forwarded header's for= list to count to reach the client IP for OAuth rate limiting and request logs. 0 ignores the header; 1 when the proxy in front writes it (e.g. AWS API Gateway) and is the only way to reach the server; 2 when a CDN fronts that proxy and is the only way to reach it. | |
| TRUST_PROXY_HOPS | Number of trusted reverse-proxy hops used to derive the client IP from X-Forwarded-For for OAuth rate limiting and request logs. With 0, injected forwarding headers are ignored. | |
| TZ | IANA timezone for timestamps and daily note resolution. | |
| WINDOWS_MODE | Windows bind-mount mode: enables filesystem polling for the file watcher and rename-based moves across the Docker Desktop/WSL2 bridge. Set to true when the vault lives on a Windows drive. |
자동 검사
2026년 11월 13일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능aliasunder/vault-cortex is public and reachablegithub.com/aliasunder/vault-cortex ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-13github.com/aliasunder/vault-cortex ↗통과
- OpenSSF ScorecardOpenSSF Scorecard 8.0 / 10; weakest: Code-Review 0, Fuzzing 0, Contributors 3scorecard.dev/viewer/?uri=github.com/aliasunder/vault-cortex ↗통과
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기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
- Remote access — works from your phone, a remote server, or any MCP client via OAuth 2.1. One click on Render or Railway gets you there with no server to manage; a VPS works too.
- Plugin-free — Obsidian doesn't need to be running. The server works directly with
.mdfiles on disk. Headless sync keeps the vault current. - Hybrid search — FTS5 keyword matching + vector semantic similarity via RRF fusion, refined by cross-encoder reranking for intent-heavy queries. Keywords stay precise on exact terms and jargon; vectors find notes even when your words differ from the vault's.
- Structured memory — dated, append-only entries accumulate into a personal knowledge layer, auto-initialized for AI personalization. Topic recall answers "what do I think about X?" with the current take and the dated history behind it — evolution included.
- Tasks — Kanban-aware task queries and updates: triage by status, dates, or priority, then complete, reprioritize, or move tasks between lanes in one call. Completing a recurring task spawns its next occurrence. Parses both Tasks plugin emoji and Dataview inline-field formats.
- Link graph — backlinks, outgoing links, and orphan detection across the vault
- Files — read the vault's non-markdown files too: images arrive as actual images (shrunk to fit when needed), PDFs as structured text or rendered pages, canvases as readable outlines, data files, HTML pages, and scripts as text
- 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 each time
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 (~59MB 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_recallretrieves 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.
Vault Cortex MCP 질문
Vault Cortex MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add --env 'MCP_AUTH_TOKEN=<YOUR_MCP_AUTH_TOKEN>' vault-cortex -- docker run -i --rm ghcr.io/aliasunder/vault-cortex:0.57.6를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
Vault Cortex MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
Vault Cortex를 사용하려면 Obsidian이 실행 중이어야 하나요?
아니요. 디스크에 있는 markdown 파일을 직접 처리하므로 Obsidian 앱이 실행 중일 필요는 없습니다.
Vault Cortex는 Obsidian vault를 어떻게 검색하나요?
FTS5 키워드 매칭과 RRF fusion을 통한 벡터 의미론적 유사성을 결합한 뒤, cross-encoder로 검색 결과를 재순위화합니다.
Vault Cortex를 로컬에 어떻게 설정하나요?
npx로 init 명령어를 실행하세요. CLI에서 vault 경로를 요청하며, 설정 파일과 토큰을 생성한 뒤 서버를 시작합니다.
휴대폰에서 원격으로 vault에 접속할 수 있나요?
네. Railway, Render 또는 개인 VPS에 배포하여 어떤 MCP client에서도 접속할 수 있으며, OAuth 2.1으로 보안을 유지합니다.
Vault Cortex가 작업 관리를 지원하나요?
네. 상태, 날짜 또는 우선순위에 따라 Kanban 기반 작업을 조회하고 업데이트하며, 반복 작업의 다음 일정을 생성할 수 있습니다.