keephaven-mcp

Name: keephaven-mcp
Author: dafarusd

本地服务

github.com/dafarusd记忆与知识03 天前更新

代码仓库

关于 keephaven-mcp

keephaven-mcp 将 Keephaven 设备上的文件记忆和追加式日志提供给 AI Agent，适合希望把 Agent 长期记忆保存在自有设备上的用户。它支持按 Agent 隔离存储、搜索及权限和配额管理。

主要功能

01读写和列出记忆文件
02跨文件与日志搜索
03追加并读取不可修改的日志
04按 Agent 隔离文件夹
05设置只读权限和存储上限

适用场景

01保存 Agent 可复用的长期信息
02搜索记忆文件和历史日志
03为不同 Agent 分开管理记忆
04限制某个 Agent 的写入或存储量

MCP 相关

它通过 MCP 服务向客户端提供文件记忆、搜索和日志工具。客户端使用 Keephaven URL 和令牌连接服务。

配置

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

mcp.json · 通用配置

{
  "mcpServers": {
    "dafarusd-keephaven": {
      "command": "npx",
      "args": [
        "-y",
        "@dafarusd/keephaven-mcp"
      ],
      "env": {
        "KEEPHAVEN_URL": "<KEEPHAVEN_URL>",
        "KEEPHAVEN_TOKEN": "<KEEPHAVEN_TOKEN>"
      }
    }
  }
}

启动命令npx -y @dafarusd/keephaven-mcp

需要配置的环境变量

KEEPHAVEN_URLThe box's memory API, e.g. http://keephaven-xxxx.local:8790

KEEPHAVEN_TOKEN密钥Agent token from Settings > Agents on the box

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

安装包

npm@dafarusd/keephaven-mcp0.1.0stdio

工具

收录的工具列表 · 更新于 3 天前

此工具无需参数。

详细介绍

keephaven-mcp

让你的 Agent 在家中的设备上拥有记忆。这是一个 MCP 服务，让 AI Agent 将长期记忆存储在 Keephaven 上，而不是供应商的服务端。

适用于运行本地服务的 MCP 客户端，例如 Claude Desktop、Claude Code 和 Cursor。

Agent 能做什么

工具	功能
`memory_write`	保存文件，例如 `people/dafarus.md` 或 `projects/keephaven.md`。可选的 etag 检查可防止两个会话互相覆盖。
`memory_read`	读取文件，并返回其 etag。
`memory_list`	列出文件，可选指定文件夹。
`memory_search`	在文件和日志中进行不区分大小写的搜索。
`memory_delete`	删除文件。
`journal_append`	向只追加日志添加条目。Agent 可以向其中添加内容，但不能编辑或删除。
`journal_read`	按从旧到新的顺序读取近期日志条目。
`memory_status`	查看名称、是否只读以及已用配额。

所有者可以掌控什么

每个 Agent 都有自己的文件夹，无法查看其他 Agent 的文件夹。
在 Keephaven 的 Settings > Agents 中添加 Agent，即可获取一个令牌；令牌只会显示一次。设备只会存储它的指纹。
撤销令牌后，Agent 会立即失去访问权限。删除文件前，这些文件会继续保留。
可为每个 Agent 设置大小限制，或将其设为只读。
如果你的 Keephaven 会备份到另一台设备，Agent 的文件夹也会包含在备份中，而且备份设备会拒绝所有删除操作。这一功能尚未在两台真实设备之间测试。

设置

在 Keephaven 上打开：Settings > Agents > Add an agent。复制页面显示的两个值。
将服务添加到 MCP 客户端。对于 Claude Desktop，在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "keephaven": {
      "command": "npx",
      "args": ["-y", "github:dafarusd/keephaven-mcp"],
      "env": {
        "KEEPHAVEN_URL": "http://keephaven-xxxx.local:8790",
        "KEEPHAVEN_TOKEN": "khm_..."
      }
    }
  }
}

对于 Claude Code：

claude mcp add keephaven -e KEEPHAVEN_URL=http://keephaven-xxxx.local:8790 -e KEEPHAVEN_TOKEN=khm_... -- npx -y github:dafarusd/keephaven-mcp

该服务直接从 GitHub 安装，因此首次启动时需要构建，耗时约一分钟。需要 Node 20 或更高版本。

运行 Agent 的设备必须能够访问 Keephaven：连接到同一家庭网络、Keephaven 自带的 Wi-Fi，或在开启远程访问后连接到你的 Tailscale tailnet。

没有设备也可以试用

设备使用一个没有依赖项的 Python 文件运行服务。使用 Python 3，在任意位置运行同一个文件：

python3 agent-memory.py serve --data ./mem --bind 127.0.0.1 --dev-token khm_try-it-locally

然后将 MCP 服务指向 http://127.0.0.1:8790，并使用该令牌。此文件位于 Keephaven 仓库的 modules/agent-memory.py。

如实说明当前状态

记忆服务已完成构建和测试：包含 22 项 API 测试，以及一项双虚拟机 NixOS 测试；测试中服务以独立的受限用户身份运行，另一台设备通过网络使用该服务。
此 MCP 服务有 7 项端到端测试：使用官方 MCP 客户端、通过 stdio 运行此服务，以及连接真实记忆服务。
它随 Keephaven Agent Memory 一同发布，于 2026-10-25 面向 Pi 5 和 Windows PC 上的 USB SSD 发布：https://keephaven.co/agent-memory。Pi 版本在一台 Pi 5 上通过了发布检查；SSD 版本在 Windows PC 上的真实硬盘上通过了检查。备份通过 Tailscale 从一台真实 Pi 5（预发布构建）运行到虚拟机中的 PC 构建——尚未在两台真实设备之间测试。Home 和 Photos 设备尚未提供此功能。
令牌在家庭网络中通过普通 HTTP 传输，和设备上的其他本地页面一样。通过 Tailscale 传输时则会加密。

Agent 技能

skill/keephaven/ 是一项 Agent 技能（包含 SKILL.md 和只读的 check.py）：介绍如何将 Keephaven 用作记忆，以及如何在虚拟机中启动它并报告运行情况。check.py 已在 QEMU 中启动的 Photos SSD 镜像上运行：设置页面正常，随后设备就绪、Photos 启动，Immich 版本为 3.0.3。

由 @Dafarusd 构建。MIT 许可证。

支持 Markdown

登录后评论