349 lines
9.0 KiB
Markdown
349 lines
9.0 KiB
Markdown
# Git 一致性优先的共享记忆检索系统
|
||
|
||
本项目在现有 QMD 基础上增加 `memory-gateway`，目标是让多 Agent 查询具备“查询前强制同步”的一致性，而不是只依赖后台轮询同步。
|
||
|
||
## 1. 项目背景
|
||
|
||
在多 Agent 协作里，若“同步”和“查询”解耦为两个松散后台动作，会出现：
|
||
|
||
- Agent A 读到旧记忆
|
||
- Agent B 读到新记忆
|
||
- 对任务目标、恢复点、执行上下文理解分叉
|
||
|
||
本项目的核心设计：
|
||
|
||
- Git 是 source of truth
|
||
- QMD 只做索引和检索
|
||
- memory-gateway 负责查询前同步与一致性协调
|
||
|
||
## 2. 架构与一致性事务
|
||
|
||
```mermaid
|
||
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` 的主链路：
|
||
|
||
1. 解析 `branch / memory_profile / query_type / query`
|
||
2. 获取 workspace 锁（同 workspace 串行，不同 workspace 并行）
|
||
3. `git fetch` + workspace 对齐到目标 branch 最新 commit
|
||
4. `qmd update`（需要时 `embed`）
|
||
5. 执行检索
|
||
6. 返回结果 + `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）
|
||
|
||
```text
|
||
.
|
||
├─ 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）
|
||
|
||
### 查询返回路径映射（项目相对路径）
|
||
|
||
为方便你直接在项目目录定位，`/query` 与 `/sync` 返回的 `resolved_workspace` 使用项目相对路径，而不是容器绝对路径。
|
||
|
||
- `main` -> `data/workspaces/main`
|
||
- `memory/2026-03` -> `data/workspaces/memory-2026-03`
|
||
- `task/TASK-001` -> `data/workspaces/task-TASK-001`
|
||
|
||
内部容器路径仍是 `/data/workspaces/...`，网关会在响应时转换为相对路径表示。
|
||
|
||
## 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 与目录
|
||
|
||
```bash
|
||
cd /home/lingyuzeng/project/qmd-local/qmd-docker-http-mcp
|
||
./scripts/bootstrap.sh
|
||
```
|
||
|
||
### 7.2 启动
|
||
|
||
```bash
|
||
docker compose build
|
||
docker compose up -d
|
||
```
|
||
|
||
### 7.3 健康检查
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8181/health
|
||
curl http://127.0.0.1:8787/health
|
||
```
|
||
|
||
## 8. API 使用
|
||
|
||
### GET /health
|
||
|
||
```bash
|
||
curl -fsS http://127.0.0.1:8787/health
|
||
```
|
||
|
||
### POST /sync
|
||
|
||
```bash
|
||
curl -fsS -X POST http://127.0.0.1:8787/sync \
|
||
-H 'content-type: application/json' \
|
||
-d '{"branch":"main","require_latest":true}'
|
||
```
|
||
|
||
### POST /query（主入口）
|
||
|
||
```bash
|
||
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`（项目相对路径，例如 `data/workspaces/main`）
|
||
- `commit_hash`
|
||
- `synced_at`
|
||
- `query_type`
|
||
- `results`
|
||
- `qmd_collection`
|
||
- `debug`（可选）
|
||
|
||
### GET /status
|
||
|
||
```bash
|
||
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. 测试与验收
|
||
|
||
### 自动化测试
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
. .venv/bin/activate
|
||
pip install -r gateway/requirements.txt pytest httpx
|
||
PYTHONPATH=./gateway pytest -q gateway/tests
|
||
```
|
||
|
||
### 手工验收（建议）
|
||
|
||
1. 构建与启动
|
||
2. 服务健康
|
||
3. 基础查询
|
||
4. 修改远端后立即查询（验证查询前同步）
|
||
5. 分支隔离
|
||
6. 默认分支
|
||
7. 并发查询
|
||
8. 重启恢复
|
||
|
||
## 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](/home/lingyuzeng/project/qmd-local/qmd-docker-http-mcp/gateway/app/main.py)
|
||
- 同步事务：[gateway/app/sync_service.py](/home/lingyuzeng/project/qmd-local/qmd-docker-http-mcp/gateway/app/sync_service.py)
|
||
- Git 管理：[gateway/app/git_manager.py](/home/lingyuzeng/project/qmd-local/qmd-docker-http-mcp/gateway/app/git_manager.py)
|
||
- QMD 调用：[gateway/app/qmd_client.py](/home/lingyuzeng/project/qmd-local/qmd-docker-http-mcp/gateway/app/qmd_client.py)
|
||
- Compose 编排：[docker-compose.yml](/home/lingyuzeng/project/qmd-local/qmd-docker-http-mcp/docker-compose.yml)
|
||
|
||
## 14. 多 Agent 记忆仓库最佳实践
|
||
|
||
### 14.1 子记忆仓库怎么放
|
||
|
||
建议把“记忆系统仓库”单独管理，并在本项目中通过 `.gitignore` 忽略运行态 clone/mirror/workspace。
|
||
|
||
- 推荐：独立 memory repo（独立 push/pull 生命周期）
|
||
- 不推荐主方案：submodule（多 agent 高频写入时维护成本高、冲突处理复杂）
|
||
|
||
### 14.2 推荐目录结构（memory repo 内）
|
||
|
||
```text
|
||
memory-repo/
|
||
├─ shared/
|
||
│ ├─ announcements/
|
||
│ └─ sop/
|
||
├─ agents/
|
||
│ ├─ agent-a/
|
||
│ │ ├─ AGENT-CARD.md
|
||
│ │ ├─ MEMORY-LOG.md
|
||
│ │ ├─ PROMPT-RULES.md
|
||
│ │ ├─ inbox/
|
||
│ │ ├─ working/
|
||
│ │ ├─ handoff/
|
||
│ │ └─ checkpoints/
|
||
├─ tasks/
|
||
│ └─ TASK-001/
|
||
└─ policies/
|
||
└─ WRITE-PERMISSIONS.yaml
|
||
```
|
||
|
||
### 14.3 每个子 Agent 的脚手架
|
||
|
||
本仓库提供脚手架脚本：`scripts/scaffold-agent-memory.sh`
|
||
|
||
示例：
|
||
|
||
```bash
|
||
./scripts/scaffold-agent-memory.sh \
|
||
--repo /path/to/memory-repo \
|
||
--agent agent-a \
|
||
--default-branch main
|
||
```
|
||
|
||
作用：
|
||
|
||
- 生成 `agents/<agent-id>/` 标准目录
|
||
- 生成 `AGENT-CARD.md`（身份与可写路径声明）
|
||
- 生成 `PROMPT-RULES.md`（写前 pull、冲突处理规则）
|
||
- 生成 `policies/WRITE-PERMISSIONS.yaml`
|
||
|
||
### 14.4 多 Agent 同步与冲突最小化策略
|
||
|
||
1. 写入前固定执行：`git pull --rebase origin <branch>`
|
||
2. 尽量 append-only，减少多人改同一行
|
||
3. 原子小提交（按一次记忆动作提交）
|
||
4. 推送失败先 rebase，再自动合并一次；仍冲突则人工解决
|
||
5. 共享目录写权限建议通过 gateway 或服务端 hook 校验，避免越权路径写入
|
||
|
||
### 14.5 与 QMD/gateway 的关系
|
||
|
||
- Git 仓库负责“真相源”和版本历史
|
||
- gateway 负责查询前同步和分支/工作区隔离
|
||
- qmd 负责本地索引与检索
|
||
|
||
这样可以同时满足：
|
||
|
||
- 多 agent 共享记忆
|
||
- 查询一致性
|
||
- 冲突可控
|
||
- 结果可追溯（branch + commit）
|