Vault Cortex

Vault Cortex 是一个独立的 MCP 服务器，为你的 Obsidian 仓库提供混合搜索、任务管理、结构化记忆，以及读写访问能力。无需插件、无需运行 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 插件 的 emoji 和 Dataview 的内联字段格式。

• 链接图谱 — 跨仓库的反向链接、出链和孤立笔记检测

• 文件 — 也能读取仓库中的非 Markdown 文件：图片以实际图片形式呈现（必要时缩小以适配），PDF 以结构化文本或渲染页面呈现，画布以可读大纲呈现，数据文件以文本呈现

• Obsidian 原生 — 理解 frontmatter、wikilinks、标签、标题和每日笔记

• 引导式工作流 — 内置用于仓库健康、记忆回顾和每日对账的提示——每次根据实时仓库数据组装

在为期 15 天的欧洲之旅中进行了测试。 30 多次手机会话，216 次工具调用，全程无需笔记本电脑。一次会话中的写入在下次会话中立即可用，跨越城市和天数。

Related MCP server: Vault MCP Server (mschuchard)

快速开始

本地（2 分钟 — Docker + 你的仓库文件夹）

先决条件： Docker（或兼容 Docker 的运行时，例如 OrbStack、Colima、Podman）、Node.js >= 20.12（仅用于 CLI——服务器本身在 Docker 中运行），以及一个 Obsidian 仓库（或任何包含 .md 文件的文件夹）。

npx vault-cortex@latest init

就这样——CLI 会询问你的仓库路径，生成认证令牌和配置文件，启动服务器，并打印你的 MCP 客户端的连接详情（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（或兼容 Docker 的运行时）的 VPS、一个 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 设置？ 它从此管理服务器——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 客户端

在任何 MCP 客户端中添加服务器 URL——Claude Code、Claude Desktop、Cursor、OpenCode 或任何其他客户端。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 会为每个项目注册服务器；省略它则仅将其限定在当前目录。

“添加自定义连接器”对话框仅接受 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% 的自然语言查询返回零结果或无关结果。混合搜索消除了这些遗漏——向量弥合了词汇差距，而重排序器挽救了那些单独信号都不强的意图密集型查询。

混合搜索通过 倒数排名融合 结合三种排序信号：

• 关键词（FTS5）在精确术语、行话和属性值上保持精准

• 向量（sqlite-vec）通过语义匹配弥合词汇差距

• 重排序器（cross-encoder）通过联合评分每个查询-文档对来优化排序——挽救关键词和向量都遗漏的意图密集型查询

所有模型均在本地运行（总计约 45MB，无需外部 API）。设置 EMBEDDING_ENABLED=false 可仅使用关键词搜索，或设置 RERANK_MODE=none 跳过重排序以降低延迟。

有关模型详情、混合权重和完整流水线分解，请参阅 ARCHITECTURE.md → 混合搜索。

记忆

一个只增长的记忆层，只有在代理能够检索到正确条目而无需将所有内容倾倒入上下文时才有用。一旦你在多个文件中拥有数百条带日期的条目——偏好、原则、沟通风格、持续承诺——读取整个文件会浪费上下文在无关材料上，并埋没信号。记忆系统专为定向检索而设计：代理随时间积累知识，并准确回忆与当前任务相关的内容。

该层是一个纯 Markdown 文件文件夹（默认：About Me/），在主题标题下保存带日期的条目——首次运行时使用入门模板自动创建，由代理通过 vault_update_memory 增长。三个属性使其发挥作用：

• 仅追加 —— 条目永不被覆盖；更正以新的带日期条目形式出现。该层成为个人知识库，既捕捉你的当前状态，也捕捉其背后的演变过程

• 主题召回 —— vault_memory_recall 一次性跨所有记忆文件检索每条相关条目，支持关键词和语义匹配，按从旧到新排序。问"我对 X 的看法是什么？"即可获得当前观点以及其发展的带日期历史——无需阅读整个文件或猜测哪个文件存了什么

• 增长而不退化 —— 结果上限（max_results）丢弃最不相关的条目，绝不会截断时间线。拥有 500 条条目的记忆层与只有 50 条的一样，能为定向查询提供同样好的服务

描述当前状态而非历史事实的文件（例程、活跃承诺）可以在 frontmatter 中声明 entry-policy: living——其过期条目可被修剪而非保留，从而保持当前状态图景的准确性。

整个层是可选的——设置 MEMORY_ENABLED=false 可隐藏记忆工具并完全跳过文件夹自动创建。

参见 ARCHITECTURE.md → Memory 了解召回管道、索引模型、自动初始化和退出行为，以及 templates/memory 了解文件格式、条目策略约定和入门模板。

Tasks

任务元数据存在于纯 markdown 中——分散在文件中，编码在 emoji 标记或内联字段中，组织在 Kanban 标题下。一个回答"什么逾期了？"的代理需要解析每个文件并理解你选择的格式；在 Kanban 板上完成任务意味着要了解板子的泳道结构、日期语法，以及哪个标题是完成泳道。

任务层处理了这一切，代理无需操心：

• 查找 —— 按状态、六个日期字段（截止、计划、开始、创建、完成、取消）、优先级、文件夹或 Kanban 泳道过滤。每个结果都携带其泳道、笔记路径、标题和行号——无需后续读取即可定位任务

• 更新 —— 在单次调用中完成、调整优先级并在 Kanban 泳道间移动任务。将任务标记为完成会自动检测完成泳道并盖上完成日期；撤销操作则移除该日期。三项更改可以同时发生

• 两种格式 —— 无论你使用哪种格式，Tasks plugin emoji 标记还是 Dataview 内联字段，服务器都能读取两种格式，并以你的 Tasks plugin 所配置的格式写入

参见 ARCHITECTURE.md → Tasks 了解索引模型、日期级联排序和 Kanban 泳道检测。

Files

你的笔记嵌入了截图、引用架构图，并链接到画布和数据文件——但对一个阅读 markdown 的代理来说，![[diagram.png]] 只是文本。vault-cortex 将文件视为 vault 的一部分而非其周围的杂物——可链接、可调整大小、可读取，每种都以代理实际可用的形式呈现：

• 图片 —— 图片本身，而非文件名。截图和图表在超过 MCP 客户端可接受范围时会在服务端降采样并重新压缩，因此即使是手机会话也能查看 5MB 的架构图

• 画布 —— Canvas 板以可读大纲形式呈现：其分组、每张卡片按阅读顺序的内容，以及它们之间的连接。画布内容可全文搜索，板上的文件引用会出现在链接图中——反向链接和出站链接与笔记间链接的工作方式相同。需要完整保真度时，精确的 JSON 源码仅一步之遥

• PDF —— 文本提取时保留标题层级、代码块和超链接；PDF 内容可与你的笔记一起全文搜索。设置 raw: true 可改为将页面渲染为图片，显示文本提取无法保留的布局、图表和表格——扫描版和纯图片 PDF 在此模式下可用

• 文本和数据文件 —— TXT、SVG、JSON、XML、CSV、YAML、日志和 Bases 文件按原样返回；前 100 KB 内容可全文搜索。大型数据文件和日志可以按行范围逐段读取，每页都会报告你所在位置以及文件剩余量

• 浏览 —— 列出任何可见文件夹的文件，附带各扩展名计数和文件大小；笔记链接到的文件也会在链接图中报告其大小

设置 FILE_TOOLS_ENABLED=false 可隐藏文件工具——当你的远程 vault 同步时不带附件时很有用。

参见 ARCHITECTURE.md → Files 了解图片管道和分发模型。

Tools

Prompts

工具是模型驱动的——由助手调用。Prompts 是你触发的工作流。每个 prompt 在调用时查询搜索索引、链接图和记忆层，然后将结果与引导指令组装在一起——因此会话从你 vault 的实际状态出发，而非假设。

Prompts 会适配你的配置（MEMORY_DIR、每日笔记设置），并且开箱即用于任何 vault。如果你的客户端有负载限制，可传入 max_chars 来限制嵌入内容。

客户端支持： Prompts 在 Claude Desktop（Chat 和 Cowork — 通过连接器下的 + 菜单）、Claude Code（斜杠命令）和 OpenCode 中均可使用。其他客户端（Cursor、Windsurf）的支持情况有所不同 — 请参阅 MCP clients matrix 了解最新信息。

属性

Vault Cortex 会为笔记中的每个 property 建立索引，但有五个属性会获得 提升 待遇 — 专属列用于快速筛选，以及每次搜索和发现结果中的顶级字段：

所有其他属性 仍然可以完全查询 — 使用 vault_search 配合 filters.properties 进行文本 + 元数据组合查询，或使用 vault_search_by_property 进行仅元数据查询。vault_list_property_keys 和 vault_list_property_values 可发现 vault 中存在的属性。

这些是约定，而非要求 — Vault Cortex 适用于任何属性模式。提升属性只是让你开箱即用地获得更丰富的筛选和更清晰的结果。

前置 callout 获得同样的处理。当笔记的第一个正文内容是 Obsidian callout（> [!type]）— 无论是紧跟 frontmatter 之后还是紧跟标题之后 — 它都会被索引，并与每条发现结果一起呈现（在 vault_search 上，使用 include_leading_callout 请求它）。这使得笔记具有自描述性：扫描结果的 agent 可以在决定阅读哪条笔记之前看到每条笔记的用途。记忆模板使用 > [!info] Scope of this file callouts 来实现这一点，vault 中的任何笔记都可以使用相同的模式。

配置

所有设置都是环境变量，带有合理的默认值。远程部署还有以下未列出的额外设置（SYNC_CONFIGS、SYNC_MODE、…）— 参见 remote guide's configuration table。

数据完整性

Vault Cortex 写入个人笔记——文件安全层旨在防止损坏，而不仅仅是错误。

• 原子写入——每次文件写入都会先暂存到临时文件，然后重命名。读者永远不会看到部分写入或 0 字节的笔记。独占创建使用 link()（POSIX 无覆盖）来关闭笔记移动时的 TOCTOU 窗口。

• 每文件互斥锁——并发的 MCP 工具调用会按文件串行化，或快速失败。移动操作会将源、目标和每个反向链接作为一个整体锁定。

• 阻止路径遍历——resolveSafePath() 先解析再对每个路径做前缀检查。规范化后拒绝删除受保护路径。内存文件名在边界处拒绝分隔符。

• 隐藏路径不可访问——以点开头的文件和文件夹（.obsidian/、.trash/）永远不会出现在列表或搜索中，任何直接针对它们的工具调用都会被拒绝，与 Obsidian 行为一致。插件配置及其 API 密钥不受影响。

• 注入防护——搜索查询经过参数化并经过 FTS5 净化；提示内容包裹在 XML 数据标记中，并带有闭合标签转义，以防止标签逃逸注入。

• 容器加固——非 root 用户、PID 1 init、运行时镜像中无包管理器、摘要固定基础镜像、优雅关闭。

参见 ARCHITECTURE.md → 数据完整性 了解机制细节，以及 SECURITY.md → 运行时加固 了解完整的攻击面清单。

身份验证

对于具有笔记读写权限的服务器，身份验证是强制性的。Vault Cortex 实现了完整的 OAuth 2.1 规范，包括 PKCE 和刷新令牌轮换。AWS (SST) 部署 增加了纵深防御：请求在两层独立验证（API Gateway Lambda 授权器 + Express 中间件）。根据 BlueRock 的 2026 MCP 安全分析，只有 8.5% 的 MCP 服务器实现了 OAuth；41% 完全没有身份验证。

两种方法：

OAuth 使用动态客户端注册——无需 Client ID/Secret。同意页面会在浏览器中打开；输入你的 MCP_AUTH_TOKEN 以批准。刷新令牌有 60 天滑动过期期（日常用户永远不需要重新认证）。

参见 ARCHITECTURE.md → 身份验证 了解完整流程。

部署选项

本地运行在你的机器上。远程部署运行在 VPS 上——即使你的笔记本电脑关机，你的笔记库也可访问。

AWS 路径包含为该项目构建的 CI/CD 工作流——fork 者需要配置自己的凭据和阶段 才能部署。

所有三种路径都运行相同的镜像，ghcr.io/aliasunder/vault-cortex——:latest 是独立的 MCP 服务器（本地），:remote 在 s6-overlay 监督下捆绑了 Obsidian 同步（远程和 AWS）。一个容器意味着任何 OCI 运行时都可以工作：docker run、Podman、nerdctl——Docker Compose 是可选的。

也可在 Docker Hub 获取： 相同镜像镜像到 aliasunder/vault-cortex。GHCR 是主要来源；Hub 标签完全相同。

成本： 远程设置需要一台 VPS 和每月 4 美元用于 Obsidian 同步。2 GiB 实例对于典型笔记库的语义搜索绰绰有余；4 GiB 为并发搜索和更大的笔记库增加了余量。完全跳过语义搜索可以进一步缩小规模。纯本地免费。参考 AWS 部署 全部包含约每月 17–29 美元。

社区部署

由社区构建和维护的部署模板——此处未经过测试，可能落后于版本发布。

• vault-cortex-aca——由 @flytzen 为 Azure 容器应用 提供的 Bicep 模板。在容器应用入口后面运行 :remote 镜像，带有免费托管 HTTPS；存储有意设计为临时性，以 Obsidian 同步为唯一事实来源。

为其他平台构建了部署？打开 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 风格 markdown 的更深理解——frontmatter 约定、callout 语法，以及 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 融合、交叉编码器重排序的位置感知分数混合、内容哈希门控，以及标题感知分块。

贡献

参见 CONTRIBUTING.md 了解开发设置、代码约定和 PR 指南。

许可证

MIT

:remote 镜像捆绑了 obsidian-headless（ob CLI），它是专有软件——其 package.json 声明了 "license": "UNLICENSED"（© Dynalist Inc. / Obsidian）。它在构建时从公共 npm 安装；此处的 MIT 许可证不涵盖它，使用它需要有效的 Obsidian 同步订阅。:latest（本地）镜像不包含任何专有组件。

安全

私下报告漏洞——参见 SECURITY.md。