MemClawz 三层记忆架构集成指南：为 OpenClaw 注入持久记忆

存储内容：

• 活跃任务（进度、决策、阻碍）
• 实体追踪（提到的人、URL、凭证）
• 决策日志（'为什么选择 X 而非 Y'）

示例结构：

{
  "session_id": "main-2026-03-07",
  "started_at": "2026-03-07T08:30:00Z",
  "tasks": [
    {
      "id": "hotel-search",
      "status": "active",
      "title": "查找利马索尔月租房",
      "context": "2 成人 +3 儿童，3 月 5 日–4 月 5 日",
      "progress": ["发送 20 份 RFP", "四季酒店回复：€1,360/晚"],
      "entities": ["四季酒店", "Amara 酒店"],
      "decisions": ["使用 AgentMail 而非个人邮箱"],
      "blockers": ["Royal Apollonia 邮件被退回"],
      "next": "等待回复，每 6 小时检查",
      "caused_by": ["research-ama-bench"],
      "confidence": 0.85
    }
  ],
  "entities_seen": {"people": ["Omer Levi"], "urls": ["clawz.org"]},
  "updated_at": "2026-03-07T20:00:00Z"
}

生命周期管理：

• 会话开始： 读取 current.json 恢复感知
• 工作中： 每次重要操作后更新 QMD（新任务、决策、完成）
• 会话结束： 完成任务压缩到日志，活跃任务保留
• 每周： 重要决策提升到 MEMORY.md

2. Zvec 服务器 — 混合向量 + 关键词搜索

位置： memclawz_server/server.py 端口： localhost:4010

技术栈基于 FastAPI + Uvicorn，底层使用阿里巴巴的 Zvec (HNSW 向量数据库)，支持 768 维嵌入（兼容 OpenClaw 的 embeddinggemma-300m）。

搜索策略：

• HNSW 向量搜索： 适用于语义相似性场景，如'查找酒店定价相关上下文'。
• BM25 关键词搜索： 适用于精确匹配，如'查找 Four Seasons 提及'。
• 混合评分： 默认采用 70% 向量 + 30% 关键词融合排序。

3. 自动索引 Watcher

位置： memclawz_server/watcher.py

Watcher 监控 OpenClaw 的 SQLite 记忆数据库，每 60 秒自动同步新块到 Zvec。关键特性包括无需手动重新索引、新记忆 60 秒内可搜索、批量处理（每次 50 块）以及错误重试机制。

4. 因果图 (Causality Graph) — v3.0 新增

位置： memclawz_server/causality_graph.py 存储： SQLite (~/.openclaw/zvec-memory/causality.db)

基于 AMA-Bench 研究发现，因果图结合工具增强检索能显著提升得分。边类型包括 Causality（有向）、Association（无向关联）和 Similarity（无向相似度）。

QMD 因果字段（v3.0）：

{"id":"deploy-v3","status":"active","title":"部署 v3","caused_by":["research-ama-bench"],"causes":["testing-v3"],"confidence":0.85}

5. 压缩脚本

位置： scripts/qmd-compact.py

用于将已完成的 QMD 任务移动到日志文件，修剪工作记忆。支持手动运行、cron 定时或通过心跳检查钩子触发。

python3 scripts/qmd-compact.py
# 输出：Compacted 3 completed tasks to memory/2026-03-07.md
# 2 active tasks remain in QMD

安装与配置

前置条件

• OpenClaw：已安装并运行
• Python：3.10–3.13 (x86_64 Linux)
• pip 包：zvec, numpy

注意： zvec 仅提供 x86_64 Linux wheels，暂不支持 macOS/ARM64/Windows。

一键安装

cd ~/.openclaw/workspace
git clone https://github.com/yoniassia/memclawz.git
cd memclawz && bash scripts/first-run.sh

首跑脚本会自动完成依赖安装、目录创建、服务启动、历史导入及验证注册。

后续命令：

# 重新同步历史
bash scripts/bootstrap-history.sh
# 验证安装
python3 scripts/verify.py
# 手动搜索
bash scripts/search.sh "查询内容"

环境变量

systemd 服务（生产环境）

# 安装服务
sudo cp systemd/zvec-server.service /etc/systemd/system/
sudo cp systemd/zvec-watcher.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now zvec-server zvec-watcher

# 查看状态
systemctl status zvec-server zvec-watcher

# 查看日志
journalctl -u zvec-server -f

API 参考

基础端点

搜索端点

POST /search

请求体包含 embedding 或 text（自动嵌入）：

{"embedding":[0.1,0.2,...], "text":"可选，自动嵌入", "topk":5, "filter":"可选过滤表达式"}

响应返回匹配结果及分数：

{"results":[{"id":"chunk_123","score":0.95,"text":"匹配内容...","path":"memory/2026-03-07.md","source":"sqlite","start_line":10,"end_line":25}],"count":5}

索引端点

POST /index

支持简写模式，自动嵌入文本：

{"text":"内容", "meta":{"path":"source.md","source":"manual"}}

因果图端点（v3.0）

POST /graph/add

允许定义节点间的因果关系：

{"text":"事件描述", "node_id":"custom-id", "caused_by":["node_id_1"], "causes":["node_id_2"]}

POST /graph/search

支持多跳检索，可设置置信度阈值和遍历深度：

{"embedding":[0.1,0.2,...], "topk":5, "similarity_threshold":0.5, "max_depth":2}

OpenClaw 集成

AGENTS.md 配置

在智能体的 AGENTS.md 中添加以下记忆协议，指导智能体如何读写记忆：

## Memory Protocol
1. **On session start:** Read `memory/qmd/current.json` — your working memory
2. **During work:** Update QMD after significant actions (new task, decision, completion)
3. **For search:** Check QMD first → then curl Zvec (port 4010) → then memory_search
4. **On session end:** Run `python3 scripts/qmd-compact.py` to archive completed tasks

搜索脚本封装

创建便捷的搜索脚本 scripts/search.sh，封装了调用嵌入器与搜索的逻辑：

#!/bin/bash
# MemClawz Search Wrapper
# Usage: ./scripts/search.sh "query text"
QUERY="$1"
TOPK="${2:-5}"
ZVEC_URL="${ZVEC_URL:-http://localhost:4010}"

if [ -z "$QUERY" ]; then
  echo "Usage: $0 \"query text\" [topk]"
  exit 1
fi

# Call embedder + search in one step
curl -s -X POST "$ZVEC_URL/search" \
  -H 'Content-Type: application/json' \
  -d "{\"text\": \"$QUERY\", \"topk\": $TOPK}" | \
  python3 -c "import sys, json; data = json.load(sys.stdin); 
  for r in data.get('results', []): print(f\"\\n[Score: {r['score']:.3f}] {r.get('path', 'unknown')}:{r.get('start_line', 0)}\"); 
  print(r['text'][:200] + '...' if len(r['text']) > 200 else r['text'])"

子智能体调度模式（Dispatch Pattern）

最佳实践是生成领域专家子智能体，并在预加载阶段从 MemClawz 获取相关记忆。

规则： 每个需要工作的请求都生成一个子智能体，主智能体保持轻量。

预加载上下文：

1. 提取请求中的关键术语
2. 查询 POST http://127.0.0.1:4010/search_text
3. 将结果作为'过往上下文'包含在 spawn 任务中

Spawn 模板：

# Step 1: Search memclawz for context
curl -s -X POST http://127.0.0.1:4010/search \
  -H 'Content-Type: application/json' \
  -d '{"text":"[request keywords]","topk":5}'

# Step 2: Spawn with context + live memory access
sessions_spawn(
  task="[Task]\n\n## Past Context (from memclawz):\n[results]\n\n ## Memory Access:\nSearch memclawz during work:\n curl -s -X POST http://127.0.0.1:4010/search \
   -H 'Content-Type: application/json' \
   -d '{\"text\":\"query\",\"topk\":5}'\n ALWAYS search before starting to find relevant history.",
  label="[domain]-[short-desc]"
)

性能基准

测试环境： AMD EPYC 9354P, 32GB RAM, 1,166 索引块

最佳实践

1. QMD 更新时机

应该更新：

• 开始新任务
• 做出重要决策
• 完成任务
• 遇到阻碍
• 发现关键实体（人、URL、凭证）

不应该更新：

• 每次工具调用（过于频繁）
• 琐碎的中间步骤
• 临时想法（除非重要）

2. 搜索策略选择

3. 压缩策略

自动压缩（推荐）： 添加到 crontab，每小时运行：

0 * * * * cd ~/.openclaw/workspace/memclawz && python3 scripts/qmd-compact.py --auto

会话结束压缩： 在智能体会话结束时自动运行：

import subprocess
subprocess.run(["python3", "scripts/qmd-compact.py", "--auto"])

4. 监控与告警

健康检查脚本示例：

#!/bin/bash
# check_memclawz_health.sh
ZVEC_URL="http://localhost:4010"

# Check Zvec server
if ! curl -sf "$ZVEC_URL/health" > /dev/null; then
  echo "❌ Zvec server not responding"
  exit 1
fi

# Check indexed docs
STATS=$(curl -sf "$ZVEC_URL/stats")
DOCS=$(echo "$STATS" | python3 -c "import sys,json; print(json.load(sys.stdin).get('total_docs',0))")

if [ "$DOCS" -lt 100 ]; then
  echo "⚠️ Low doc count: $DOCS"
fi

# Check QMD file
if [ ! -f "memory/qmd/current.json" ]; then
  echo "❌ QMD file missing"
  exit 1
fi

echo "✅ All systems operational ($DOCS docs indexed)"

5. 备份策略

定期备份：

tar -czf memclawz-backup-$(date +%Y%m%d).tar.gz \
  ~/.openclaw/zvec-memory/ \
  memory/qmd/current.json

恢复流程：

# 停止服务
systemctl stop zvec-server zvec-watcher
# 恢复备份
tar -xzf memclawz-backup-20260307.tar.gz -C ~/ 
# 重启服务
systemctl start zvec-server zvec-watcher

故障排查

常见问题

1. Zvec 服务器无法启动

症状： curl localhost:4010/health 无响应

排查步骤：

# 检查日志
cat /tmp/zvec-server.log
# 检查端口占用
lsof -i :4010
# 检查 Python 版本
python3 --version # 需要 3.10+
# 检查依赖
python3 -c "import zvec; print(zvec.__version__)"

解决方案：

# 重新安装依赖
pip3 install --upgrade zvec numpy
# 清理锁文件
rm -rf ~/.openclaw/zvec-memory/memory/.lock
# 重启服务器
cd memclawz && python3 memclawz_server/server.py

2. 搜索结果为空

可能原因： 索引为空、嵌入维度不匹配、查询向量维度错误。

排查：

# 检查索引统计
curl localhost:4010/stats
# 检查集合信息
curl localhost:4010/info
# 测试搜索
curl -X POST localhost:4010/search \
  -H 'Content-Type: application/json' \
  -d '{"text": "test", "topk": 5}'

3. Watcher 未同步新文件

排查：

# 检查 Watcher 进程
ps aux | grep watcher.py
# 检查 Watcher 日志
cat /tmp/zvec-watcher.log
# 手动触发索引
curl -X POST localhost:4010/index \
  -H 'Content-Type: application/json' \
  -d '{"text": "test content", "meta": {"path": "test.md"}}'

项目结构

memclawz/
├── README.md
├── LICENSE
├── CONTRIBUTING.md
├── clawhub.json # ClawHub 包清单
├── requirements.txt
├── qmd/
│   ├── schema.json # QMD JSON 模式
│   └── current.json.example # QMD 示例
├── memclawz_server/
│   ├── server.py # Zvec HTTP 搜索服务器
│   ├── embed_server.py # 独立嵌入服务器 (端口 4020)
│   ├── fleet_server.py # 多租户舰队记忆服务器
│   ├── file_watcher.py # 直接 .md 文件监视器
│   ├── chunker.py # Markdown 分块引擎
│   ├── watcher.py # SQLite 自动索引监视器
│   ├── embedder.py # 嵌入工具
│   ├── embed_bridge.py # 本地 GGUF 嵌入桥接
│   └── causality_graph.py # 因果图 (v3.0)
├── skill/
│   ├── SKILL.md # OpenClaw 技能说明
│   ├── install.sh # 一键安装
│   └── config.example # 环境配置示例
├── scripts/
│   ├── first-run.sh # 首跑脚本
│   ├── bootstrap-history.sh # 历史导入
│   ├── search.sh # 搜索封装
│   ├── qmd-compact.py # 压缩脚本
│   ├── verify.py # 验证脚本
│   └── optimize-context.py # 上下文优化
├── systemd/
│   ├── zvec-server.service
│   └── zvec-watcher.service
├── tests/ # 45 个测试（全部通过）
└── docs/
    ├── architecture.md
    ├── fleet-memory.md
    └── explainer.html

参考资料

研究论文

'AMA-Bench: Evaluating Long-Horizon Memory for Agentic Applications' (Zhao et al., 2026)
https://arxiv.org/abs/2602.22769
关键发现： Mem0 得分 0.2104，因果图 + 工具增强检索得分 0.5722（2.7× 提升）

相关项目

ClawHub 安装

clawhub install yoniassia/memclawz