MemAura MCP Server for DeepSeek Harness

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

适用范围

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

工作流程

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。

安装

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 健康检查：

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

卸载时运行：

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

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

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

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：

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，将路径换成你的实际绝对路径：

- 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：

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

查看合成后的配置：

pnpm dsh --profile web --dump-config

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

mcp__memaura__store_memory
mcp__memaura__search_memory
mcp__memaura__search_memory_hybrid

命令行补丁

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

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

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

工具参数

store_memory

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

{
  "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

{
  "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 中加入类似规则：

用户明确要求记住信息时调用 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 日志

目录结构

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              # 本说明