Vortex Notes

本地服务

vortex-notes.pages.dev记忆与知识01 周前更新

代码仓库访问官网

关于 Vortex Notes

Vortex Notes 将端到端加密的 Markdown 笔记用作个人与 Agent 的共享记忆，并提供本地语义搜索。笔记以可编辑的 Markdown 文件为源，Agent 使用独立、可授权和撤销的密钥访问指定空间。

主要功能

01端到端加密的 Markdown 笔记
02Agent 独立密钥与权限控制
03本地混合语义和关键词搜索
04跨设备同步与版本恢复
05MCP 工具及命令行操作

适用场景

01让 Agent 查询并更新项目笔记
02在任务开始时构建关联笔记上下文
03记录带时间戳的日记与可追溯事实
04在设备间同步并恢复旧版本

MCP 相关

提供 MCP 服务，包含搜索、读取、写入、编辑笔记、追加日记、记录事实和构建上下文等工具。Agent 通过独立密钥访问获授权的空间，密钥可撤销。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "vortex-303-vortex-notes": {
      "command": "npx",
      "args": [
        "-y",
        "vortex-notes"
      ],
      "env": {
        "VORTEX_NOTES_VAULT": "<VORTEX_NOTES_VAULT>",
        "VORTEX_NOTES_READONLY": "<VORTEX_NOTES_READONLY>"
      }
    }
  }
}

启动命令npx -y vortex-notes

需要配置的环境变量

VORTEX_NOTES_VAULTVault folder to serve. Optional: after `npx vortex-notes@latest pair` the paired vault is found automatically.

VORTEX_NOTES_READONLYSet to 1 for search-and-read-only access.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmvortex-notes0.1.11stdio

工具

收录的工具列表 · 更新于 1 周前

参数	类型	必填	说明
mode	enum	否	搜索模式（默认值为 hybrid）hybrid \| keyword
limit	integer	否	最大结果数（默认值为 8）
query	string	是	自然语言或关键词查询

详细介绍

Vortex Notes

端到端加密的笔记，也可作为 AI Agent 的记忆。

▶ 打开应用 · 在线演示 · npm · 自行托管

Vortex Notes 网页应用：带加密保险库的实时预览 Markdown 编辑器

你的笔记是归你所有的纯 .md 文件——可用 grep 搜索、可纳入 Git 管理，并兼容 Obsidian。 Vortex Notes 将笔记应用和 Agent 记忆库各自独有的两项功能整合到一处：

服务端无法读取任何内容。 一个 12 词短语就是你的整个账户；密钥在浏览器中派生。中继服务只存储密文——其架构中不存在明文字段，而且没有密码可重置，因为服务端没有任何需要重置的内容。
Agent 是主体，而不是乘客。 Agent 拥有自己的密钥——在其设备上生成、从不传输、由你认证、仅限你授权的空间，并且可通过一条命令撤销。它所做的每次编辑都会以 Agent 的身份签名。

这种组合——Agent 可以充分使用它，同时 服务端无法读取内容——填补了原本空缺的一角。

应用

这是真正的应用，而非查看器：可在 iPhone / Android / Mac 上安装（支持离线使用），通过 WebSocket 在不同设备间以不到一秒的速度同步，并配备 Obsidian 风格的实时预览 Markdown 编辑器，在手机上的体验和桌面设备一样出色。

手机上的 Vortex Notes Agent 和设备：每个都有自己的专属密钥，且密钥可撤销

密码锁定笔记——用密码或 12 个词锁定笔记；标题仍然可见，正文则是第二层密封内容，解锁前连你自己的设备也无法读取。
版本历史与恢复——保留每个同步版本；可恢复到较早的版本，也可找回加锁前遗失密码的笔记。
公开笔记——轻点一下，即可将任意笔记发布到带主题样式的公开页面。
更换 12 个词——轮换恢复短语而不丢失任何内容；所有已登录的设备和 Agent 都能继续使用，旧短语会失效。

Agent 记忆（MCP）

一款官方 MCP 服务为 Claude Code、OpenClaw、Cursor 或任何 MCP 客户端提供按任务设计的工具，而非 CRUD 镜像，并且支持无头运行：

search_notes · read_note · write_note · edit_note（精细编辑）
append_daily——添加带时间戳的日志条目
remember(fact, supersedes)——带有生命周期管理的事实：被取代的事实仍会显示，并带删除线标记，指向取代它的内容。可审计，而非黑盒。
build_context(topic)——获取最相关笔记的完整内容及一层 [[wikilinks]] 链接，让 Agent 一次调用就能在开始任务时获得合适的上下文。

搜索在设备端进行。 混合使用 BM25 和多语言嵌入（SQLite FTS5 + sqlite-vec + 小型本地模型）。无需 API 密钥，内容不会离开你的设备；英语查询也能在约 100 种语言的笔记中找到西班牙语内容。

快速开始

试用应用

打开 vortex-notes.pages.dev/app，创建账户（保存好 12 个词），然后开始写笔记。将其添加到主屏幕即可安装。整个入门过程就是这么简单——无需邮箱，也无需密码。

连接 Agent

在 Agent 的设备上：

npx -y vortex-notes@latest pair

它会显示一个 6 位字母代码；在应用中批准此代码（用户菜单 → Agents & devices → Pair an agent）。Agent 会获得一个专属、可撤销的密钥，且永远不会看到你的恢复短语。随后，pair 会配置它在该设备上找到的所有运行环境，并将其绑定到配对的保险库：

Claude Code：用户范围，因此每个项目都能使用
Hermes：之后输入 /reload-mcp
OpenCode：添加到 ~/.config/opencode/opencode.json

Agent 没有 MCP？同样的工具也能作为 Shell 命令使用，参见没有 MCP 的 Agent：使用相同的命令工具。也支持通过 SSH 使用（你可以在手机上批准）。对于其他任何 stdio MCP 客户端： { "command": "npx", "args": ["-y", "vortex-notes", "mcp"], "env": { "VORTEX_NOTES_VAULT": "<path pair printed>" } }。添加 --read-only 可将其设为只读。

连接 Claude.ai、ChatGPT 或其他聊天应用

浏览器或手机上的聊天应用只能通过 URL 访问 MCP 服务。在应用中：用户菜单 → Agents & devices → Connect a chat app 会创建一个云端 Agent，并提供一个私密连接器 URL：

Claude（网页、桌面、移动端）：Settings → Connectors → Add custom connector → 粘贴 URL
ChatGPT：Settings → Apps & Connectors → Advanced → Developer mode → Create → 粘贴 URL（无需身份验证）

这是零知识架构中唯一需要主动选择的例外：中继服务会保存该 Agent 的密钥（静态加密），以便提供该 Agent 可访问的笔记。密钥有访问范围限制，可设为只读，撤销后对应的 URL 即失效。其他所有内容仍保持端到端加密。

使用 CLI

npm install -g vortex-notes
vortex-notes init                              # create a vault
vortex-notes search "that idea about pricing"  # hybrid semantic + keyword
vortex-notes serve                             # local web viewer at 127.0.0.1:7303

没有 MCP 的 Agent：使用相同的命令工具

每个 MCP 工具也能作为命令使用，因此任何可以运行 Shell 的 Agent（OpenClaw 风格的运行环境、脚本、cron、git 钩子）都能获得相同行为。执行 pair 后，命令会自动找到已配对的保险库；每个命令都会在读取前和写入后同步。

npm install -g vortex-notes@latest                # once, so `vortex-notes` is on PATH
vortex-notes context "kiln"                       # top notes in full + linked notes
vortex-notes read projects/kiln.md
vortex-notes daily "fired the test tiles"
vortex-notes remember "Kiln max is cone 8" --topic kiln --supersedes "cone 10"
vortex-notes write "Glaze tests" "Three recipes…" --folder studio --tags glaze
vortex-notes edit clay.md --append "Order more in May."
vortex-notes recent --days 3 --json               # --json on any command

当 write/edit/daily/remember 的文本参数为 - 时，会从 stdin 读取内容。错误会以退出码 1 表示（使用 --json 时返回 {"error": …}）。完整列表：vortex-notes --help。这些命令也可用于一个现成的 OpenClaw 技能。

.vortex/index.db 中的索引可随时丢弃——Markdown 文件始终是事实来源。设置 VORTEX_NOTES_NO_SEMANTIC=1 可跳过嵌入（仅关键词搜索，不下载模型）。

自托管中继服务

托管中继服务 vortex-notes.pages.dev 只是为了方便，并非供应商锁定。你可以运行自己的服务：

vortex-notes relay --port 7300 --db ~/relay.db   # the ciphertext store, web app and chat connectors
vortex-notes setup --relay http://<host>:7300    # on each computer: your 12 words, then sync
npx -y vortex-notes@latest pair --relay http://<host>:7300   # an agent machine

打开 http://<host>:7300/app，在浏览器中创建账户。

你的数据就是 --db 文件（默认为 ~/.vortex-notes/relay.db）。请备份。 --db :memory: 仅用于临时测试。
聊天应用（Claude、ChatGPT）：
- 在创建连接器之前，将 RELAY_CONNECTOR_KEK 设置为 64 个十六进制字符（openssl rand -hex 32），以便对其密钥进行静态加密。
- 通过 HTTPS 提供中继服务（使用 Caddy、nginx 或隧道）：聊天应用无法访问 localhost。
- OAuth 发现会遵循 Host / X-Forwarded-Host 标头，因此反向代理可直接使用。
其他设置：
- RELAY_QUOTA_MB 限制每个账户的存储空间。
- RELAY_ADMIN_ACCOUNT（你的 Account ID）可在 Web 应用中启用管理员统计信息。
**原生应用：**Mac 和 iPhone 应用目前使用托管中继服务。CLI、Agent 和 Web 应用可与任何中继服务配合使用。

加密的工作原理

12 个词的 BIP39 助记词会派生出你账户的签名密钥和加密密钥。每台设备和每个 Agent 都有自己的随机密钥对，并由账户密钥认证，形成 account → device → agent 链。空间的内容密钥会封装给每个可能读取该空间的主体；中继会在每个已签名请求上强制执行范围和只读权限，但始终只持有已封装的数据块。

恶意中继或被传票要求配合的中继能做什么：提供过期或扣留的密文（可通过序列缺口检测）。它不能做什么：读取笔记、标题或密钥；伪造编辑；或暗中篡改内容。WebSocket 同步通道只传递不含内容的“空间已更改”通知——它只是门铃，绝不传输数据。

为了从宏观层面了解使用情况，中继会在内存中根据你的 IP 派生出一个粗略的国家/地区（两位字母代码），并且只存储该代码——IP 本身绝不会写入磁盘或记录到日志中。

技术栈

TypeScript，全部采用 MIT 许可：@noble / @scure 加密库、CodeMirror 6、 better-sqlite3、sqlite-vec、transformers.js、 marked。中继是一个小型 Node 服务；Web 应用是一个单独的 esbuild 打包文件，所有加密操作都在客户端完成。48 个单元测试，以及 10 个 Playwright 浏览器测试套件。