# MemAura Qoder MCP

把 MemAura/OmniMemory 接入 Qoder CN 的独立适配器。它不会修改或依赖原来的 DeepSeek Harness 项目 `/Users/azhai/memaura-mcp-server`。

## 功能

- MCP：`store_memory`、`search_memory`、`search_memory_hybrid`
- Hook：每次提交问题前自动混合召回；回答结束后自动保存本轮问答
- 记忆设备号可配置：默认 `qoder-agent`，也可改成与其他客户端共享的设备号

## 1. 安装依赖

```bash
git clone https://github.com/Omnimemory/omnin-Qoder-mcp.git
cd omnin-Qoder-mcp
./install.sh
```

`install.sh` 会创建本项目的 `.venv`，不会修改系统 Python。

## 2. 配置本地环境

```bash
cp .env.example .env
```

编辑 `.env`，至少填写：

```dotenv
MEMAURA_API_KEY=你的真实APIKey
MEMAURA_DEFAULT_DEVICE_NO=qoder-agent
```

`.env` 已被 `.gitignore` 忽略。不要把 API Key 提交到 GitHub。

如果要和 DeepSeek Harness 共用记忆，把设备号改为它使用的值，例如 `dsh-agent`；使用 `qoder-agent` 则记忆隔离。

## 3. 配置 Qoder MCP

在 Qoder 的“设置 → MCP 服务”中打开 `mcp.json`，使用绝对路径配置：

```json
{
  "mcpServers": {
    "memaura": {
      "type": "stdio",
      "command": "/绝对路径/omnin-Qoder-mcp/.venv/bin/python",
      "args": ["/绝对路径/omnin-Qoder-mcp/mcp_server.py"],
      "env": {
        "MEMAURA_API_KEY": "你的真实APIKey",
        "MEMAURA_DEFAULT_DEVICE_NO": "qoder-agent",
        "MEMAURA_DEFAULT_TOP_K": "10",
        "MEMAURA_TIMEOUT": "30"
      }
    }
  }
}
```

把两个“绝对路径”替换为本机实际路径。保存并完全重启 Qoder。MCP 页面应显示三个工具。

## 4. 启用自动召回和保存

Qoder 的 MCP 配置不会自动触发工具。Hook 配置位于 `hooks/hooks.json`。将下面的 `hooks` 配置合并到 `~/.lingma/settings.json`（不要覆盖你已有的其他设置）：

```json
{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "/绝对路径/omnin-Qoder-mcp/hooks/run-memory-hook.sh",
        "timeout": 25
      }]
    }],
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "/绝对路径/omnin-Qoder-mcp/hooks/run-memory-hook.sh",
        "timeout": 25,
        "async": true
      }]
    }]
  }
}
```

本项目的 Hook 会自动读取同目录 `.env`，因此不需要依赖 `launchctl`。修改后完全退出并重新打开 Qoder。

## 5. 验证

先验证 Hook 能读取配置：

```bash
printf '%s' '{"hook_event_name":"UserPromptSubmit","session_id":"test-001","prompt":"测试记忆 QODER-HOOK-918273"}' | hooks/run-memory-hook.sh
```

再在 Qoder 新建对话：

```text
我刚刚购买了一台测试设备，序列号是 DEVICE-XK-591。
```

等待 30–60 秒，新建另一个对话并问：

```text
我刚刚购买的测试设备序列号是什么？
```

如果能回答 `DEVICE-XK-591`，说明跨对话保存和召回均生效。

## 发布插件包

插件包必须是 ZIP，且 ZIP 根目录直接包含 `.qoder-plugin/plugin.json`。不要把 `.venv`、`.env` 或 API Key 放进压缩包：

```bash
zip -qr memaura-qoder.zip . \
  -x './.venv/*' './.env' './**/__pycache__/*' './*.pyc'
```

在 Qoder“插件 → 导入”中选择生成的 ZIP，而不是选择源码文件夹。安装后仍需按上面的步骤配置本机 Python 环境和 API Key。

## 故障排查

- MCP 能看到工具但不自动保存：Hook 没加载，检查 `~/.lingma/settings.json` 并重启 Qoder。
- Hook 输出 `MEMAURA_API_KEY 未设置`：确认项目根目录有 `.env`，并且变量名拼写正确。
- 手动 `store_memory` 成功、自动测试失败：MCP 正常，问题只在 Hook 配置或 Hook 环境。
- 保存成功后不能立即检索：MemAura 入队后通常需要 30–60 秒建立索引。