Everkeep

Everkeep

别再反复向你的 AI 解释自己。

Everkeep 会将你的笔记、决策和项目保存在你自己的服务器上的一个文件夹中。聊天开始时，你的 AI 助手会读取其中的内容，并记下你们讨论出的结果——这样，明天的对话就能从今天结束的地方继续。你可以决定它能修改什么；未经允许，它无法删除或覆盖任何内容。

适用于 Claude 和任何 MCP 客户端 · 可在 Linux、Docker 或 Home Assistant 上运行

你的文档也能用

将合同、发票、手册、价目表和导出的报告原样放进文件夹，支持 PDF、Word、Excel、PowerPoint 和电子邮件。你的 AI 会将它们作为文本读取，同时搜索所有文档，并告诉你答案来自哪里：问“哪份合同的付款期限是 30 天？”，它会给出文件和页码。无需在每次聊天时上传文件，也无需复制粘贴；需要时，AI 会读取文件的新版本。对于扫描页，它会以图像形式查看。

只需像复制到其他文件夹一样，将文件复制到该文件夹中：请参阅添加文件。

快速入门

本指南将教你使用 Docker 在自己的电脑上运行 Everkeep，并将 Claude 连接到它。整个过程约需 10 分钟，无需编程。

1. 安装 Docker。 在 Windows 或 macOS 上，安装 Docker Desktop 并启动；等待它显示 Docker 正在运行。在 Linux 上，安装 Docker Engine。

2. 启动 Everkeep。 打开终端（Windows 上使用 PowerShell；macOS 上使用 Terminal），粘贴适用于你系统的两行命令。第一行会在你的主文件夹中创建 everkeep-notes 文件夹，你的笔记将存放在此文件夹中。第二行会下载 Everkeep 并在后台启动；电脑重启后它会自动再次启动。

Windows（PowerShell）：

mkdir $HOME\everkeep-notes
docker run -d --name everkeep --restart unless-stopped -p 127.0.0.1:3100:3100 -v "$HOME\everkeep-notes:/vault" -v everkeep-data:/data ghcr.io/st412m/everkeep:1.0.0

macOS 或 Linux：

mkdir -p ~/everkeep-notes
docker run -d --name everkeep --restart unless-stopped -p 127.0.0.1:3100:3100 -v "$HOME/everkeep-notes:/vault" -v everkeep-data:/data ghcr.io/st412m/everkeep:1.0.0

在 Linux 上，该文件夹必须可由用户 ID 1000 写入。如果命令 id -u 输出的是其他数字，请改为按照 Docker：文件夹的所有者 操作。

3. 保护你的笔记。 在同一个终端中再输入一行：

docker exec everkeep everkeep policy set . --mode rev --trash

从现在起，Claude 可以在文件夹中创建新文件，但只有先读取现有文件后才能修改它，因此它绝不会覆盖自己未查看过的内容。任何内容都不会被删除：Claude 丢弃的文件会移至 everkeep-notes 中的 .vault-trash 文件夹，你可以从那里恢复文件。

4. 获取你的令牌。 Everkeep 在首次启动时生成了一个机密令牌。显示令牌：

docker exec everkeep everkeep token

命令会输出两行。第一行是用于 claude.ai 的机密路径，第二行是供其他客户端使用的标头：

/private_<token>/mcp
Authorization: Bearer <token>

请像保护密码一样保护这两项信息：任何拥有它们的人都可以读取和修改你的笔记。

5. 连接 Claude。

• 同一台电脑上的 Claude Code：

  claude mcp add --transport http everkeep http://127.0.0.1:3100/mcp --header "Authorization: Bearer <token>"
  

• 同一台电脑上的 Claude Desktop： 将 Claude Desktop 中的代码块添加到其配置文件，然后重启。

• 浏览器中的 claude.ai 或 Claude 应用： 它们通过互联网连接，因此 Everkeep 需要一个公开的 HTTPS 地址。远程访问将逐步介绍两种免费的设置方式。然后，在 claude.ai → Settings → Connectors → Add custom connector 中，粘贴 https://<your public address>/private_<token>/mcp。

6. 试用。

• 向 Claude 提问：“使用 Everkeep，根据你对我当前项目的了解创建一个 about-me.md 文件。” 该文件会出现在你的 everkeep-notes 文件夹中。
• 打开文件夹：在 Windows 上，在同一个 PowerShell 中输入 explorer $HOME\everkeep-notes（或者依次打开“此电脑” → “用户” → 你的用户名 → everkeep-notes）；在 macOS 上，在 Terminal 中输入 open ~/everkeep-notes（或者在 Finder 中打开你的主文件夹）；在 Linux 上，在文件管理器中打开你的主文件夹。
• 将合同、发票或任何 PDF、Word 文件拖入文件夹，或复制粘贴进去，就像放入任何文件夹一样。Everkeep 会立即发现这些文件，无需重启。你也可以在其中创建文件夹，这样很方便：contracts/、projects/…。
• 向 Claude 提问：“使用 Everkeep：我的笔记中的合同对付款条款是怎么说的？请给出页码。”

如果希望 Claude 在每次聊天开始时读取你的笔记，可在 Settings → Account → Instructions for Claude 中添加一行类似这样的说明，或将其添加到某个项目的说明中：“聊天开始时，使用 Everkeep 读取 /vault/about-me.md。” 在 Docker 中，你的文件夹路径是 /vault。

若要更改某个文件夹的规则，请参阅写入策略。

它是什么

Everkeep 是一个 MCP 服务。MCP 是 Claude 等 AI 客户端在其他机器上调用工具的方式。Everkeep 的工具仅在一个目录树中运行，即 vault：读取、搜索、编辑、移动和丢弃文件，读取文档和 PDF，以及以只读方式查询 SQLite 数据库。无法通过它访问 vault 之外的任何内容。

助手可以更改的内容由每个目录的 写入策略 设置：目录可以是只读的、仅允许已读取文件当前版本的人编辑的、仅允许新建文件的，或完全开放的。没有删除操作：丢弃文件会将其移入所在区域的回收站目录。助手无法更改策略；策略由你在服务端设置。

它以单个进程运行，通过 HTTP 为 claude.ai 等远程客户端提供服务，通过标准输入输出为 Claude Desktop 等本地客户端提供服务。

效果展示

助手列出一个目录。第一行会说明该目录允许进行哪些操作：

Policy: overwrite=rev, trash=.vault-trash, auto-purge after 30 d — own marker (/vault/wiki/.vault-policy)

[FILE] .vault-policy
[DIR] .vault-trash
[FILE] decisions.md
[FILE] todo.md

它尝试覆盖 todo.md，但尚未读取该文件，因此被拒绝：

Error: Refused — policy "overwrite: rev": changing an existing file requires its current rev, which is 5db20d56. Nothing was written. Repeat the call with rev: "5db20d56".

它搜索内容，获取行号和文件的 rev，然后编辑一行：

/vault/wiki/todo.md · rev 5db20d56 · 212 lines
  148: - [ ] Check backup-rotation settings on the NAS

— 1 match(es) in 1 file(s) · scanned 37/37 files, 190 KB, 12 ms

要求

Docker	Docker Desktop（Windows、macOS）或 Docker Engine（Linux）；提供适用于 amd64 和 arm64（Raspberry Pi 4/5）的镜像
不使用 Docker 的 Linux	Node.js ≥ 22.17、poppler-utils（pdfinfo、pdftoppm）、sqlite3
Home Assistant	OS 或 Supervised，通过 ha-filesystem-mcp 应用运行
磁盘空间	Docker 镜像约为 340 MB；包含依赖项的 npm 包约为 48 MB
使用 claude.ai	一个公开的 HTTPS 地址：参见远程访问

安装

Docker

镜像 ghcr.io/st412m/everkeep 以用户 ID 1000 在端口 3100 上运行 everkeep serve，vault 位于 /vault，自身状态（令牌、文档缓存）存储在卷 /data 中。快速入门展示了 docker run 的用法；compose.example.yaml 使用 Docker Compose 实现相同效果。文件夹所有权、更新和自行构建镜像：参见安装。

不使用 Docker 的 Linux

使用包管理器安装 poppler-utils 和 sqlite3，然后通过 npx 运行：

npx --yes --package=everkeep everkeep serve --vault /home/me/notes

首次启动时会显示一次令牌；再次运行 everkeep token 可查看令牌。关于安装永久可用的 everkeep 命令、在不支持 AVX 的 CPU（部分 Celeron、Atom 和 Pentium 型号）上运行，以及配置 systemd 服务，请参见安装。不使用 Docker 时不支持 Windows 和 macOS。

Home Assistant

安装 ha-filesystem-mcp 应用。该应用会在 /media 或 /share 下的 vault 中运行 Everkeep，并在侧边栏中添加 Vault 策略页面。

配置

设置可以通过标志、环境变量和可选的 JSON 文件（EVERKEEP_CONFIG，否则为 ~/.config/everkeep/config.json）指定。首先需要了解的设置：

设置	标志 / 变量	默认值
vault	--vault、EVERKEEP_VAULT	无，必填
host	--host	127.0.0.1
port	--port	3100
state_dir	EVERKEEP_STATE_DIR	~/.local/state/everkeep
令牌	--token-file、EVERKEEP_TOKEN	生成到 <state_dir>/token

everkeep check-config 会打印当前生效的配置，并检查 Everkeep 所需的工具。关于所有配置项、令牌规则和请求日志：参见配置。

连接

• **claude.ai、Claude Desktop 连接器、Claude 应用：**在 设置 → 连接器 → 添加自定义连接器 中填写 https://<your-host>/private_<token>/mcp。地址必须是公开的 HTTPS 地址：远程访问。

• **Claude Code：**通过 HTTP 携带 Bearer 标头，或通过 stdio：

  claude mcp add --transport stdio everkeep -- npx --yes --package=everkeep everkeep --vault /home/me/notes
  

• **没有公开地址的 Claude Desktop：**通过 Docker 使用 stdio 运行 Everkeep，参见 Claude Desktop。

• **Cursor 和其他客户端：**使用 URL http://127.0.0.1:3100/mcp（或你的 HTTPS 地址）以及标头 Authorization: Bearer <token>，参见安装。

没有 OAuth：令牌是唯一的密钥。路径错误会返回空的 404，Bearer 令牌错误则返回 401。

工具

共 20 个工具。参数和返回格式：工具。

读取

• read_text_file — 读取整个文件、head/tail 行，或带行数和 rev 的 offset/limit 范围；文档会以编号行的形式返回
• read_file — read_text_file 的已弃用别名
• read_multiple_files — 在一次响应中读取多个完整文件
• read_media_file — 将图像或音频作为 base64 读取；将 PDF 页面读取为 JPEG（路径后缀使用 #N）
• read_pdf_text — 读取 PDF 文本或页面范围，编号方式与 read_text_file 相同
• read_pdf_page — 将单个 PDF 页面渲染为 JPEG

搜索

• grep_files — 使用正则表达式搜索文件内容，包括文档；返回路径、rev、行数和匹配行
• search_files — 按名称查找文件和目录

写入

• write_file — 创建或覆盖文件
• edit_file — 按字面内容替换 oldText，或通过受 rev 保护的行号编辑
• create_directory — 创建目录及其父目录
• move_file — 移动或重命名文件或目录；也可从废纸篓恢复
• trash_file — 将文件移入所属区域的废纸篓；不提供删除功能

列出

• list_directory — 在策略行之后列出一个目录的条目
• list_directory_with_sizes — 列出条目及文件大小，按名称或大小排序
• directory_tree — 显示两层深度的目录树
• get_file_info — 显示大小、时间和格式；文本文件还会显示行数和 rev
• list_allowed_directories — 知识库根目录

SQLite（只读）

• sqlite_schema — 显示每个对象的 DDL、文件 pragma，以及可选的行数
• sqlite_query — 执行一条带行数限制的 SELECT/WITH/VALUES/EXPLAIN 语句

搜索后编辑的工作流见搜索和编辑，SQLite 见 sqlite。

写入策略

如果没有策略，任何工具都可以在知识库中的任意位置写入。策略是放在某个目录中的小型文件 .vault-policy，适用于该目录及其所有子目录。在服务器上设置策略：

everkeep policy set wiki --mode rev --trash --purge-days 30 --vault /home/me/notes
everkeep policy set raw --mode readonly --vault /home/me/notes

模式	效果
readonly	禁止写入、编辑、移入或移出，以及丢弃
rev	新文件不受限制；更改、移出或丢弃现有文件时，需要提供其当前 rev
never	仅允许创建新文件；无法更改现有文件
free	不进行检查

使用 Docker 时，请在容器内运行相同的命令：docker exec everkeep everkeep policy show。在 Home Assistant 应用中，请使用侧边栏中的 Vault policies 页面。关于废纸篓、自动清空，以及损坏的标记会产生什么影响，请参见写入策略。

文档和格式

read_text_file 和 grep_files 会将 PDF、Word、Excel、PowerPoint、OpenDocument、EPUB、FB2、RTF、HTML 和邮件文件读取为带有页面、工作表和幻灯片标记的编号行；grep_files 会报告匹配项的位置（L8 (p.1)、L2 (sheet Data)）。扫描版 PDF 没有文本；回答会指出需要用 read_pdf_page 作为图像读取的页面。文档为只读。提取的文本会缓存在知识库之外。格式、限制和缓存：文档。

限制

• 仅支持不使用 Docker 的 Linux。 Windows 和 macOS 需在 Docker 中运行。
• 不支持 OAuth。 路径中的令牌或 Bearer 标头是唯一的密钥。
• 不支持删除。 trash_file 会将文件移入垃圾目录，且仅限有垃圾目录的区域。
• SQLite 为只读，并将一直保持只读。
• 文档为只读，扫描件无法识别为文本（不支持 OCR）。
• 策略仅限制 Everkeep 的工具。 任何其他写入文件夹的操作——无论是你、同步任务还是文件共享——都不会遵守这些策略。
• 客户端会缓存工具列表。 更新导致工具发生变化后，已打开的对话仍会保留旧列表。

故障排除

• Claude 中没有显示 Everkeep 工具。 检查容器是否正在运行（docker ps）、URL 或标头中的令牌是否为当前令牌（everkeep token），以及 claude.ai 是否能从外部访问 HTTPS 地址。
• 所有写入操作都因 EACCES 失败。 知识库文件夹不可由 Everkeep 运行时使用的用户写入（Docker 中的用户 ID 为 1000）。
• 400 / 401 / 403 / 404 / 405 / 406。 401：Bearer 令牌错误。404：路径或路径中的令牌错误。403：在监听 127.0.0.1 的服务上，Host 或 Origin 既不是本地地址，也不在 allowed_hosts 中。405：请求方法不是 POST。406：Accept 标头未列出 JSON 或事件流。400：JSON 无效或不支持的 MCP-Protocol-Version。
• 所有写入操作均被拒绝，且列表中显示 ⚠ Policy: BROKEN MARKER。 .vault-policy 文件已损坏，并锁定了所在区域。使用 everkeep policy 修复，或手动修复。

更多信息：故障排除。

安全

• 令牌就是密码。它由服务生成，至少 32 个字符，且绝不会记录到日志中；对于任何可从你的设备之外访问的地址，都应在其前面配置 TLS。
• 所有路径都限制在知识库内，包括通过符号链接访问的路径以及大小写不敏感文件系统上的路径。
• 在 127.0.0.1（不使用 Docker 时的默认地址）上，如果请求的 Host 或 Origin 不是本地地址，请求将被拒绝，以阻止浏览器中的网站访问该服务。
• 令牌和文档缓存位于状态目录中，该目录必须在知识库之外。
• grep_files 会在子进程中运行，并在 10 秒后终止；文档会在工作线程中提取，并设有超时和内存上限；SQLite 使用 sqlite3 -readonly -safe 运行。

更多信息：安全。

链接

• 文档 — 安装、 添加文件、 远程访问、 配置、 编写策略、 工具、 搜索和编辑、 文档、 sqlite、 安全、 故障排除、 内部机制
• Home Assistant 应用
• 更新日志
• 问题：此处反馈服务的问题；在 ha-filesystem-mcp 中反馈安装或运行 Home Assistant 应用的问题

许可证

MIT — 由 st412m 编写。