内容
# qmd-gateway
一个**共享、常驻、预热**的 qmd 内存服务，供整个 mairp 代理舰队使用，以及一个**可写**的跨代理知识集合。取代了旧模型，其中每个 `claude`/`bebop` 会话都会启动自己的 `qmd mcp` stdio 子进程（冷模型，无共享），而 OpenClaw 则会为每个代理维护一个单独的索引。
```
┌───────────────────────────────────────────────┐
Claude / bebop ─┐ │ qmd-gateway.service │
pi (via skill) ─┤ MCP │ uvx mcp-proxy --host 0.0.0.0 --port 8190 │
OpenClaw agents ─┤ SSE │ └─ 一个预热的 `qmd mcp` (stdio 子进程) │
3rd-party CLIs ─┘ 8190 │ XDG -> /root/qmd-shared │
└───────────────────────────────────────────────┘
recall.sh / qmd-remember.sh （bash 路径，无 MCP 客户端需要）
│ read │ write
▼ ▼
qmd-shared 索引（sqlite） /root/fleet-memory/** ── reindex.sh （定时器 + 写入时）
集合: fleet-ops （读写）+ claude-memory （只读）+ openclaw-memory （只读）
模型: Qwen3-Embedding-0.6B · qmd-query-expansion-1.7B · Qwen3-Reranker-0.6B （本地 GGUF）
```
## 端点和绑定
| | |
|---|---|
| SSE MCP | `http://127.0.0.1:8190/sse` （也可在 WireGuard 上通过 `10.8.0.1:8190` 访问） |
| 存活状态 | `http://127.0.0.1:8190/status` → 200 |
| 绑定 | `0.0.0.0:8190`，但主机防火墙（`setup-firewall.sh`，INPUT 策略 DROP）仅允许 `lo` + `10.8.0.0/24` 访问。无公网暴露，无密钥材料在单元中。 |
## 文件
| 路径 | 描述 |
|---|---|
| `run.sh` | 服务：`mcp-proxy` 面向一个预热的 `qmd mcp`。环境变量固定共享 XDG + Intel-iGPU Vulkan（RTX 3090 保留给 llama-swap）。 |
| `recall.sh` | 失败-开放召回针对共享索引（`fast` BM25 / `deep` vec-only / `query` 混合）。对于没有 MCP 客户端的代理（pi，CLI）- 从 bash 工具调用。 |
| `qmd-remember.sh` | **写入路径。** `qmd-remember.sh "<title>" "<body>" [--type project\|infra\|feedback\|reference]` → `/root/fleet-memory/` 下的叶子节点，`MEMORY.md` 中的指针，然后重新索引。 |
| `reindex.sh` | flock-guarded `qmd update && qmd embed` 在共享索引上。由定时器和每次写入后运行。 |
| `qmd-attach.sh` | 附加代理（参见下面的矩阵）。 |
## 附加矩阵
| 代理 | 命令 | 路径 |
|---|---|---|
| Claude / bebop | `qmd-attach.sh claude-http` | MCP/SSE → 共享预热索引（恢复: `claude-stdio`） |
| pi | `qmd-attach.sh pi` | 注册 `~/.claude/skills` （包括 `qmd-recall`）到 `~/.pi/agent/settings.json`；通过 bash 回忆。**可选 MCP:** `pi install npm:<mcp-client-ext>` → `:8190/sse` |
| OpenClaw 代理 | `qmd-attach.sh openclaw <agent>` | 将共享 fleet-ops 读取添加到代理的 `index.yml`。**可选 MCP:** 启用 `mcporter` → `:8190/sse` |
| 3rd-party CLI | `qmd-attach.sh cli` | 打印环境变量 + `.mcp.json` （MCP CLI）或 `recall.sh` bash 模式 |
| — | `qmd-attach.sh status` | 显示已附加的内容 |
## Systemd
- `qmd-gateway.service` — SSE 服务（`Restart=always`）。
- `qmd-gateway-reindex.timer` / `.service` — 每 10 分钟增量重新索引。
- 由 `/root/fleet.sh` （步骤 5）启动/停止/报告。
## 集合
在 `/root/qmd-shared/xdg-config/qmd/index.yml` 中定义:
- **`fleet-ops` / `fleet-ops-root`** （可写）→ `/root/fleet-memory/**` — 跨代理大脑。
- **`claude-memory-*`** （只读）→ `/root/.claude/projects/-root/memory`。
- **`openclaw-memory-*`** （只读）→ `/root/.openclaw/workspace{,/memory}`。
只有 `fleet-ops` 被写入（通过 `qmd-remember.sh`）；其他是单向只读共享。
