# MemAura MCP Server for DeepSeek Harness

把 MemAura 云端长期记忆服务接入 DeepSeek Harness 的 MCP Server。服务通过 MCP stdio 暴露记忆写入、语义检索和混合检索三个工具，再把请求转换为 MemAura `/api/v2` HTTP API。

## 适用范围

本项目是一个独立的 Python MCP Server，并附带一个无需打包安装的 Harness 配置工具。MCP 工具仍由模型按需调用；安装原生 Harness 适配器后，召回和回合结束保存会自动执行。

## 工作流程

```text
DeepSeek Harness
  └─ @deepseek-ai/dsh-mcp-client
       └─ stdio → server.py
            └─ HTTPS → https://api.omnimemory.cn/api/v2
```

启动后，Harness 会发现以下模型可见工具：

| MCP 工具 | MemAura API | 作用 |
| --- | --- | --- |
| `store_memory` | `POST /memory/ingest` | 异步写入一条或多条对话消息 |
| `search_memory` | `POST /memory/retrieval` | 兼容的语义检索 |
| `search_memory_hybrid` | `POST /memory/retrieval/hybrid` | BM25 + Dense Vector 的混合检索，推荐 |

## 前置条件

- Python 3.11 或更高版本。
- 已安装并能运行 DeepSeek Harness。
- MemAura API Key。
- 本机可以访问 `https://api.omnimemory.cn`。

## 安装

```bash
git clone <your-repository-url> memaura-mcp-server
cd memaura-mcp-server
python3 -m pip install -r requirements.txt
```

安装完成后，可以自动写入 Harness profile 配置、安装记忆规则和 Skill，并执行 MCP `tools/list` 健康检查：

```bash
export MEMAURA_API_KEY='你的 API Key'
python3 memaura_cli.py setup --agent dsh --profile web
python3 memaura_cli.py doctor --agent dsh --profile web
```

卸载时运行：

```bash
python3 memaura_cli.py uninstall --agent dsh --profile web
```

`setup` 不会把 API Key 写入文件，只写入 `!!js process.env.MEMAURA_API_KEY`。安装的原生适配器会在每个直接用户回合自动召回，并在回合结束后台写入，不需要模型先决定调用 MCP 搜索工具。

API Key 建议放在启动环境中，不要写入 Git 或共享的 YAML 文件：

```bash
export MEMAURA_API_KEY="你的 MemAura API Key"
export MEMAURA_DEFAULT_DEVICE_NO="dsh-agent"
```

也可以设置以下变量：

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `MEMAURA_BASE_URL` | `https://api.omnimemory.cn/api/v2` | MemAura API 根地址 |
| `MEMAURA_API_KEY` | 空 | 必填的 API Key |
| `MEMAURA_DEFAULT_DEVICE_NO` | `dsh-agent` | 记忆隔离设备号 |
| `MEMAURA_DEFAULT_TOP_K` | `10` | 默认检索条数 |
| `MEMAURA_TIMEOUT` | `30.0` | HTTP 超时秒数 |

## 单独验证 MCP Server

MCP stdio 使用标准输入输出承载协议，日志写入 stderr：

```bash
MEMAURA_API_KEY="$MEMAURA_API_KEY" \
  python3 server.py --transport stdio
```

不要直接把 JSON 写到终端验证；建议使用支持 MCP 的客户端执行 `initialize` 和 `tools/list`。该检查不会写入或检索云端记忆。

## 接入 DeepSeek Harness

### Web Profile 配置

编辑 `~/.dsh/profiles/web/cordis.patch.yml`，将路径换成你的实际绝对路径：

```yaml
- insert:
    - id: memaura-memory
      name: "@deepseek-ai/dsh-mcp-client"
      config:
        serverName: memaura
        transport: stdio
        command: python3
        args:
          - /absolute/path/memaura-mcp-server/server.py
        env:
          MEMAURA_API_KEY: !!js process.env.MEMAURA_API_KEY
          MEMAURA_DEFAULT_DEVICE_NO: !!js process.env.MEMAURA_DEFAULT_DEVICE_NO
          MEMAURA_DEFAULT_TOP_K: "10"
```

如果使用 `!!js process.env...`，必须从同一个终端导出变量后启动 Harness：

```bash
export MEMAURA_API_KEY="你的 MemAura API Key"
export MEMAURA_DEFAULT_DEVICE_NO="dsh-agent"
pnpm dsh web
```

查看合成后的配置：

```bash
pnpm dsh --profile web --dump-config
```

启动日志应能看到 Python MCP Server 启动。MCP 工具在 Harness 中会以以下命名空间公开：

```text
mcp__memaura__store_memory
mcp__memaura__search_memory
mcp__memaura__search_memory_hybrid
```

### 命令行补丁

仓库中的 `memaura.cordis.yml` 是不含密钥的配置模板，也可以通过 Harness 的 `--patch` 加载：

```bash
pnpm dsh web --patch /absolute/path/memaura-mcp-server/memaura.cordis.yml
```

如果模板里使用了明文占位符，启动前必须替换为安全的环境变量表达式；不要把真实 API Key 提交到仓库。

## 工具参数

### `store_memory`

请求参数与官网 `/memory/ingest` 保持一致：

```json
{
  "turns": [
    {"role": "user", "content": "用户喜欢用中文回答。"},
    {"role": "assistant", "content": "我会记住这个偏好。"}
  ],
  "language": "zh",
  "commit_id": "optional-idempotency-key",
  "device_no": "dsh-agent"
}
```

服务始终把 `device_no` 放入 `X-Device-No` 请求头，并且不发送 `session_id`。设备号用于隔离记忆空间；同一设备重试同一写入请求时，应复用 `commit_id`。

写入接口返回 HTTP 202 表示任务已经入队，不表示记忆已经完成索引。响应中会返回 `job_id`、`status` 和 `status_url`。官网说明通常需要 30–60 秒后才可以检索到新记忆。

### `search_memory` 和 `search_memory_hybrid`

```json
{
  "query": "用户喜欢使用哪种语言？",
  "top_k": 5,
  "language": "zh",
  "device_no": "dsh-agent"
}
```

服务会把设备号放入 `X-Device-No`，请求体只包含官网支持的 `query`、`top_k` 和可选 `language`。新接入不使用 `session_id` 或旧版 `group_id`。

检索结果统一返回 `evidence_details`，每条结果保留 `event_id`、`source`、`role`、`sender_name`、`text`、`atomic_facts`、`timestamp` 等官网字段。

## 记忆调用策略

MCP 只提供工具，模型是否调用取决于工具描述和 Harness 系统提示。推荐在 Agent Preset 中加入类似规则：

```text
用户明确要求记住信息时调用 store_memory。
问题可能依赖历史偏好、事实或项目背景时，先调用 search_memory_hybrid。
不要保存密码、API Key、访问令牌或其他认证凭据。
只有工具返回成功后，才能告诉用户记忆已保存。
```

## 安全注意事项

- API Key 只通过环境变量或本机密钥管理器提供。
- 不要把 `.env`、真实的 `cordis.patch.yml` 或日志提交到 Git。
- 不要把 API Key、密码和令牌传给 `store_memory`。
- `X-Device-No` 是记忆隔离标识，不是认证凭据；不同用户或不同 Harness 实例应使用不同设备号。
- 当前 Python Server 只实现 stdio。它的可选 SSE 入口使用旧版 `/sse` + `/messages` Transport，不应直接配置成 Harness 的 `streamable-http`，除非另行实现 MCP Streamable HTTP。

## 故障排查

| 现象 | 检查 |
| --- | --- |
| `MEMAURA_API_KEY 未设置` | 确认启动 Harness 的同一个终端已导出变量 |
| 工具没有出现在模型工具列表 | 运行 `pnpm dsh --profile web --dump-config`，检查插件行和绝对路径 |
| HTTP 401 | API Key 是否有效、是否过期 |
| HTTP 400 | 检查 `turns` 非空、`query` 非空、设备号是否存在 |
| 写入后立即检索为空 | 写入是异步任务，等待约 30–60 秒再检索 |
| 检索到其他设备的记忆 | 检查写入和检索是否使用相同的 `X-Device-No` |
| MCP 反复重启 | 检查 Python 解释器、依赖安装和 stderr 日志 |

## 目录结构

```text
memaura-mcp-server/
├── server.py              # MCP Server 和 MemAura API 适配器
├── memaura_cli.py         # setup / doctor / uninstall 命令
├── requirements.txt       # Python 依赖
├── .env.example           # 环境变量模板
├── memaura.cordis.yml     # 不含密钥的 Harness 配置模板
└── README.md              # 本说明
```