Metadata-Version: 2.1
Name: n1mem-mcp
Version: 0.2.0
Summary: N1Mem MCP server (BYOK, zero dependencies) — long-term memory for Claude / Cursor / OpenClaw, including one-call import of your existing agent memory
Author: N1Mem (powered by T1Mem engine)
License: Proprietary
Project-URL: Homepage, https://www.n1mem.com
Keywords: mcp,memory,llm,agent,n1mem,t1mem,claude,cursor,openclaw
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# n1mem-mcp · N1Mem 记忆 MCP Server

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

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

## 六个工具

| 工具 | 作用 |
|---|---|
| `memory_write` | 写入一段记忆（持久化 + 建向量，**写入即可召回**） |
| `memory_recall` | 按自然语言问题召回；`answer` 已基于命中记忆接地，`retrieved` 给出命中的明文记忆 |
| `memory_import` | **把本机已有的 Agent 记忆批量迁进来**（身份层 + 技能层），可 `dry_run` 先预览 |
| `memory_skill_lookup` | 任务开始前查「有没有现成经验可复用」，返回匹配的 skill 与要点 |
| `memory_forget` | 遗忘指定记忆（按 id，RLS 隔离，只能删自己的） |
| `memory_health` | 查看服务健康与 provider 可用性 |

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

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

## 安装

```bash
pip install n1mem-mcp
```

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

```bash
pip install -U "n1mem>=0.2.0"
```

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

## 获取 Key

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

## 配置（Cursor / Claude / OpenClaw）

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

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

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

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

## 环境变量

| 变量 | 说明 | 默认 |
|---|---|---|
| `N1MEM_API_KEY` | 你的 Key（必填） | 空 |
| `N1MEM_BASE_URL` | API 地址 | `https://api.n1mem.com` |
| `N1MEM_MCP_TIMEOUT` | 单条调用超时（秒） | `90` |

## `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` 可能返回 `status: degraded`：这是设计使然（部分上游 provider 未配置），
  核心记忆链路（存储 / 嵌入 / 写入 / 召回）正常。
- `memory_import` 目前支持 WorkBuddy（`~/.workbuddy`）与关键文档目录两种来源。

## 与 `n1mem` 的区别

| 包 | 形态 | 用途 |
|---|---|---|
| `n1mem` | Python SDK（函数调用） | 代码里直接 `m.ingest() / m.recall() / m.ingest_batch()` |
| `n1mem-mcp` | MCP Server（stdio） | 让 MCP 客户端（Claude / Cursor / OpenClaw）以工具方式调用记忆 |

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