WorkBuddy 接入 n1mem 指南

一、这是什么 / 为什么重点

n1mem 是为 AI Agent 设计的长期记忆系统（国产第一记忆系统，对外引擎 N1Mem）。n1mem-mcp 是它的 MCP 客户端，以 stdio 方式作为 WorkBuddy 的子进程运行，把记忆能力以标准化工具暴露给 WorkBuddy 的 Agent。

本指南面向：

• 桌面端 在本机（Windows / macOS / Linux）安装并运行 WorkBuddy 桌面的用户；
• 自托管 在云端轻量服务器上运行 WorkBuddy、能拉起本地子进程的环境。

二、接入形态（stdio 直连）

三、前置要求

• Python 3.9 及以上（建议 3.10+）。n1mem-mcp 零第三方依赖、纯标准库（`requires-python = ">=3.9"`），装好 Python 即可运行。
• pip（Python 包管理器，通常随 Python 一起安装）。
• 运行 WorkBuddy 的机器能访问外网 HTTPS https://api.n1mem.com（默认端点，可覆盖）。
• 一个 n1mem API Key（见下一节）。

# 确认 Python 与 pip 版本（本机或服务器上执行，任选其一）
python3 --version
python3 -m pip --version

# 若系统自带 Python 过旧（低于 3.9），请先安装 3.10+ 后再继续

四、安装 n1mem-mcp

在运行 WorkBuddy 的那台机器上执行（桌面端用本机终端，自托管用 SSH 后的服务器终端）：

python3 -m pip install --upgrade n1mem-mcp

# 验证安装成功（应输出版本号 0.1.1）
n1mem-mcp --version

五、获取 API Key

在 注册页填写邮箱即可自助申请（内测期免费；Key 仅展示一次，请立即保存）。也可以向组织管理员索取组织级 Key。

• 你会获得形如 n1mem- 开头、共 38 位的密钥。
• ⚠️ 组织级 Key 在组织内是共享的 —— 「谁在调用」由 N1MEM_SUBJECT 声明（见第七节）。这不是可选项。
• 密钥即凭证：它绑定你的专属租户，只能读写你自己的记忆。请勿提交到代码仓库、粘贴到公开渠道。

六、WorkBuddy MCP 配置（mcp.json）

WorkBuddy 的 MCP 配置位于用户级文件 ~/.workbuddy/mcp.json：

• Windows：C:\Users\你的用户名\.workbuddy\mcp.json
• macOS / Linux：~/.workbuddy/mcp.json

若该文件已存在，请合并而非覆盖——在已有的 mcpServers 对象里新增 n1mem 一项，保留其他 server。示例完整内容：

{
  "mcpServers": {
    "n1mem": {
      "command": "n1mem-mcp",
      "env": {
        "N1MEM_API_KEY": "n1mem-你的密钥",
        "N1MEM_SUBJECT": "你给这台机器起的主体名"
      }
    }
  }
}

七、环境变量说明

主体声明 N1MEM_SUBJECT（0.3.0 起，必填）

八、激活 / 信任步骤

配置写好后，需让 WorkBuddy 加载 n1mem 这个 MCP server。两种方式任选其一：

方式 A（推荐，编辑配置文件）

• 编辑 ~/.workbuddy/mcp.json 加入上面的 n1mem 段；
• 重启 WorkBuddy 桌面/服务进程，它会在启动时读取配置并拉起 n1mem-mcp 子进程。

方式 B（通过 UI 连接器管理页添加）

• 在 WorkBuddy 的连接器管理页（右上角入口）添加 MCP server，填入同上的 command / env；
• 添加后新 server 默认处于未信任状态，需在该页面对 n1mem 点击「Trust」 才能激活；
• 激活后 WorkBuddy 加载工具，无需重启。

九、五分钟跑通步骤

1. 装包：在运行 WorkBuddy 的机器上 python3 -m pip install --upgrade n1mem-mcp。
2. 拿 Key：在 注册页自助申请（形如 n1mem- 开头的 38 位串，仅展示一次，请立即保存），或向组织管理员索取。
3. 写配置：编辑 ~/.workbuddy/mcp.json，加入上面的 JSON，填入 Key。
4. 激活：重启 WorkBuddy，或到连接器页 Trust n1mem；确认工具列表里能看到 n1mem 的 9 个工具。
5. 对话验证：对 WorkBuddy 说「记住：我的项目代号是 ProjectT1」，过一会儿再问「我的项目代号是什么？」——它应能从记忆里召回。
6. 删除验证（可选但推荐）：让 WorkBuddy 调用 memory_forget 删除该条记忆，再次询问应已遗忘。

十、验证 Checklist

十一、工具能力一览

十二、故障排查

① 重启 / 信任后 WorkBuddy 找不到 n1mem 工具

• 确认 n1mem-mcp --version 能跑通；若 command not found，说明 pip 安装到的 Python 与 WorkBuddy 用的不是同一个——用运行 WorkBuddy 的那个 Python 重装：该python -m pip install n1mem-mcp。
• 确认配置里 command 写的是 n1mem-mcp（不是路径、不是 python -m）。
• 确认 mcp.json 是合法 JSON 且 n1mem 段已合并进 mcpServers（未破坏其他 server）。
• 重启 WorkBuddy 或重新 Trust 后再看工具列表。

② API Key 未配置 / 鉴权失败

• 确认 env.N1MEM_API_KEY 已填且重启 / 信任后生效；memory_health 若报 401/403，多为 Key 缺失或错误。
• Key 不要带多余空格或引号。

②b 报 missing_subject / not_registered（0.3.0 起新增的两种）

这两种错误码含义完全不同，别混：

③ 首次调用很慢或超时

• 首调含服务冷启动（可能 20–50s），把 N1MEM_MCP_TIMEOUT 调到 120 再试。
• 云端服务器需确认能出网到 api.n1mem.com:443。

④ memory_forget 报 404

• 该 memory_id 不属于当前 Key 对应的租户，或已被删除过一次（再删即 404，属正常）。
• 确认传入的是 memory_write 返回的完整 memory_id。

十三、安全与租户隔离

• 租户隔离（RLS）：每个 API Key 对应独立租户。你的 memory_forget / memory_write / memory_recall 只能作用于你自己的记忆，无法触碰他人数据。
• 密钥管理：Key 留在你运行 WorkBuddy 的机器环境里（mcp.json 或进程环境），n1mem-mcp 只在本地子进程内使用，不会上传到除 n1mem API 之外的任何地方。
• 遗忘权：产品硬要求是「用户必须能 forget」。本指南接入的 0.1.1 已内置 memory_forget，闭环已验证。

十四、常见问题

Q：WorkBuddy 的 mcp.json 具体在哪？
A：用户级路径。Windows 为 C:\Users\你的用户名\.workbuddy\mcp.json；macOS / Linux 为 ~/.workbuddy/mcp.json。若文件不存在，直接新建并写入上面的内容即可。

Q：添加后工具列表里没有 n1mem？
A：先确认 n1mem-mcp --version 在终端能跑通（命令在 PATH 中）；再确认 mcp.json 合法且 n1mem 段已合并进 mcpServers；最后重启 WorkBuddy 或重新 Trust。详见故障排查 ①。

Q：需要点「Trust」吗？
A：如果你是在 WorkBuddy UI 的连接器页添加 MCP server，新 server 默认未信任，需手动点 Trust 激活。如果是直接编辑 mcp.json 后重启，则无需额外信任步骤。

Q：需要开放什么防火墙端口？
A：仅需出方向 443（HTTPS）到 api.n1mem.com。无需开放任何入站端口，也无需在你的机器上起任何服务。

Q：n1mem-mcp 会读我本机文件吗？
A：不会。它只做一件事：把 WorkBuddy 发来的记忆请求通过 HTTPS 转发给 n1mem API，并把结果回传。零依赖、纯标准库。

Q：升级怎么操作？
A：python3 -m pip install --upgrade n1mem-mcp，重启 WorkBuddy 即可。API 兼容，无需改配置。

Q：我的记忆存在哪里？
A：存储在 N1Mem 托管的服务端（阿里云，按租户隔离）。本地只保留密钥，不存记忆数据本身。