使用 memory-lancedb-pro 构建开源 AI Agent 记忆系统
基于 LanceDB 的语义记忆实战指南
一、为什么需要记忆系统？
一个没有记忆的 AI Agent，每次对话都是从零开始——它不认识你，不知道你关心什么，不记得你们之前讨论过什么。
记忆系统让 AI Agent 能够：
- 积累知识：记住学到的概念、技术方案、经验教训
- 理解偏好：记住你喜欢什么、不喜欢什么
- 保持上下文：跨会话连贯处理复杂任务
OpenClaw 提供了开放的记忆插件生态，其中 memory-lancedb-pro 是一个基于 LanceDB 的语义记忆系统，支持向量检索、分层摘要和灵活导入导出。
二、memory-lancedb-pro 核心机制
2.1 存储结构
LanceDB 以表格形式存储记忆，每条记录包含以下字段：
id - 唯一标识符 text - 记忆原文（通常是摘要级别的文本） vector - text 对应的向量嵌入（用于语义检索） category - 分类：fact / decision / preference / entity / other scope - 作用域：global / agent:main / agent:xxx importance - 重要程度：0.0 ~ 1.0 timestamp - 创建时间戳 metadata - 扩展信息（JSON）
metadata 里最核心的是三层摘要结构：
| 字段 | 含义 | 示例 |
|---|---|---|
l0_abstract | 一句话概括 | "MiniMax M2.7 是 2026 年发布的 AI Agent 系统" |
l1_overview | 要点列表 | "- 2026年发布\n- 自进化循环机制\n- 20万 token 上下文" |
l2_content | 完整内容 | 扩充后的自然段落，中英文均可能 |
text 和 l0/l1/l2 的关系
以一条真实记录为例：
text（原文）："AI manually triggered a morning report script on April 3, 2026."
l0（一句话)："AI manually triggered a morning report script on April 3, 2026."（text 很短时，l0 可以和 text 相同）
l1（要点列表)："- The AI manually triggered the morning report script\n- It wrote the content of April 2, 2026's report to IMA\n- Note ID: XXX"
l2（完整内容)："AI于2026年04月03日手动触发早报脚本成功运行，将2026年04月02日的早报内容写入了IMA（note_id: XXX）"
三层摘要的作用是让 AI 在回答不同复杂度的问题时，可以选择合适粒度的参考内容——简单问题用 l0，复杂问题用 l1/l2。
2.2 Capture 流程
记忆是如何产生的？有三种途径：
途径一：自动 Session Capture（主要方式）
当一个对话 session 结束时，memory-lancedb-pro 的 agent_end hook 会自动运行 smart extraction：
途径二：memory_store API（手动存入）
通过 memory_store 工具直接写入重要记忆。
注意：直接存入的记录，
text会被原样复制到 l0/l1/l2，LLM enrichment 不会自动触发。真正的分层摘要需要通过途径一或后续的 upgrade 批处理生成。
途径三：Import + Upgrade（批量导入）
从其他记忆系统导出 JSON 后，通过以下流程迁移：
# 1. 导入原始数据 openclaw memory-pro import migrated_memories.json --scope global # 2. 批量生成 l0/l1/l2 openclaw memory-pro upgrade --scope global
2.3 Retrieval 流程
当用户发起 query 时，memory-lancedb-pro 使用 Hybrid Search 混合检索：
→ top-K 候选结果 → Rerank 精排 (bge-reranker-v2-m3)
→ 综合相关性 + 时效性 → top-N 返回
关键参数：
| 参数 | 含义 | 建议值 |
|---|---|---|
candidatePoolSize | 向量初筛候选数 | 20 |
minScore | 向量检索最低分 | 0.45 |
hardMinScore | 硬过滤阈值 | 0.35 |
recencyHalfLifeDays | 时效性衰减半衰期 | 14天 |
recencyWeight | 时效性权重 | 0.1 |
三、安装步骤
3.1 环境准备
版本要求： OpenClaw 2026.x.x
需要同时具备以下三个模型的使用权限，建议在 SiliconFlow 申请一个 API Key：
- Embedding 模型：BAAI/bge-m3（速度快，1024维）
- Reranker 模型：BAAI/bge-reranker-v2-m3（精排用）
- LLM 模型：THUDM/GLM-4-9B-0414（推荐，生成摘要速度快）
3.2 配置参数详解
在 openclaw.json 中添加或修改以下配置：
{
"plugins": {
"slots": {
"memory": "memory-lancedb-pro"
},
"entries": {
"memory-lancedb-pro": {
"enabled": true,
"config": {
"embedding": {
"apiKey": "your-siliconflow-api-key",
"model": "BAAI/bge-m3",
"baseURL": "https://api.siliconflow.cn/v1",
"dimensions": 1024
},
"retrieval": {
"mode": "hybrid",
"candidatePoolSize": 20,
"minScore": 0.45,
"hardMinScore": 0.35,
"rerank": "cross-encoder",
"rerankApiKey": "your-siliconflow-api-key",
"rerankModel": "BAAI/bge-reranker-v2-m3",
"rerankEndpoint": "https://api.siliconflow.cn/v1/rerank",
"rerankProvider": "siliconflow",
"recencyHalfLifeDays": 14,
"recencyWeight": 0.1
},
"llm": {
"apiKey": "your-siliconflow-api-key",
"model": "THUDM/GLM-4-9B-0414",
"baseURL": "https://api.siliconflow.cn/v1",
"timeoutMs": 45000
},
"autoCapture": true,
"autoRecall": true,
"autoRecallTimeoutMs": 15000
}
}
}
}
}
各组件模型选型参考：
| 组件 | 推荐模型 | 速度 | 质量 | 备注 |
|---|---|---|---|---|
| Embedding | BAAI/bge-m3 | 快 | 高 | 1024维，支持多语言 |
| Reranker | BAAI/bge-reranker-v2-m3 | 中 | 高 | 精排，显著提升精度 |
| LLM（首选） | THUDM/GLM-4-9B-0414 | 2.1s/条 | 高 | 推荐，速度快，无 JSON 解析错误 |
| LLM（备选） | deepseek-ai/DeepSeek-R1-Distill-Qwen-7B | 5.1s/条 | 高 | 速度较慢，偶有 JSON 解析失败 |
实测对比（GLM-4-9B vs DeepSeek-7B）：
GLM-4-9B: 2.1s/条（平均） DeepSeek-7B: 5.1s/条（平均） 加速比: 约 2.4 倍
3.3 插件切换
如果之前使用了其他记忆插件，需要：
- 安装 memory-lancedb-pro（通过 OpenClaw 的插件管理）
- 修改 slots.memory 指向新插件
- 可选：清理旧插件配置（从 plugins.entries / plugins.allow / plugins.installs 中移除）
- 重启 Gateway
openclaw gateway restart
3.4 数据导入
从其他记忆系统迁移时，通常的流程是：
Step 1：从旧插件导出 JSON
不同插件有不同的导出方式，通常是生成一个包含所有记忆的 JSON 文件。
Step 2：导入 LanceDB
openclaw memory-pro import your_memories.json --scope global
这一步会把 JSON 中的每条记录写入 LanceDB，text 字段会被填充。
Step 3：批量生成 l0/l1/l2
openclaw memory-pro upgrade --scope global
upgrade 会逐条调用 LLM，为每条记录生成分层摘要。700 条记录大约需要 20-30 分钟（GLM-4-9B 速度下）。
四、踩坑实录
4.1 LanceDB _versions/ 快照膨胀
现象：
升级过程中，LanceDB 目录从几十 MB 迅速膨胀到 300+ MB。其中 _versions/ 目录占用了绝大部分空间。
memories.lance/ ├── data/ 23MB ← 实际数据 ├── _versions/ 320MB ← MVCC 版本快照（主要空间消耗） ├── _transactions/ 18MB └── _indices/ 12KB
原因：
LanceDB 使用 MVCC（多版本并发控制），每次写入都会产生新的版本快照文件。升级过程中大量写入操作，快速积累了数千个版本文件。
教训：
_versions/目录是 LanceDB manifest 的一部分，记录了数据文件的版本映射关系。不能单独删除它——删除后数据库无法定位数据文件，会导致数据损坏。
正确备份方式：
# 方式一：JSON 导出（推荐日常使用，~180KB） openclaw memory-pro export --scope global 2>/dev/null | grep -v "^\[plugins\]" > export.json gzip -c export.json > lancedb-json-latest.tar.gz # 方式二：完整目录备份（紧急恢复用，~44MB） tar -czf lancedb-latest.tar.gz /root/.openclaw/memory/lancedb-pro/
JSON 导出文件极小（180KB vs 44MB），且包含所有记录数据，是更实用的日常备份方案。
4.2 升级 Lock File 冲突
现象：
同时启动多个 memory-pro upgrade 进程时报错：
Error: Lock file is already being held
原因：
LanceDB 的写操作需要获取锁，多进程同时写入会产生冲突。
解决：
单进程串行执行。升级过程中避免启动多个 upgrade 实例。
4.3 memory_store 不触发 LLM enrichment
现象：
使用 memory_store 工具手动存入的记录，l0_abstract / l1_overview / l2_content 字段的内容和 text 完全相同，没有经过 LLM 处理。
分析：
这是预期行为。memory_store 是一个简单的直接写入 API，不触发 smart extraction 流程。LLM enrichment 发生在：
memory-pro upgradeCLI（批量处理）- Session 结束时的 auto capture
直接存入的记录，text 通常本身就是摘要，不需要额外压缩。真正的分层摘要生成依赖 upgrade 或 session capture 流程。
4.4 auto-recall 超时
现象：
Gateway 日志中出现警告：
memory-lancedb-pro: auto-recall timed out after 5000ms; skipping memory injection
原因：
每次 agent 启动时，会从 LanceDB 检索相关记忆（auto-recall）。如果检索速度慢（网络延迟、向量检索慢），超过 5 秒就会被强制跳过。
解决：
在配置中增加超时阈值：
{
"plugins": {
"entries": {
"memory-lancedb-pro": {
"config": {
"autoRecallTimeoutMs": 15000
}
}
}
}
}
然后重启 Gateway。
五、备份策略
5.1 方案对比
| 方案 | 文件大小 | COS 写入速度 | 可移植性 | 适用场景 |
|---|---|---|---|---|
| JSON 导出 | ~180KB | 极快 | 高 | 日常备份首选 |
| 完整目录 | ~44MB | 较慢 | 中 | 紧急恢复备底 |
推荐策略：日常用 JSON 导出（COS)，每周末用完整目录备份（本地）。
5.2 备份脚本参考
#!/bin/bash
# LanceDB 每日备份脚本
COS_DIR="/lhcos-data/backup-memory"
LOCAL_DIR="/root/backups"
EXPORT_FILE="/tmp/lancedb-export.json"
# 1. JSON 导出 → COS
echo "[$(date)] Exporting LanceDB..."
openclaw memory-pro export --scope global 2>/dev/null | grep -v "^\[plugins\]" > "$EXPORT_FILE"
gzip -c "$EXPORT_FILE" > "$COS_DIR/lancedb-json-latest.tar.gz"
# 2. 完整目录 → 本地
echo "[$(date)] Backing up full directory..."
tar -czf "$LOCAL_DIR/lancedb-latest.tar.gz" \
-C /root/.openclaw/memory lancedb-pro/ 2>/dev/null
echo "[$(date)] Done."
5.3 恢复脚本参考
#!/bin/bash
# LanceDB 恢复脚本
# 用法: bash restore-lancedb.sh [--full]
# --full: 从完整目录备份恢复
# 默认: 从 JSON 备份导入
if [ "$1" == "--full" ]; then
# 完整目录恢复
openclaw gateway stop
tar -xzf /root/backups/lancedb-latest.tar.gz -C /root/.openclaw/memory/
openclaw gateway start
echo "Done. Run 'openclaw memory-pro upgrade --scope global' if needed."
else
# JSON 导入恢复
tar -xzf /lhcos-data/backup-memory/lancedb-json-latest.tar.gz -C /tmp/
JSON=$(find /tmp -name "*.json" | head -1)
openclaw memory-pro import "$JSON" --scope global
rm -rf /tmp/lancedb-*
echo "Done."
fi
六、效果与总结
| 维度 | 效果 |
|---|---|
| 语义搜索 | 支持自然语言 query，不再依赖关键词匹配 |
| 分层摘要 | l0/l1/l2 满足从简答到复杂推理的不同需求 |
| 导入能力 | 支持从多种记忆格式迁移，无缝衔接 |
| 向量检索 | BGE-M3 + bge-reranker 双通道，语义精度更高 |
| 配置灵活 | SiliconFlow 一站式提供 Embedding + Rerank + LLM |
适用场景：
- 个人 AI 助手，需要长期记忆用户偏好和上下文
- 多 Agent 协作系统，多个 agent 共享知识库
- 从旧记忆系统升级，期望保留历史积累
注意事项：
- 定期备份 JSON 导出（COS + 本地双份）
- 不要手动删除 LanceDB 的任何子目录（包括
_versions/） - 如果配置修改后不生效，记得重启 Gateway