flowchart LR
    C[Remote Client\nCodex/Claude/OpenClaw] --> G[memory-gateway\nHTTP :8787]
    G --> S[Sync Transaction\nfetch -> workspace sync -> qmd update/embed]
    S --> Q[qmd search/query\nper-workspace index]
    Q --> G
    G --> C

    G --> M[/data/git-mirror/repo.git]
    G --> W1[/data/workspaces/main]
    G --> W2[/data/workspaces/memory-2026-03]
    G --> W3[/data/workspaces/task-TASK-001]

/query 的主链路：

解析 branch / memory_profile / query_type / query
获取 workspace 锁（同 workspace 串行，不同 workspace 并行）
git fetch + workspace 对齐到目标 branch 最新 commit
qmd update（需要时 embed）
执行检索
返回结果 + branch/commit_hash/synced_at/workspace

3. 服务职责

qmd

提供 MCP/HTTP 能力（8181）
持久化 cache/config
作为底层检索引擎，不作为远程客户端唯一入口

memory-gateway

远程唯一入口（8787）
提供 GET /health、POST /query、POST /sync、GET /status
强制执行查询前同步

warmup（可选）

定时轻量请求，降低冷启动抖动
仅优化项，不提供一致性保证

4. 目录与关键路径

仓库目录（Host）

.
├─ docker-compose.yml
├─ .env.example
├─ AGENTS.md
├─ README.md
├─ gateway/
│  ├─ app/
│  ├─ tests/
│  ├─ requirements.txt
│  └─ Dockerfile
├─ scripts/
│  ├─ qmd-entrypoint.sh
│  ├─ bootstrap.sh
│  ├─ warmup.sh
│  └─ smoke-test.sh
└─ data/
   ├─ git-mirror/
   ├─ workspaces/
   ├─ qmd-cache/
   ├─ qmd-config/
   └─ remote-memory.git/   # bootstrap 生成的本地 demo remote

容器内路径

Git mirror: /data/git-mirror/repo.git
Workspace 根目录: /data/workspaces
QMD cache: /var/lib/qmd/cache（qmd 容器）/ /data/qmd-cache（gateway 调 CLI）
QMD config: /var/lib/qmd/config（qmd 容器）/ /data/qmd-config（gateway 调 CLI）

5. 分支与 profile 规则

优先级：branch > memory_profile > main

stable -> main
monthly-YYYY-MM -> memory/YYYY-MM
task-<task-id> -> task/<task-id>

建议分层：

长期稳定：main
月度滚动：memory/YYYY-MM
任务临时：task/<task-id>

6. 环境变量（关键配置）

必填

GIT_REMOTE_URL：Git 真相源地址（ssh/https/file/path）

常用

DEFAULT_BRANCH：默认分支（默认 main）
QMD_TIMEOUT_SECONDS：gateway 调 qmd CLI 超时秒数（默认 300）
QMD_INDEX_PREFIX：per-workspace 索引名前缀（默认 ws）
QMD_UPDATE_ON_LATEST_QUERY：require_latest=true 时是否强制 qmd update（默认 true）
QMD_EMBED_ON_CHANGE：HEAD 变化时是否尝试 embed（默认 true，可按性能改 false）

GPU（qmd 容器）

CUDA_DEVICE
CUDA_VISIBLE_DEVICES
NVIDIA_VISIBLE_DEVICES

模型覆盖（可选）

QMD_EMBED_MODEL_URI
QMD_RERANK_MODEL_URI
QMD_GENERATE_MODEL_URI

示例：见 [.env.example](/home/lingyuzeng/project/qmd-local/qmd-docker-http-mcp/.env.example)。

7. 快速开始

7.1 初始化 demo remote 与目录

cd /home/lingyuzeng/project/qmd-local/qmd-docker-http-mcp
./scripts/bootstrap.sh

7.2 启动

docker compose build
docker compose up -d

7.3 健康检查

curl http://127.0.0.1:8181/health
curl http://127.0.0.1:8787/health

8. API 使用

GET /health

curl -fsS http://127.0.0.1:8787/health

POST /sync

curl -fsS -X POST http://127.0.0.1:8787/sync \
  -H 'content-type: application/json' \
  -d '{"branch":"main","require_latest":true}'

POST /query（主入口）

curl -fsS -X POST http://127.0.0.1:8787/query \
  -H 'content-type: application/json' \
  -d '{
    "branch":"main",
    "query_type":"search",
    "query":"recovery strategy",
    "require_latest":true,
    "debug":true
  }'

返回字段核心：

ok
branch
resolved_workspace
commit_hash
synced_at
query_type
results
qmd_collection
debug（可选）

GET /status

curl -fsS http://127.0.0.1:8787/status

9. 查询策略说明

当前最小兼容实现中：

query_type=search -> qmd search
query_type=vsearch -> qmd vsearch
query_type=query/deep_search -> 为保证稳定与时延上界，默认走 qmd search（响应 debug.qmd_command 可追踪）

10. 测试与验收

自动化测试

python3 -m venv .venv
. .venv/bin/activate
pip install -r gateway/requirements.txt pytest httpx
PYTHONPATH=./gateway pytest -q gateway/tests

手工验收（建议）

构建与启动
服务健康
基础查询
修改远端后立即查询（验证查询前同步）
分支隔离
默认分支
并发查询
重启恢复

11. 常见问题

首次请求慢

首次模型/索引准备、或首次分支激活会慢。可用：

QMD_EMBED_ON_CHANGE=false（降低请求阻塞）
warmup profile 预热

本地路径 remote 被 git safe.directory 拦截

gateway 已对本地 GIT_REMOTE_URL 自动添加 safe.directory。

12. 客户端接入建议

远程客户端只访问 memory-gateway，不要直连 qmd
每次请求尽量显式传 branch 或 memory_profile
记录响应中的 branch + commit_hash 用于审计与回放

13. 关键文件

网关入口：gateway/app/main.py
同步事务：gateway/app/sync_service.py
Git 管理：gateway/app/git_manager.py
QMD 调用：gateway/app/qmd_client.py
Compose 编排：docker-compose.yml

README.md Unescape Escape

Git 一致性优先的共享记忆检索系统

1. 项目背景

2. 架构与一致性事务