Vault Cortex

Vault Cortex 是一个独立的 MCP 服务，为任何 AI Agent 提供混合搜索、任务管理、结构化记忆以及对你的 Obsidian 知识库的读写访问权限。无需插件，无需运行 Obsidian，也无需单独的桥接程序。一个 Docker 容器、你的知识库文件夹，以及一整套工具和引导式提示词。将它部署在远程服务上并搭配 Obsidian Sync，即可通过手机、claude.ai 或任何远程 MCP 客户端访问同一个知识库，并由 OAuth 2.1 提供安全保护。你可以一键部署，也可以自行托管；无论哪种方式，知识库始终归你所有。

目录 — 你将获得什么 · 快速开始 · 工作原理 · 混合搜索 · 记忆 · 任务 · 文件 · 工具 · 提示词 · 属性 · 配置 · 每日笔记 · 数据完整性 · 身份验证 · 部署选项 · 一键部署 · 社区部署

你将获得

搜索仓库	对笔记进行推理	写回 Obsidian

这三个演示均在 Claude 移动端上运行。仓库位于远程服务器上，而非手机上。

• 远程访问 — 可通过 OAuth 2.1 从你的手机、远程服务器或任何 MCP 客户端使用。在 Render 或 Railway 上一键部署即可，无需管理服务器；使用 VPS 也可以。
• 无需插件 — 无需运行 Obsidian。服务直接操作磁盘上的 .md 文件。无界面同步让仓库保持最新。
• 混合搜索 — FTS5 关键词匹配 + 向量语义相似度，通过 RRF 融合，再经交叉编码器重排序优化，以应对意图密集的查询。关键词在精确术语和行话上保持精准；向量则能在你的用词与仓库不一致时也能找到笔记。
• 结构化记忆 — 带日期、仅追加的条目累积成个人知识层，自动初始化以实现 AI 个性化。主题回忆能回答“我对 X 怎么看？”，给出当前观点及其背后的带日期历史——包括演变过程。
• 任务 — 感知看板的任务查询和更新：按状态、日期或优先级分诊，然后一次调用即可完成、重新排序或在泳道间移动任务。完成重复任务会生成其下一次出现。Tasks 插件 emoji 和 Dataview 内联字段格式均可解析。
• 链接图谱 — 整个仓库的反向链接、出链和孤立笔记检测
• 文件 — 也可读取仓库中的非 Markdown 文件：图片以实际图片呈现（必要时缩小以适应），PDF 以结构化文本或渲染页面呈现，画布以可读大纲呈现，数据文件以文本呈现
• Obsidian 原生 — 理解 frontmatter、wikilinks、标签、标题和每日笔记
• 引导式工作流 — 内置提示词，用于仓库健康检查、记忆回顾和每日对账——每次均基于实时仓库数据组装

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

快速开始

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

前提条件： Docker（或兼容 Docker 的运行时，例如 OrbStack、Colima、Podman）、Node.js >= 22.12（仅 CLI 需要 — 服务本身运行在 Docker 中），以及一个 Obsidian vault（或任意包含 .md 文件的文件夹）。

npx vault-cortex@latest init

就这么简单 — CLI 会询问你的 vault 路径，生成认证 token 和配置文件，启动服务，并打印 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 设置）

远程（随时随地访问）

你的 vault 放在服务器上，由 Obsidian Sync 保持最新，可从手机、claude.ai 或任何 MCP 客户端访问。一键选项会询问你的 vault 名称和时区（如果你的 vault 已加密，还会询问 vault 密码），然后处理 HTTPS、重启、生成的 MCP token 和持久化存储。部署完成后，设置页面会引导你在浏览器中登录 Obsidian Sync。在你自己的服务器上，CLI 会询问公共 URL 和 vault 名称，为你捕获 Sync token，并生成 MCP token；HTTPS 由你自行设置。

	Railway	Render	自托管
			CLI setup →
账户	Railway 的 Hobby 或更高套餐——包含 5 GB 卷	Render，需绑定银行卡	一台装有 Docker 的 VPS
费用	按用量计费：个人知识库通常为每月 20–30 美元——安静的知识库比 Render 略便宜，繁忙的则略贵	固定费用：Standard 实例（2 GB）加 5 GB 磁盘约每月 26 美元，按秒计费	取决于你的 VPS 费用
适合人群	你想要更轻松的上手——模板会直接为你创建配置好的项目	可预测的账单比部署体验更重要	你已有服务器，或想要完全控制
指南	Railway 指南 →	Render 指南 →	远程指南 →

三者都需要 Obsidian Sync 订阅。无论你选哪个，服务都可以替换，而你的知识库不会——它以纯 Markdown 保存在 Obsidian Sync 和你的设备上；容器中只保留一份副本。

设置页面。 不带 Obsidian Sync token 部署时，服务会以设置模式启动：在浏览器中打开其 URL 会进入 /setup 的登录页面。输入一次你的 Obsidian 账户凭据（支持双因素认证）——你直接通过 Obsidian 登录；服务仅保留该次登录的 Sync token，随后重启并下载你的知识库。

登录页面，由你的 MCP token 保护。每份部署指南都会带你走完整个流程。

Vault Cortex CLI 会在你运行它的任意 Linux 机器上部署同一个容器——由你管理服务、镜像和更新。CLI 本身需要 Node.js >= 22.12；服务运行在 Docker 中。

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

就是这样——CLI 会引导你依次填写公开 URL、Obsidian Sync token（它可以为你运行 get-sync-token）、vault 名称、加密 vault 的 vault 密码以及认证配置，然后启动服务（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, VAULT_NAME (OBSIDIAN_AUTH_TOKEN optional — /setup handles it)
docker compose up -d

连接你的 MCP 客户端

在任意 MCP 客户端中添加该服务 URL——Claude Code、Claude Desktop、Cursor、OpenCode 或任何其他客户端。OAuth 客户端会在浏览器中打开授权页面——用你的 token 批准，此后客户端会自动处理 token 续期。不支持 OAuth 的客户端（MCP Inspector、脚本）则直接通过 Authorization: Bearer 请求头发送 token。

Claude Code：

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

--scope user 会为所有项目注册该服务；省略它则仅作用于当前目录。

{
  "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）——在本地部署中，服务仍然完全运行在你自己的机器上。

两种方式及 token 有效期请参见身份认证。

工作原理

一切都在一个 Docker 容器中运行，直接操作磁盘上的 .md 文件：

• 你的 vault 始终是唯一事实来源 — 服务读写与你的 Obsidian 应用相同的纯 Markdown 文件。
• 搜索是派生数据 — 文件监听器会在笔记变更时保持索引（关键词 + 向量）最新，且索引可随时从你的笔记重建。
• 远程镜像增加了同步循环 — 内置的 Obsidian Sync 服务让容器中的 vault 与每台设备保持同步：在手机上编辑一条笔记，片刻后即可被搜索到；Agent 写入一条笔记，它就会出现在 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。

混合搜索

当你的用词与 vault 中的用词不一致时，仅靠关键词搜索就会失效 — "aspirations" 找不到关于 "targets" 的笔记，"coworkers" 也无法呈现你的 "references" 文件。在针对真实 vault 的测试中，仅使用关键词时，30% 的自然语言查询返回了零结果或边缘相关的结果。在同一测试中，混合搜索消除了这些漏检。

混合搜索通过 Reciprocal Rank Fusion 融合关键词排名与向量排名，然后由重排序器对融合结果进行精炼：

• 关键词（FTS5）在精确术语、行话和属性值上保持精准
• 向量（sqlite-vec）通过语义匹配弥合用词差异
• 重排序器（cross-encoder）通过联合评分每个查询-文档对来优化排序 — 挽救关键词和向量都失手的意图密集型查询

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

模型详情、融合权重以及完整流水线拆解请参见 ARCHITECTURE.md → Hybrid Search。

记忆

一个只会不断增长的记忆层，只有当 Agent 能够检索到正确的条目、而不必每次都读回全部内容时才有用。一旦你在多个文件中积累了数百条带日期的条目 — 偏好、原则、沟通风格、进行中的承诺 — 整文件读取就会让信号淹没在无关材料中。记忆系统正是为定向检索而设计。

该层是一个存放纯 Markdown 文件的文件夹（默认：About Me/），在主题标题下保存带日期的条目 — 首次运行时自动创建并附带起始模板，由 Agent 通过 vault_update_memory 不断扩充。三个特性让它得以运作：

• 仅追加 — 条目从不被覆盖；修正以新的带日期条目形式出现。该层成为个人知识库，既记录你的当前状态，_也_记录其背后的演变
• 主题回忆 — vault_memory_recall 一次性检索所有记忆文件中的每一条相关条目，同时按关键词和语义匹配，最早的在前。问"我对 X 怎么看？"就能得到当前观点以及它如何发展的带日期历史 — 无需读取整个文件，也无需猜测哪个文件里有什么
• 增长而不退化 — 限制结果数量（limit）会丢弃最不相关的条目，而绝不会截断时间线。拥有 500 条条目的记忆层，其定向查询表现与只有 50 条的一样好

描述当前状态而非曾经为真内容的文件（日常惯例、进行中的承诺），可在 frontmatter 中声明 entry-policy: living — 其过期条目可被清除而非保留，从而保持当前状态图景的准确性。

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

回忆流水线、索引模型、自动初始化以及退出机制请参见 ARCHITECTURE.md → Memory，文件格式、entry-policy 约定和起始模板请参见 templates/memory。

任务

任务元数据以纯 Markdown 形式存在——散落在各个文件中，用 emoji 标记或内联字段编码，并按看板标题组织。如果 Agent 要回答“哪些任务已逾期？”，就需要解析每个文件并理解你所选用的格式；在看板上完成一项任务，意味着要了解看板的分栏结构、日期语法，以及哪个标题是完成分栏。

任务层负责处理这些，因此 Agent 无需操心：

• 查找 — 按状态、六个日期字段（到期、计划、开始、创建、完成、取消）、优先级、文件夹或看板分栏进行筛选。每条结果都带有其笔记路径、行号，以及在任务位于某个标题下时最近的标题（看板上的分栏）——无需额外读取即可定位任务
• 创建 — 一步添加格式正确的任务：描述、优先级、日期、重复、On completion 操作、依赖项、块 ID（^id）以及清单子项（仅文本，无日期），可放在顶部、底部或某个标题下的精确位置，也可作为子任务嵌套在父任务下并带有自己的日期。在看板上，子任务不会获得块 ID，因为看板插件在保存看板时会将它复制到卡片上
• 更新 — 在单次调用中完成、重新设定优先级、编辑文本、设置或清除日期、重复和 On completion 操作，添加清单项，在标题之间移动任务，并在分栏内重新排序
• 完成 — 将任务标记为完成会自动检测完成分栏并写入完成日期，遵循插件的 Set done date 设置；反向操作则会移除该日期。完成还会触发 Tasks 插件自身的行为：
  • 重复任务会生成其下一次出现，日期按插件计算的方式推进
  • 设置为 On completion 删除的任务会从笔记中消失
• 两种格式 — 无论你使用哪种格式，Tasks 插件的 emoji 标记还是 Dataview 的内联字段，服务端都能读取两者，并按你的 Tasks 插件所配置的格式写入——当你的库同步 .obsidian/ 时从插件设置中读取，否则默认使用 emoji 标记

有关索引模型、日期级联排序和看板分栏检测，请参阅 ARCHITECTURE.md → Tasks。

文件

你的笔记中会嵌入截图、引用架构图，并链接到 Canvas 和数据文件——但对于阅读 Markdown 的 Agent 来说，![[diagram.png]] 只是一段文本。Vault Cortex 将文件视为知识库的一部分，而非周围的杂物——它们被链接、设定尺寸，并且可读，每一种都呈现为 Agent 可用的形式：

• 图片——图片本身，而不是文件名。当截图和图解超出 MCP 客户端可接受的范围时，会在服务端进行缩小和重新压缩，因此即使是手机会话也能查看 5MB 的架构图
• Canvas——一个 Canvas 画板会以可读大纲的形式呈现：它的分组、每张卡片按阅读顺序排列的内容，以及它们之间的连接。Canvas 内容可全文搜索，画板上的文件引用会出现在链接图中——反向链接和出链的工作方式与笔记之间的链接完全一样。当需要完整保真时，只需一个标志即可获取精确的 JSON 源
• PDF——文本提取时会保留标题层级、代码块和超链接；PDF 内容可与你的笔记一同全文搜索。设置 raw: true 可将页面改为以图片形式渲染，从而显示文本提取无法保留的布局、图表和表格——扫描版和纯图片 PDF 在此模式下也可用
• 文本和数据文件——TXT、SVG、JSON、XML、CSV、YAML、日志以及 Bases 文件会按原样返回；前 100 KB 的内容可全文搜索。大数据文件和日志可以每次读取一个行范围，每一页都会报告你当前所在的位置以及文件还剩多少
• 浏览——列出任意可见文件夹中的文件，附带按扩展名分类的计数和文件大小；笔记所链接的文件也会在链接图中报告其大小

设置 FILE_TOOLS_ENABLED=false 可隐藏文件工具——当你的远程知识库同步时不包含附件，这会很有用。

有关图片流水线和调度模型，请参见 ARCHITECTURE.md → Files。

工具

提示词

工具由模型驱动 —— 由助手调用它们。提示词则是_你_触发的工作流。每个提示词在调用时都会查询搜索索引、链接图谱和记忆层，然后将结果与引导指令组合起来 —— 因此会话从一开始就立足于你 vault 的实际状态，而非假设。

提示词会适配你的配置（MEMORY_DIR、每日笔记设置），并且开箱即可用于任何 vault。如果你的客户端有负载限制，可传入 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 中存在哪些属性。

这些是约定，而非要求——Vault Cortex 可与任何属性 schema 配合使用。提升属性开箱即用地为你提供更丰富的筛选和更清晰的结果。

开头的标注也会获得同样的处理。当一条笔记的首个正文内容是 Obsidian 标注（> [!type]）时——无论是在 frontmatter 之后还是标题标题之后——它都会被索引，并在每个发现结果旁呈现（在 vault_search 中，可通过 include_leading_callout 请求它）。这让笔记能够自我描述：扫描结果的 Agent 可以在决定阅读哪条笔记之前，看到每条笔记是_做什么用的_。记忆模板为此使用 > [!info] Scope of this file 标注，你的 vault 中的任何笔记都可以使用相同的模式。

配置

所有设置都是带有合理默认值的环境变量。某些默认值派生自其他设置——Default 列显示每个派生值，而你设置的值会替换整个派生默认值。远程部署还会转发 Obsidian Sync 自身的设置——DEVICE_NAME、SYNC_MODE、CONFLICT_STRATEGY、SYNC_CONFIGS、SYNC_EXCLUDED_FOLDERS、SYNC_FILE_TYPES——记录在远程指南的配置表中。

每日笔记

vault_get_daily_note 和每日回顾提示词会根据 Obsidian 中配置的文件夹和文件名日期格式查找每日笔记；这些设置从你的知识库 .obsidian/daily-notes.json 中读取：

• 本地模式会直接读取绑定挂载的知识库文件，无需进行任何设置。
• 远程模式通过 Obsidian Sync 的知识库配置同步获取这些设置。服务默认会拉取这些设置（.env 中的 SYNC_CONFIGS 设置），但你的设备也必须发送这些设置：在每台设备上启用 Obsidian 设置 → Sync → Vault configuration sync。详情请参阅远程指南中的「每日笔记」部分。

如果无法读取该文件，或者你使用的是 Periodic Notes 插件（其设置不保存在 daily-notes.json 中），请手动设置以下值：

• DAILY_NOTES_FOLDER — 任意相对于知识库的路径：Journal、Planner/Daily，或用 / 表示知识库根目录
• DAILY_NOTES_FORMAT — 使用与 Obsidian 日期格式设置相同的标记：YYYY-MM-DD-dddd、YYYY/MM/DD、MMM D, YYYY，……

你可以设置其中一项或两项——手动设置的值始终优先于配置文件。未设置的值会从 daily-notes.json 读取；如果该文件缺失或无法读取，服务会使用 Daily Notes 和 YYYY-MM-DD。

• 如果服务的知识库中存在 .obsidian/daily-notes.json，Obsidian 中的更改会在下次调用时生效。
• 通过 CLI 的 restart 命令应用环境更改，重新创建 Compose 容器，或在你的托管平台上重新部署。
• 如果你在 Obsidian 的 Daily notes 选项中将文件夹留空，服务会遵循 Obsidian 的 Default location for new notes 设置（设置 → Files and links），并从 .obsidian/app.json 读取该设置。与当前文件位于同一文件夹会被视为知识库根目录，因为 Obsidian 创建每日笔记时不会参考打开的笔记，因此也就没有可沿用的文件夹。当服务的知识库中不存在 app.json 时（例如远程模式下尚未同步 Main settings），服务会使用知识库根目录。
• 如果每日笔记位于知识库根目录，或因文件夹设置为空而位于新笔记文件夹中，删除和移动操作都不会保护这些笔记，孤立结果中也可能包含它们。保护或排除该文件夹也会影响其中的所有其他笔记。

注意： 部分日期格式标记不受支持——序数（Do、Mo、DDDo、wo）、dd（两字母星期缩写）、d（星期序号）、e、k/kk、w（周数）、Q（季度）、Z/ZZ（UTC 时差）以及本地化格式（L–LLLL、LT、LTS）。服务无法复现 Obsidian 使用这些标记创建的文件名，因此永远无法找到这些笔记。如果你的格式使用了其中任何标记，vault_get_daily_note 会返回明确的错误——请在 Obsidian 中更改格式，或将 DAILY_NOTES_FORMAT 设置为受支持的替代格式。

数据完整性

Vault Cortex 会写入个人笔记，因此文件安全层旨在防止文件损坏，而不只是避免错误。

• 原子写入 — 每次写入文件时，都会先写入临时文件，再重命名。读取者永远不会看到不完整或 0 字节的笔记。独占创建使用 link()（POSIX 禁止覆盖），以消除移动笔记时的 TOCTOU 窗口。
• 按文件加互斥锁 — 并发的 MCP 工具调用会按文件串行执行，或立即失败。移动操作会将源文件、目标文件以及每个反向链接来源锁定为一个整体。
• 编辑正文时保留原样的属性 — 编辑笔记正文不会改动其属性（Obsidian 显示为“属性”的 --- 区块），包括其中的注释。
• 无法保留时拒绝重写属性 — vault_update_properties、覆盖写入的 vault_write_note、任务工具，以及会更改区块内链接的移动操作都会重写该区块：保留每个属性及其值，移除 YAML 注释，格式也可能改变。如果区块不是有效的 YAML、是列表或单个值而非 key: value 属性，或包含带显式标签（如 !!str）的值，则拒绝重写并保持笔记不变；错误信息会说明如何修复。
• 属性有误的笔记仍可使用 — 与 Obsidian 一样，搜索会将属性为无效 YAML 的笔记视为没有属性。该笔记仍会出现在搜索结果和任务列表中，正文链接仍计为反向链接，你也可以读取、编辑和移动它，同时保持区块原样。服务日志会提示需要修复。
• 阻止路径遍历 — resolveSafePath() 会解析每个路径，然后检查其前缀。规范化后仍会拒绝删除受保护的路径。边界处会拒绝包含分隔符的记忆文件名。
• 禁止访问隐藏路径 — 以点号开头的文件和文件夹（.obsidian/、.trash/）永远不会出现在列表或搜索结果中，任何直接针对这类路径的工具调用都会被拒绝，与 Obsidian 的行为一致。插件配置及其 API 密钥无法被访问。
• 删除操作遵循 Obsidian 的回收站设置 — 如果 Obsidian 的“已删除文件”设置为默认的“移至系统回收站”或“移至 Obsidian 回收站”，删除的笔记会移至 Vault 内的 .trash/，而不会被移除（容器没有系统回收站；.trash/ 是 Obsidian 在这种情况下使用的备用位置）。“永久删除”会彻底移除笔记。
• Obsidian Sync 部署会永久删除 — 删除操作会同步到每台设备，恢复依靠 Sync 的版本历史，而非回收站文件夹。
• 限制回收站容量并定期清理 — 在系统默认设置下，服务移至 .trash/ 的笔记会在 TRASH_RETENTION_DAYS 指定的期限后清理（默认 30 天；none 表示永久保留）。清理任务只会移除服务记录过的文件；Obsidian 自行移入回收站的笔记，以及通过“移至 Obsidian 回收站”删除的笔记，都不会被触碰。
• 防止注入 — 搜索查询使用参数化处理并经过 FTS5 清理；提示词内容会用 XML 数据标记包裹，并对闭合标签进行转义，以防标签逃逸注入。
• 容器加固 — 使用非 root 用户、PID 1 初始化进程，运行时映像中不包含包管理器，基础映像固定到摘要，并支持优雅关闭。
• 只读模式 — READONLY_MODE=true 会隐藏所有可编辑 Vault 的工具，因此已连接的客户端可以读取和搜索，但无法更改笔记。

有关机制的详细信息，请参阅 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，否则在请求头中使用原始令牌（连接你的 MCP 客户端 展示了两种方式）。

OAuth 使用动态客户端注册——无需手动提供 Client ID 或 Secret：

1. 你的客户端会自动注册，并获得一个客户端 ID 和密钥。
2. 在浏览器同意页面上输入你的 MCP_AUTH_TOKEN 以批准访问。
3. 你的客户端会在后续的令牌请求中自动包含所签发的密钥。

刷新令牌具有 60 天的滑动过期时间。访问令牌绑定到你服务的 URL，因此为某个部署签发的令牌永远不会被另一个部署接受。轮换 MCP_AUTH_TOKEN 会终止所有会话——每个客户端都需要通过同意页面重新授权。

完整的流程图请参见 ARCHITECTURE.md → Auth。

部署选项

本地部署运行在你的机器上。远程部署运行在 VPS 或托管容器平台上——即使笔记本合上，依然可以访问你的库。

无论选择哪种方式，服务都可以替换，但你的库不会。你的笔记是纯 Markdown 文件，由 Obsidian 同步到你拥有的每台设备；容器中存放着一份副本和一个可从头重建的索引。关闭 VPS、删除 Render 或 Railway 服务、更换托管平台——相同的文件仍在你的机器和 Obsidian Sync 中，可供任何工具读取。这与 AI 笔记本不同，后者真正的数据都存放在供应商的数据库中：在这里，托管平台只是为了方便，并非数据的保管方。

AWS 部署方案包含专为此仓库构建的 CI/CD 工作流——部署前，Fork 用户需要配置自己的凭据和阶段。

所有部署方案都使用同一个镜像 ghcr.io/aliasunder/vault-cortex——:latest 仅包含 MCP 服务（本地部署），:remote 则在同一个容器中打包了 Obsidian Sync，并由 s6-overlay 监督运行（一键部署、自托管和 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 USD。

需要使用多个库？每个库都以独立安装的方式运行，各自拥有容器、数据和连接器。在自己的机器或服务器上，为每个安装指定不同名称：参见本地和远程指南中的运行多个库。在 Render 或 Railway 上，为每个库部署一个单独的服务。

一键部署

按钮和前置条件见快速入门 → 远程访问。每份指南都会介绍部署步骤、如何查找 URL 和令牌、如何更新和删除：deploy/render/（使用仓库根目录下的 render.yaml Blueprint）· deploy/railway/（使用已发布的模板）。

社区部署

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

• vault-cortex-aca — 由 @flytzen 提供的 Azure Container Apps Bicep 模板。通过 Container Apps 入站流量运行 :remote 镜像，并提供免费的托管 HTTPS；存储有意设为临时存储，以 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 run markdownlint && npm run lint:shell && npm run knip && npm test && npm run build

npm test 包含集成测试，会启动真实服务并通过 HTTP 调用每个工具和提示词——验证身份验证强制执行、受配置限制的工具界面、写入变更完整性（每次写入后都会读回），以及配置错误时拒绝启动。有关与安全相关的测试覆盖，请参阅 SECURITY.md。

MCP Inspector — 用于测试工具的交互式浏览器界面：

# 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 服务可独立与任何客户端配合使用。对于支持技能的 Agent（Claude Code、Cursor、Windsurf、Cline 以及其他 70 多种），obsidian-vault 技能可帮助其更深入地理解 Obsidian 风格的 Markdown，包括 frontmatter 约定、提示框语法，以及 Dataview、Tasks 和 Kanban 等插件专用格式。

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

技能源代码 →

路线图

计划中的工作、正在探索的内容以及明确不在计划内的事项，请参阅 ROADMAP.md。

致谢

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。