Vault Cortex

Vault Cortex는 모든 AI 에이전트에게 Obsidian 볼트에 대한 하이브리드 검색, 작업 관리, 구조화된 메모리, 읽기/쓰기 액세스를 제공하는 독립형 MCP 서버입니다. 플러그인도, 실행 중인 Obsidian도, 별도의 브리지도 필요 없습니다. Docker 컨테이너 하나, 볼트 폴더, 전체 도구 모음 + 가이드 프롬프트만 있으면 됩니다. Obsidian Sync와 함께 VPS에 배포하면 같은 볼트를 휴대폰, claude.ai 또는 원격 MCP 클라이언트 어디서든 OAuth 2.1로 보호된 상태로 접근할 수 있습니다.

목차 — 제공 기능 · 빠른 시작 · 작동 방식 · 하이브리드 검색 · 메모리 · 작업 · 파일 · 도구 · 프롬프트 · 속성 · 설정 · 데일리 노트 · 데이터 무결성 · 인증 · 배포 · 커뮤니티 배포

제공 기능

• 원격 액세스 — OAuth 2.1을 통해 휴대폰, 원격 서버 또는 모든 MCP 클라이언트에서 작동합니다. Obsidian Sync와 함께 VPS에 배포하면 어디서나 접근할 수 있습니다.

• 플러그인 불필요 — Obsidian이 실행 중일 필요가 없습니다. 서버는 디스크의 .md 파일과 직접 작동합니다. 헤드리스 동기화가 볼트를 최신 상태로 유지합니다.

• 하이브리드 검색 — FTS5 키워드 매칭 + RRF 융합을 통한 벡터 의미 유사도, 의도 중심 쿼리는 교차 인코더 재순위화로 정밀도를 높입니다. 키워드는 정확한 용어와 전문 용어에서 정밀도를 유지하고, 벡터는 볼트의 단어와 다른 표현을 사용해도 노트를 찾아냅니다.

• 구조화된 메모리 — 날짜가 기록된 추가 전용 항목이 개인 지식 계층으로 축적되며, AI 개인화를 위해 자동 초기화됩니다. 주제 회상은 "X에 대해 어떻게 생각하나요?"라는 질문에 현재 관점과 그 뒤에 있는 날짜별 이력을 포함해 답합니다 — 진화 과정까지 포함됩니다.

• 작업 — 칸반 인식 작업 쿼리 및 업데이트: 상태, 날짜 또는 우선순위로 분류한 다음 한 번의 호출로 작업을 완료, 우선순위 변경 또는 레인 간 이동할 수 있습니다. Tasks 플러그인 이모지와 Dataview 인라인 필드 형식을 모두 파싱합니다.

• 링크 그래프 — 볼트 전체의 역링크, 외부 링크, 고아 노트 감지

• 파일 — 마크다운이 아닌 파일도 읽습니다: 이미지는 실제 이미지로 제공되고(필요 시 크기 축소), PDF는 구조화된 텍스트 또는 렌더링된 페이지로, 캔버스는 읽기 가능한 개요로, 데이터 파일은 텍스트로 제공됩니다

• Obsidian 네이티브 — frontmatter, wikilink, 태그, 제목, 데일리 노트를 이해합니다

• 가이드 워크플로 — 볼트 상태 점검, 메모리 검토, 일일 조정을 위한 내장 프롬프트 — 매번 실시간 볼트 데이터로 구성됩니다

유럽 15일 여행에서 테스트 완료. 휴대폰에서 30개 이상의 세션, 216회의 도구 호출, 노트북 접근 전혀 불필요. 한 세션에서의 쓰기가 다음 세션에서 즉시 사용 가능했으며, 도시와 날짜를 넘나들며 확인되었습니다.

Related MCP server: Vault MCP Server (mschuchard)

빠른 시작

로컬 (2분 — Docker + 볼트 폴더)

사전 요구사항: Docker (또는 OrbStack, Colima, Podman 같은 Docker 호환 런타임), Node.js >= 20.12 (CLI 전용 — 서버 자체는 Docker에서 실행), 그리고 Obsidian 볼트 (또는 .md 파일 폴더).

npx vault-cortex@latest init

이것으로 끝입니다 — CLI가 볼트 경로를 묻고, 인증 토큰과 설정 파일을 생성하고, 서버를 시작한 다음 MCP 클라이언트용 연결 정보를 출력합니다 (CLI 참조 →).

CLI로 설정하셨나요? 이제부터 CLI가 서버를 관리합니다 — configure, upgrade, start, restart, logs, down (CLI 참조 →).

Compose로 설정하셨나요? 업데이트도 Compose로 계속하세요 (docker compose pull && docker compose up -d) — CLI와 Compose는 컨테이너를 독립적으로 관리합니다.

# 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

전체 로컬 가이드 → (Windows 설정 포함)

원격 (어디서나 접근 — Docker + Obsidian Sync)

사전 요구사항: Docker가 설치된 VPS (또는 Docker 호환 런타임), Obsidian Sync 구독, 그리고 Node.js >= 20.12 (CLI 전용 — 서버 자체는 Docker에서 실행).

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

이것으로 끝입니다 — CLI가 공개 URL, Obsidian Sync 토큰(대신 get-sync-token을 실행해 줄 수 있음), 인증 설정을 안내한 다음 서버를 시작합니다 (CLI 참조 →).

CLI로 설정하셨나요? 이제부터 CLI가 서버를 관리합니다 — configure, upgrade, start, restart, logs, down (CLI 참조 →).

Compose로 설정하셨나요? 업데이트도 Compose로 계속하세요 (docker compose pull && docker compose up -d) — CLI와 Compose는 컨테이너를 독립적으로 관리합니다.

# 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

전체 원격 가이드 →

MCP 클라이언트 연결

Claude Code, Claude Desktop, Cursor, OpenCode 또는 기타 모든 MCP 클라이언트에서 서버 URL을 추가하세요. OAuth 클라이언트는 브라우저에서 동의 페이지를 열고 — 토큰으로 승인하면 이후 클라이언트가 토큰 갱신을 처리합니다. OAuth가 없는 클라이언트(MCP Inspector, 스크립트)는 토큰을 Authorization: Bearer 헤더로 직접 전송합니다.

Claude Code:

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

--scope user는 모든 프로젝트에 서버를 등록합니다. 생략하면 현재 디렉토리에만 적용됩니다.

"Add custom connector" 대화상자는 https URL만 허용합니다. https PUBLIC_URL이 있으면 커넥터 대화상자에 직접 추가하세요. localhost 서버의 경우 mcp-remote stdio 브리지를 통해 claude_desktop_config.json에 등록하세요:

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

claude.ai (웹 및 모바일) 은 원격 설정에만 연결됩니다 — 커넥터가 서버 측에서 가져와지므로 localhost에는 절대 도달할 수 없습니다.

"원격 MCP 서버"는 연결 유형(HTTP)을 의미합니다 — 로컬 설정에서도 서버는 여전히 사용자 머신에서 완전히 실행됩니다.

두 방법과 토큰 수명에 대해서는 인증을 참조하세요.

작동 방식

모든 것이 하나의 Docker 컨테이너에서 실행되며, 디스크의 .md 파일과 직접 작동합니다:

• 볼트가 진실의 원천으로 유지됩니다 — 서버는 Obsidian 앱이 사용하는 것과 동일한 일반 Markdown 파일을 읽고 씁니다.

• 검색은 파생 데이터입니다 — 파일 감시자가 노트가 변경될 때 인덱스(키워드 + 벡터)를 최신 상태로 유지하며, 언제든지 노트에서 재구축할 수 있습니다.

• 원격 이미지는 동기화 루프를 추가합니다 — 번들된 Obsidian Sync 서비스가 컨테이너의 볼트를 모든 기기와 최신 상태로 유지합니다: 휴대폰에서 노트를 편집하면 잠시 후 검색 가능해지고, 에이전트가 노트를 쓰면 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

전체 설계, 인증 흐름 다이어그램, 구성 요소 분석은 ARCHITECTURE.md를 참조하세요.

하이브리드 검색

키워드 검색만으로는 사용자의 어휘가 볼트의 어휘와 일치하지 않을 때 실패합니다 — "aspirations"는 "targets"에 대한 노트를 찾지 못하고, "coworkers"는 "references" 파일을 표시하지 않습니다. 실제 볼트를 대상으로 한 테스트에서 자연어 쿼리의 30%가 키워드만으로는 결과가 없거나 관련성이 없는 결과를 반환했습니다. 하이브리드 검색은 이러한 누락을 제거했습니다 — 벡터가 어휘 격차를 메우고, 재순위화기가 두 신호 모두 약한 의도 중심 쿼리를 구출합니다.

하이브리드 검색은 Reciprocal Rank Fusion을 통해 세 가지 순위 신호를 결합합니다:

• 키워드 (FTS5)는 정확한 용어, 전문 용어, 속성 값에서 정밀도를 유지합니다

• 벡터 (sqlite-vec)는 의미 기반 매칭으로 어휘 격차를 메웁니다

• 재순위화기 (교차 인코더)는 각 쿼리-문서 쌍을 공동으로 점수화하여 순서를 정제합니다 — 키워드와 벡터가 모두 놓치는 의도 중심 쿼리를 구출합니다

모든 모델은 로컬에서 실행됩니다 (총 ~45MB, 외부 API 없음). 키워드 전용 검색은 EMBEDDING_ENABLED=false로, 낮은 지연 시간을 위해 재순위화를 건너뛰려면 RERANK_MODE=none으로 설정하세요.

모델 세부 정보, 혼합 가중치, 전체 파이프라인 분석은 ARCHITECTURE.md → 하이브리드 검색을 참조하세요.

메모리

계속 성장하는 메모리 계층은 에이전트가 모든 것을 컨텍스트에 덤프하지 않고 올바른 항목을 검색할 수 있을 때만 유용합니다. 여러 파일에 걸쳐 수백 개의 날짜별 항목이 쌓이면 — 선호도, 원칙, 커뮤니케이션 스타일, 진행 중인 약속 — 전체 파일을 읽는 것은 관련 없는 자료로 컨텍스트를 낭비하고 신호를 묻어버립니다. 메모리 시스템은 목표 지향적 검색을 위해 설계되었습니다: 에이전트는 시간이 지남에 따라 지식을 축적하고 현재 작업에 정확히 관련된 것만 회상합니다.

이 계층은 주제 제목 아래 날짜별 항목을 담은 일반 Markdown 파일 폴더(기본값: About Me/)입니다 — 첫 실행 시 시작 템플릿과 함께 자동 생성되고, 에이전트가 vault_update_memory를 통해 성장시킵니다. 세 가지 속성이 이를 가능하게 합니다:

• 추가 전용(Append-only) — 항목은 절대 덮어쓰지 않으며, 수정 사항은 새 날짜 항목으로 추가됩니다. 이 레이어는 현재 상태 와 그 뒤에 숨은 변화 과정을 담아내는 개인 지식 기반이 됩니다.

• 주제 회상(Topic recall) — vault_memory_recall은 모든 메모리 파일에서 관련 항목을 한 번에 검색하며, 키워드 및 의미 기반 매칭으로 오래된 순서대로 반환합니다. "X에 대해 어떻게 생각하나요?"라고 물으면 현재 관점과 함께 그것이 어떻게 발전해 왔는지에 대한 날짜별 이력까지 얻을 수 있습니다 — 전체 파일을 읽거나 어떤 파일에 무엇이 있는지 추측할 필요가 없습니다.

• 성능 저하 없이 확장 — 결과 상한(max_results)은 가장 관련성 낮은 항목을 제거할 뿐, 타임라인의 일부를 잘라내지 않습니다. 500개 항목이 있는 메모리 레이어는 50개 항목이 있는 레이어만큼이나 정확하게 특정 질의에 응답합니다.

현재 상태가 아니라 현재 사실을 설명하는 파일(루틴, 진행 중인 약속)은 frontmatter에 entry-policy: living을 선언할 수 있습니다 — 만료된 항목은 보존되는 대신 정리(prunable) 대상이 되어 현재 상태 그림이 정확하게 유지됩니다.

전체 레이어는 선택 사항입니다 — MEMORY_ENABLED=false로 설정하면 메모리 도구를 숨기고 폴더 자동 생성도 건너뜁니다.

회상 파이프라인, 인덱싱 모델, 자동 초기화 및 옵트아웃 동작에 대해서는 ARCHITECTURE.md → Memory를, 파일 형식, entry-policy 규칙 및 시작 템플릿에 대해서는 templates/memory를 참조하세요.

Tasks

작업 메타데이터는 일반 마크다운에 저장됩니다 — 파일 전체에 흩어져 있고, 이모지 기호나 인라인 필드로 인코딩되며, Kanban 제목 아래에 정리됩니다. "뭐가 기한이 지났지?"라고 묻는 에이전트는 모든 파일을 파싱하고 사용자가 선택한 형식을 이해해야 합니다; Kanban 보드에서 작업을 완료하려면 보드의 레인 구조, 날짜 구문, 그리고 어떤 제목이 완료 레인인지 알아야 합니다.

작업 레이어는 에이전트가 그럴 필요 없도록 처리합니다:

• 찾기(Find) — 상태, 6가지 날짜 필드(마감, 예정, 시작, 생성, 완료, 취소), 우선순위, 폴더 또는 Kanban 레인으로 필터링합니다. 각 결과에는 레인, 노트 경로, 제목 및 줄 번호가 포함되어 있어 작업을 찾기 위해 추가 읽기가 필요 없습니다.

• 업데이트(Update) — 단일 호출로 작업 완료, 우선순위 변경, Kanban 레인 간 이동을 수행합니다. 작업을 완료로 표시하면 완료 레인을 자동 감지하고 완료 날짜를 기록합니다; 되돌리면 날짜가 제거됩니다. 세 가지 변경을 동시에 수행할 수 있습니다.

• 두 형식 모두(Both formats) — Tasks 플러그인 이모지 기호를 사용하든 Dataview 인라인 필드를 사용하든, 서버는 두 형식을 모두 읽고 Tasks 플러그인이 구성된 형식으로 작성합니다.

인덱싱 모델, 날짜 계단식 정렬 및 Kanban 레인 감지에 대해서는 ARCHITECTURE.md → Tasks를 참조하세요.

Files

노트에는 스크린샷이 포함되고, 아키텍처 다이어그램을 참조하며, 캔버스와 데이터 파일로 연결됩니다 — 하지만 마크다운을 읽는 에이전트에게 ![[diagram.png]]는 그저 텍스트일 뿐입니다. vault-cortex는 파일을 볼트 주변의 잡동사니가 아닌 볼트의 일부로 취급합니다 — 연결되고, 크기가 조정되며, 읽을 수 있는 형태로, 각각 에이전트가 실제로 사용할 수 있는 형식으로 제공합니다:

• 이미지(Images) — 파일 이름이 아닌 이미지 자체입니다. 스크린샷과 다이어그램은 MCP 클라이언트가 수용할 수 있는 크기를 초과하면 서버 측에서 축소 및 재압축되므로, 휴대폰 세션에서도 5MB 아키텍처 다이어그램을 볼 수 있습니다.

• 캔버스(Canvases) — Canvas 보드는 읽기 가능한 개요로 도착합니다: 그룹, 각 카드의 내용(읽기 순서), 그리고 카드 간의 연결이 포함됩니다. 캔버스 콘텐츠는 전체 텍스트 검색이 가능하며, 보드의 파일 참조는 링크 그래프에 나타납니다 — 역링크와 외부 링크는 노트 간 링크와 동일하게 작동합니다. 정확한 JSON 소스는 완전한 충실도가 필요할 때 플래그 하나로 얻을 수 있습니다.

• PDF — 텍스트는 제목 계층, 코드 블록 및 하이퍼링크가 보존된 채 추출됩니다; PDF 콘텐츠는 노트와 함께 전체 텍스트 검색이 가능합니다. raw: true로 설정하면 페이지를 이미지로 렌더링하여 텍스트 추출로는 보존할 수 없는 레이아웃, 다이어그램 및 표를 보여줍니다 — 스캔된 PDF와 이미지 전용 PDF는 이 모드에서 작동합니다.

• 텍스트 및 데이터 파일 — TXT, SVG, JSON, XML, CSV, YAML, 로그 및 Bases 파일은 작성된 그대로 반환됩니다; 처음 100KB의 콘텐츠는 전체 텍스트 검색이 가능합니다. 대용량 데이터 파일과 로그는 한 번에 한 줄 범위씩 읽을 수 있으며, 각 페이지는 현재 위치와 남은 파일 크기를 보고합니다.

• 찾아보기(Browse) — 표시 가능한 폴더의 파일을 확장자별 개수와 파일 크기와 함께 나열합니다; 노트가 링크하는 파일은 링크 그래프에서도 크기를 보고합니다.

FILE_TOOLS_ENABLED=false로 설정하면 파일 도구를 숨길 수 있습니다 — 원격 볼트가 첨부 파일 없이 동기화되는 경우 유용합니다.

이미지 파이프라인 및 디스패치 모델에 대해서는 ARCHITECTURE.md → Files를 참조하세요.

Tools

Prompts

도구는 모델 기반입니다 — 어시스턴트가 호출합니다. 프롬프트(Prompts) 는 사용자가 트리거하는 워크플로우입니다. 각 프롬프트는 호출 시점에 검색 인덱스, 링크 그래프 및 메모리 레이어를 질의한 다음, 안내 지침과 함께 결과를 조합합니다 — 세션이 가정이 아닌 볼트의 실제 상태에 기반하여 시작됩니다.

프롬프트는 구성(MEMORY_DIR, 데일리 노트 설정)에 적응하며 모든 볼트에서 즉시 작동합니다. 클라이언트에 페이로드 제한이 있는 경우 max_chars를 전달하여 포함된 콘텐츠를 제한할 수 있습니다.

클라이언트 지원: 프롬프트는 Claude Desktop(Chat 및 Cowork — 커넥터 아래의 + 메뉴를 통해), Claude Code(슬래시 명령), OpenCode에서 작동합니다. 다른 클라이언트(Cursor, Windsurf)에서의 지원은 다양합니다 — 최신 정보는 MCP 클라이언트 매트릭스를 참조하세요.

속성

Vault Cortex는 노트의 모든 속성을 인덱싱하지만, 다섯 가지는 승격되어 특별 대우를 받습니다 — 빠른 필터링을 위한 전용 열과 모든 검색 및 탐색 결과의 최상위 필드입니다:

그 외 모든 속성도 여전히 완전히 쿼리할 수 있습니다 — 텍스트 + 메타데이터 결합 쿼리는 filters.properties와 함께 vault_search를 사용하고, 메타데이터 전용 조회는 vault_search_by_property를 사용하세요. vault_list_property_keys와 vault_list_property_values로 볼트 전체에 존재하는 속성을 확인할 수 있습니다.

이것은 관례일 뿐 요구 사항이 아닙니다 — Vault Cortex는 어떤 속성 스키마와도 작동합니다. 승격된 속성은 기본적으로 더 풍부한 필터링과 깔끔한 결과를 제공할 뿐입니다.

선행 콜아웃도 동일한 대우를 받습니다. 노트의 첫 번째 본문 콘텐츠가 Obsidian 콜아웃(> [!type])인 경우 — frontmatter 바로 뒤 또는 제목 헤딩 바로 뒤 — 인덱싱되어 모든 탐색 결과와 함께 표시됩니다(vault_search에서 include_leading_callout으로 요청). 이렇게 하면 노트가 스스로를 설명하게 됩니다: 결과를 스캔하는 에이전트는 어떤 노트를 읽을지 결정하기 전에 각 노트가 무엇을 위한 것인지 알 수 있습니다. 메모리 템플릿은 이를 위해 > [!info] Scope of this file 콜아웃을 사용하며, 볼트의 어떤 노트든 동일한 패턴을 사용할 수 있습니다.

구성

모든 설정은 합리적인 기본값을 가진 환경 변수입니다. 원격 배포에는 아래에 포함되지 않은 추가 설정(SYNC_CONFIGS, SYNC_MODE, …)이 있습니다 — 원격 가이드의 구성 표를 참조하세요.

• 스마트 기본값 — MEMORY_DIR 또는 DAILY_NOTES_FOLDER를 설정하면 PROTECTED_PATHS 및 ORPHAN_EXCLUDE_FOLDERS의 기본값이 자동으로 업데이트됩니다. DAILY_NOTES_FOLDER가 설정되지 않으면 Daily Notes가 그 자리를 차지합니다. daily-notes.json에만 구성된 데일리 노트 폴더는 자동으로 인식되지 않으므로 직접 PROTECTED_PATHS에 추가하세요. 완전히 사용자 지정 목록을 원할 때만 명시적으로 설정하면 됩니다.

• MEMORY_ENABLED=false 메모리 계층을 완전히 비활성화합니다. 메모리 도구가 숨겨지고 메모리 폴더가 자동 생성되지 않습니다.

• FILE_TOOLS_ENABLED=false 파일 도구를 완전히 숨깁니다. Obsidian Sync에서 첨부 파일 동기화가 비활성화되어 디스크에 파일이 없을 때 유용합니다.

• READONLY_MODE=true 볼트에 쓰는 모든 도구를 숨기고 메모리 폴더 자동 생성을 건너<...> 연결된 클라이언트는 읽고 검색할 수 있지만 편집할 수는 없습니다.

• DISABLED_TOOLS 지정한 도구만 정확히 숨깁니다. 위의 스위치보다 세밀한 제어를 위해 사용합니다. 예를 들어 쓰기는 유지하되 vault_delete_note와 vault_move_note만 제거할 수 있습니다. 도구 설명과 프롬프트의 가용성 기반 상호 참조는 자동으로 조정됩니다.

메모리 파일 예제와 날짜 기반 항목 설계 철학은 templates/memory/를 참조하세요.

데일리 노트

vault_get_daily_note 및 일일 리뷰 프롬프트는 볼트의 .obsidian/daily-notes.json에서 읽은 Obsidian에 구성된 폴더 및 파일 이름 날짜 형식을 사용하여 데일리 노트를 찾습니다:

• 로컬 모드는 바인드 마운트된 볼트에서 파일을 직접 읽습니다 — 설정할 것이 없습니다.

• 원격 모드는 Obsidian Sync의 볼트 설정 동기화를 통해 파일을 받습니다. 서버는 기본적으로 이를 가져옵니다(.env의 SYNC_CONFIGS 설정). 하지만 푸시 쪽을 활성화해야 할 가능성이 높습니다: Obsidian 설정 → 동기화 → 볼트 설정 동기화, 기기별로. 자세한 내용: 원격 가이드의 Daily notes 섹션.

파일을 사용할 수 없거나 — 설정을 반영하지 않는 Periodic Notes 플러그인을 사용하는 경우 — DAILY_NOTES_FOLDER(볼트 기준 경로: Journal, Planner/Daily)와 DAILY_NOTES_FORMAT(Obsidian의 날짜 형식 설정과 동일한 토큰: YYYY-MM-DD-dddd, YYYY/MM/DD, MMM D, YYYY, …)을 설정하세요. 둘 중 하나 또는 둘 다 설정할 수 있습니다 — 설정된 값은 항상 구성 파일보다 우선합니다. 두 소스가 모두 없으면 서버는 Daily Notes와 YYYY-MM-DD로 폴백합니다.

참고: 일부 날짜 형식 토큰은 지원되지 않습니다 — 서수(Do, Mo, DDDo, wo), dd(2글자 요일), d(요일 숫자), e, k/kk, 그리고 지역화 형식(L–LLLL, LT, LTS). 서버는 이러한 토큰으로 Obsidian이 생성하는 파일 이름을 재현할 수 없으므로 노트를 찾을 수 없습니다. 형식에 이러한 토큰이 포함된 경우 vault_get_daily_note는 명확한 오류를 반환합니다 — Obsidian에서 형식을 변경하거나 DAILY_NOTES_FORMAT을 지원되는 대안으로 설정하세요.

데이터 무결성

Vault Cortex는 개인 노트에 기록합니다 — 파일 안전 계층은 단순한 오류 방지가 아닌 손상 방지를 위해 설계되었습니다.

• 원자적 쓰기 — 모든 파일 쓰기는 임시 파일에 스테이징한 후 이름을 변경합니다. 읽는 쪽은 부분적이거나 0바이트 노트를 볼 수 없습니다. 독점 생성은 link()(POSIX no-clobber)를 사용하여 노트 이동 시 TOCTOU 창을 닫습니다.

• 파일별 뮤텍스 — 동시 MCP 도구 호출은 파일별로 직렬화되거나 빠르게 실패합니다. 이동은 소스, 대상, 모든 백링크 소스를 하나의 단위로 잠급니다.

• 경로 탐색 차단 — resolveSafePath()는 모든 경로를 해석한 후 접두사를 검사합니다. 정규화 후 보호된 경로 삭제는 거부됩니다. 메모리 파일 이름은 경계에서 구분자를 거부합니다.

• 숨김 경로는 접근 불가 — 점으로 시작하는 파일과 폴더(.obsidian/, .trash/)는 목록이나 검색에 절대 나타나지 않으며, 직접 대상으로 하는 도구 호출은 Obsidian과 동일하게 거부됩니다. 플러그인 구성과 API 키는 접근 범위 밖에 유지됩니다.

• 주입 방지 — 검색 쿼리는 매개변수화되고 FTS5로 정화됩니다. 프롬프트 콘텐츠는 태그 이탈 주입을 방지하기 위해 닫는 태그 이스케이프가 있는 XML 데이터 마커로 래핑됩니다.

• 컨테이너 강화 — 비루트 사용자, PID 1 init, 런타임 이미지에 패키지 관리자 없음, 다이제스트 고정 베이스, 정상 종료.

메커니즘 세부 사항은 ARCHITECTURE.md → 데이터 무결성을, 전체 공격 표면 목록은 SECURITY.md → 런타임 강화를 참조하세요.

인증

개인 노트에 대한 읽기/쓰기 액세스 권한이 있는 서버의 경우 인증은 선택 사항이 아닙니다. Vault Cortex는 PKCE 및 리프레시 토큰 순환을 포함한 전체 OAuth 2.1 사양을 구현합니다. AWS (SST) 배포는 심층 방어를 추가합니다: 요청은 두 개의 독립적인 계층(API Gateway Lambda 인증자 + Express 미들웨어)에서 검증됩니다. BlueRock의 2026 MCP 보안 분석에 따르면 MCP 서버의 8.5%만 OAuth를 구현하며, 41%는 인증이 전혀 없습니다.

두 가지 방법:

OAuth는 동적 클라이언트 등록을 사용합니다 — Client ID/Secret이 필요 없습니다. 브라우저에서 동의 페이지가 열립니다. MCP_AUTH_TOKEN을 입력하여 승인하세요. 리프레시 토큰은 60일 슬라이딩 만료 기간이 있습니다(일일 사용자는 다시 인증할 필요가 없습니다).

전체 흐름 다이어그램은 ARCHITECTURE.md → 인증을 참조하세요.

배포 옵션

로컬은 사용자 머신에서 실행됩니다. 원격 배포는 VPS에서 실행됩니다 — 노트북이 닫혀 있어도 볼트에 접근할 수 있습니다.

AWS 경로에는 이 저장소용으로 구축된 CI/CD 워크플로가 포함됩니다 — 포크 사용자는 배포 전에 자체 자격 증명과 스테이지를 구성해야 합니다.

세 경로 모두 동일한 이미지 ghcr.io/aliasunder/vault-cortex를 실행합니다 — :latest는 MCP 서버 단독(로컬), :remote는 s6-overlay 감독 하에 동일한 컨테이너에 Obsidian Sync를 번들합니다(원격 및 AWS). 하나의 컨테이너이므로 모든 OCI 런타임에서 작동합니다: docker run, Podman, nerdctl — Docker Compose는 선택 사항입니다.

Docker Hub에도 있습니다: 동일한 이미지가 aliasunder/vault-cortex에 미러링됩니다. GHCR이 기본 소스이며, Hub 태그는 동일합니다.

비용: 원격 설정에는 VPS와 Obsidian Sync용 월 $4 USD가 필요합니다. 2 GiB 인스턴스는 일반적인 볼트에서 의미론적 검색을 충분히 처리합니다. 4 GiB는 동시 검색과 더 큰 볼트를 위한 여유를 추가합니다. 의미론적 검색을 완전히 건너뛰면 더 작은 인스턴스로도 충분합니다. 로컬 전용은 무료입니다. 참조 AWS 배포는 월 약 $17–29로 모두 포함됩니다.

커뮤니티 배포

커뮤니티에서 구축하고 유지 관리하는 배포 템플릿 — 여기서 테스트되지 않았으며 릴리스보다 뒤처질 수 있습니다.

• vault-cortex-aca — @flytzen의 Azure Container Apps용 Bicep 템플릿. Container Apps 수신 뒤에서 무료 관리형 HTTPS로 :remote 이미지를 실행합니다. 스토리지는 의도적으로 임시적이며 Obsidian Sync가 진실의 원천입니다.

다른 플랫폼용 배포를 구축하셨나요? 여기에 추가하려면 PR을 열어주세요.

개발

# 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 test && npm run build

npm test에는 실제 서버를 부팅하고 HTTP를 통해 모든 도구와 프롬프트를 호출하는 통합 테스트가 포함됩니다 — 인증 적용, 구성 게이트 도구 표면, 쓰기 변형 무결성(각 쓰기는 다시 읽혀짐), 잘못된 구성 시 부팅 거부를 검증합니다. 보안 관련 범위는 SECURITY.md를 참조하세요.

MCP Inspector — 도구 테스트용 대화형 브라우저 UI:

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

전체 개발 설정은 CONTRIBUTING.md를 참조하세요.

동반: obsidian-vault 스킬

MCP 서버는 모든 클라이언트와 단독으로 작동합니다. 스킬을 지원하는 에이전트(Claude Code, Cursor, Windsurf, Cline 및 70개 이상)의 경우 obsidian-vault 스킬은 Obsidian 특화 마크다운에 대한 더 깊은 지식을 추가합니다 — frontmatter 규칙, 콜아웃 구문, Dataview, Tasks, Kanban과 같은 플러그인별 형식.

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

스킬 소스 →

로드맵

감사의 말

Obsidian 동기화는 obsidian-headless로 구동됩니다 — 컨테이너화 접근 방식은 @Belphemur의 obsidian-headless-sync-docker에서 영감을 받았습니다. :remote 이미지의 s6-overlay 감독 스캐폴딩은 해당 프로젝트의 유지 관리 포크에서 흡수되어 이제 이 저장소에 있습니다.

하이브리드 검색 파이프라인은 @tobi의 qmd의 패턴을 활용합니다 — 순위 보너스가 있는 RRF 융합, 교차 인코더 리랭킹을 위한 위치 인식 점수 혼합, 콘텐츠 해시 게이팅, 헤딩 인식 청킹.

기여

개발 설정, 코드 규칙, PR 지침은 CONTRIBUTING.md를 참조하세요.

라이선스

MIT

:remote 이미지는 독점인 obsidian-headless(ob CLI)를 번들합니다 — 해당 package.json은 "license": "UNLICENSED"를 선언합니다(© Dynalist Inc. / Obsidian). 빌드 시 공개 npm에서 설치되며, 여기의 MIT 라이선스는 이를 포함하지 않으며, 사용하려면 활성 Obsidian Sync 구독이 필요합니다. :latest(로컬) 이미지에는 독점 구성 요소가 없습니다.

보안

취약점은 비공개로 보고하세요 — SECURITY.md를 참조하세요.