n1mem-mcp · N1Mem 记忆 MCP Server

powered by T1Mem engine · BYOK（自带 Key）· 零依赖（仅标准库）

让 Claude / Cursor / OpenClaw 之类支持 MCP 的客户端，直接获得 N1Mem 的长期记忆能力。

九个工具

典型用法是让模型自己用这三步： memory_skill_lookup（先查经验）→ memory_recall（再取上下文）→ memory_write（把结论存回去）。

本 Server 是薄层透传：不含任何记忆逻辑，只把工具调用转发到 N1Mem API （https://api.n1mem.com）。因此零依赖、可塞进任意环境。

安装

pip install n1mem-mcp

用到 memory_import 时还需本机有导入器：

pip install -U "n1mem>=0.2.0"

（不装也能用其它 8 个工具 —— memory_import 会在调用时给出这条安装提示， 而不是甩一个 ImportError 堆栈。）

实例身份（设备授权）

MCP Server 支持把请求绑定到具体设备：设置环境变量 N1MEM_INSTANCE=<local_id>:<secret> 即可让通过该 Server 的记忆写入带设备级标识，配合服务端「实例强制」模式可实现设备级隔离与撤销。 默认不设置，行为不变（0.3.1 新增）。

获取 Key

访问 https://api.n1mem.com/register 自助注册，邮箱即拿到形如 tk_xxx 的 Key。

配置（Cursor / Claude / OpenClaw）

把下面片段加进你的 MCP 配置（~/.cursor/mcp.json、Claude 的 claude_desktop_config.json、 或 OpenClaw 的 MCP 配置）：

{
  "mcpServers": {
    "n1mem": {
      "command": "n1mem-mcp",
      "env": { "N1MEM_API_KEY": "tk_xxx" }
    }
  }
}

或用模块方式启动（无需 pip install 也可，只要能 import）：

{
  "mcpServers": {
    "n1mem": {
      "command": "python",
      "args": ["-m", "n1mem_mcp"],
      "env": { "N1MEM_API_KEY": "tk_xxx" }
    }
  }
}

环境变量

主体声明 N1MEM_SUBJECT（0.3.0 新增）

Key 回答「哪个组织」，N1MEM_SUBJECT 回答「谁」。 同一台机器上跑多个 Agent 时， 它们共用一个主体 —— 别把它和 N1MEM_AGENT_ID 混起来：后者是「哪个 Agent」， 只用于本地埋点（跨 Agent 命中率统计），不是身份。

在你的 MCP 配置里加一个键即可：

"env": { "N1MEM_API_KEY": "tk_xxx", "N1MEM_SUBJECT": "workbuddy-pc" }

• 须与组织里已登记的主体名逐字一致；拼错不会报错，服务端只会认为「未登记」。
• 不设 ⇒ 不发该头，行为与 0.3.0 之前完全一致（可随时去掉该键回退）。
• 🔴 不要把它设成 N1MEM_AGENT_ID 的值（那是 Agent 类型名，如 workbuddy）—— 登记名与声明名对不上时，接入会一直停在「未登记」，而且没有任何报错。

memory_import 用法

memory_import(dry_run=true)     # 先看会导入什么（条数 / 字节 / 分层），不写任何数据
memory_import()                 # 确认后真导（默认 identity + skill 两层）
memory_import(path="…", layers=["identity","skill","note"])

导入是在本机读你磁盘上的记忆资产，服务端只接收结构化条目。 想撤销：用服务端按批次 rollback（返回值里带 source_id），或对单条用 memory_forget。

已知限制（诚实告知）

• 暂无 update 工具（服务端更新能力未就绪，故不暴露，避免客户端以为支持）。 删除是支持的（memory_forget）—— 0.1.x 的说明曾写"暂无 delete"，与实现不符，0.2.0 已更正。
• memory_health 如实反映服务健康：未配置的上游不会拉低整体状态；只有当"已配置的上游" 或存储真的不可用时才返回 degraded（0.2.1 修正：此前会把未配置的 provider 误算成 down， 导致核心链路全绿却报 degraded）。
• memory_import 目前支持 WorkBuddy（~/.workbuddy）与关键文档目录两种来源。

与 n1mem 的区别

两者都遵守 BYOK：Key 由你提供，SDK 与 Server 都不存储、不上传你的凭据。