n1mem 是为 AI Agent 设计的长期记忆系统。n1mem-mcp 是它的 MCP（Model Context Protocol）客户端，以 stdio 方式作为 OpenClaw 的子进程运行，把记忆能力以标准化工具暴露给 OpenClaw。
本指南面向：
| 维度 | 本地电脑（形态 A） | 云端轻量服务器（形态 B） |
|---|---|---|
| OpenClaw 位置 | 你的笔记本 / 台式机 | 你 SSH 上去的云服务器 |
| 能否拉起子进程 | 能（本机 Python 进程） | 能（服务器上的 Python 进程） |
| n1mem-mcp 接入方式 | stdio 直连 | stdio 直连（完全一致） |
| 出网到 api.n1mem.com | 取决于本机网络 | 需服务器放行 443 出方向 |
| 密钥存放位置 | 本机环境 / OpenClaw 配置 | 该服务器环境 / OpenClaw 配置 |
https://api.n1mem.com（默认端点，可覆盖）。# 确认 Python 与 pip 版本（本地或云端服务器上执行，任选其一）
python3 --version
python3 -m pip --version
# 若系统自带 Python 过旧，请先安装 3.10+ 后再继续在运行 OpenClaw 的那台机器上执行（形态 A 用本机终端，形态 B 用 SSH 后的服务器终端）：
python3 -m pip install --upgrade n1mem-mcp
# 验证安装成功（应输出版本号 0.1.1）
n1mem-mcp --versionn1mem-mcp，OpenClaw 正是通过这个命令拉起子进程。不要用 python -m n1mem_mcp 之外的复杂方式——配置里直接写 "command": "n1mem-mcp" 即可。
在 注册页填写邮箱即可自助申请（内测期免费；Key 仅展示一次，请立即保存）。也可以向组织管理员索取组织级 Key。
n1mem- 开头、共 38 位的密钥。N1MEM_SUBJECT 声明（见第七节）。这不是可选项。在 OpenClaw 的 MCP 配置文件（通常为 mcp.json 或设置中的 MCP 段）加入以下内容：
{
"mcpServers": {
"n1mem": {
"command": "n1mem-mcp",
"env": {
"N1MEM_API_KEY": "n1mem-你的密钥",
"N1MEM_SUBJECT": "你给这台机器起的主体名"
}
}
}
}command 指向可执行命令；env.N1MEM_API_KEY 放你的密钥；env.N1MEM_SUBJECT 填这台机器的主体名（不是 workbuddy 这类 Agent 类型名 —— 见第七节「主体声明」）。保存后重启 OpenClaw，它会在启动时自动拉起 n1mem-mcp 子进程并发现 9 个工具。
| 变量 | 必填 | 默认值 | 说明 |
|---|---|---|---|
N1MEM_API_KEY | 是 | 无 | API 密钥，仅从环境变量读取，绝不硬编码 |
N1MEM_SUBJECT | 是 | 无 | 主体名（谁在调用）—— 服务端据此反查"这台设备有没有被授权接入"；不设 ⇒ 不发该头，请求会被拒（missing_subject）。见下节。 |
N1MEM_BASE_URL | 否 | https://api.n1mem.com | API 基址，一般无需改 |
N1MEM_MCP_TIMEOUT | 否 | 90（秒） | 单次请求超时。首调含服务冷启动可能 20–50s，若偶发超时可调大到 120 |
N1MEM_SUBJECT（0.3.0 起，必填）Key 回答「哪个组织」，N1MEM_SUBJECT 回答「谁」。
同一个组织下可能有多台设备 / 多个人在调用；服务端要靠主体名反查成员表，
判断这台设备是否已被授权接入。不声明主体 ⇒ 服务端回 missing_subject，记忆请求会被拒。
workbuddy-pc、zhangsan-laptop；workbuddy / codex 这种「Agent 类型名」——
它不是身份。服务端会去成员表里找一个叫 workbuddy 的主体，查不到，
于是返回 not_registered，而你会以为是别的问题；另有一个 N1MEM_AGENT_ID，答的是「哪个 Agent」（仅用于本地埋点统计，跨 Agent 命中率）。
两者刻意不互相回落 —— 拿 Agent 类型名当主体，正是上面那条坑。
python3 -m pip install --upgrade n1mem-mcp。n1mem- 开头的 38 位串，仅展示一次，请立即保存），或向组织管理员索取。memory_forget 删除该条记忆，再次询问应已遗忘。| ✓ | 检查项 | 预期结果 |
|---|---|---|
| 1 | n1mem-mcp --version | 输出版本 0.1.1 |
| 2 | OpenClaw 工具列表 | 含 memory_write / memory_recall / memory_health / memory_forget |
| 3 | memory_health | 返回服务状态正常 |
| 4 | memory_write 一条信息 | 返回 memory_id（如 mem_xxx） |
| 5 | memory_recall 同一信息 | 召回命中，answer 接地、retrieved 非空 |
| 6 | memory_forget 该 memory_id | 返回 {"deleted": true} |
| 7 | 再次 memory_recall | 不再命中（retrieved 为空） |
| 工具 | 入参 | 作用 |
|---|---|---|
memory_write | text（字符串，必填） | 写入一条记忆，返回 memory_id |
memory_recall | prompt（字符串，必填） | 按语义召回相关记忆，返回 answer + retrieved 列表 |
memory_health | 无 | 探活，返回服务与端点状态 |
memory_forget | memory_id（字符串，必填） | 删除指定记忆，仅能删自己的，返回 {"deleted": true} |
n1mem-mcp --version 能跑通；若 command not found，说明 pip 安装到的 Python 与 OpenClaw 用的不是同一个——用运行 OpenClaw 的那个 Python 重装：该python -m pip install n1mem-mcp。command 写的是 n1mem-mcp（不是路径、不是 python -m）。env.N1MEM_API_KEY 已填且重启后生效；memory_health 若报 401/403，多为 Key 缺失或错误。missing_subject / not_registered（0.3.0 起新增的两种）这两种错误码含义完全不同，别混：
| 返回 | 含义 | 动作 |
|---|---|---|
missing_subject |
请求没带主体头 ⇒ 客户端没声明"谁在调用" | 在配置的 env 里加 N1MEM_SUBJECT，重启后生效 |
not_registered |
声明了主体，但这个名字没在本组织登记过 | 用安装器的「检查接入状态」；或联系组织管理员把你加进来。重复安装不会改变状态 |
pending |
已提交，在等管理员审批（这是正常状态，不是错误） | 不需要重装，过一会儿再查一次 |
N1MEM_SUBJECT 填成了 Agent 类型名（workbuddy）。
服务端确实"收到了主体"，但成员表里没有这个名字 ⇒ 返回 not_registered，
而人会去怀疑 Key 或网络。先核对主体名。
N1MEM_MCP_TIMEOUT 调到 120 再试。api.n1mem.com:443。memory_id 不属于当前 Key 对应的租户，或已被删除过一次（再删即 404，属正常）。memory_write 返回的完整 memory_id。memory_forget / memory_write / memory_recall 只能作用于你自己的记忆，无法触碰他人数据。memory_forget，闭环已验证。Q：云端轻量服务器上能直接用吗？
A：能。只要服务器上装了 Python3 + pip，照常 pip install n1mem-mcp 并配置 OpenClaw 即可。差异只是运行环境在云端，客户端配置与本机完全一致。
Q：需要开放什么防火墙端口？
A：仅需出方向 443（HTTPS）到 api.n1mem.com。无需开放任何入站端口。
Q：n1mem-mcp 会读我本机文件吗？
A：不会。它只做一件事：把 OpenClaw 发来的记忆请求通过 HTTPS 转发给 n1mem API，并把结果回传。零依赖、纯标准库。
Q：升级怎么操作？
A：python3 -m pip install --upgrade n1mem-mcp，重启 OpenClaw 即可。API 兼容，无需改配置。
Q：我的记忆存在哪里？
A：存储在 N1Mem 托管的服务端（阿里云，按租户隔离）。本地只保留密钥，不存记忆数据本身。