7.5 KiB
mem0-integration Skill
功能概述
为 OpenClaw 提供基于 mem0 + Qdrant 的对话记忆系统 (Memory Layer 4),包括:
- Pre-Hook 语义检索注入(对话前自动召回相关记忆)
- Post-Hook 异步写入(对话后智能筛选并存储记忆)
- 三级可见性隔离 (public / project / private)
- 记忆衰减 (expiration_date: 7d / 30d / permanent)
- 智能写入过滤(跳过无价值对话)
- Layer 3 FTS5 本地全文检索 fallback(Qdrant 不可达时接管)
- 冷启动记忆预加载(新会话自动注入最近上下文)
架构全景文档:
docs/MEMORY_ARCHITECTURE.md
文件结构
skills/mem0-integration/
├── SKILL.md # 本文档 — 开发者参考
├── openclaw.plugin.json # OpenClaw 插件声明 (lifecycle hook)
├── skill.json # Skill 元数据
├── index.js # JS 入口,桥接 OpenClaw Gateway ↔ Python
│
│ ── 核心运行时 ──
├── mem0_client.py # 核心客户端:初始化、检索、写入、队列、缓存
├── openclaw_interceptor.py # Pre/Post-Hook 拦截器(Gateway 调用入口)
├── session_init.py # 冷启动记忆预加载
│
│ ── 配置 ──
├── config.yaml # mem0 全局配置(Qdrant / LLM / Embedder / Cache)
├── project_registry.yaml # Agent-项目归属关系(决定 project 级可见性)
│
│ ── 辅助工具 ──
├── local_search.py # Layer 3: SQLite FTS5 本地全文检索 fallback
├── memory_cleanup.py # 月度记忆统计与清理脚本
├── migrate_to_single_collection.py # 从旧多 Collection 迁移到单库融合架构
├── recover_memories.py # 记忆恢复工具 v1
├── recover_memories_v2.py # 记忆恢复工具 v2
│
│ ── 旧版 / 命令 ──
├── commands.py # /memory 命令处理
├── openclaw_commands.py # OpenClaw 原生命令扩展
├── mem0_integration.py # 旧版集成入口(已被 mem0_client.py 取代)
│
│ ── 测试 ──
├── test_mem0.py # mem0 单元测试
├── test_integration.py # 集成测试
└── test_production.py # 生产环境测试
环境变量
| 变量名 | 用途 | 必需 | 默认值 |
|---|---|---|---|
MEM0_DASHSCOPE_API_KEY |
DashScope API 密钥 (LLM + Embedding) | 是 | — |
DASHSCOPE_API_KEY |
备选 key 名称 (二选一) | — | — |
MEM0_QDRANT_HOST |
Qdrant 地址 | 否 | localhost |
MEM0_QDRANT_PORT |
Qdrant 端口 | 否 | 6333 |
MEM0_LLM_MODEL |
LLM 模型名 | 否 | qwen-plus |
MEM0_EMBEDDER_MODEL |
Embedding 模型名 | 否 | text-embedding-v4 |
API 密钥查找顺序: MEM0_DASHSCOPE_API_KEY → DASHSCOPE_API_KEY → 已有 OPENAI_API_KEY
DashScope 兼容模式需要同时设置 OPENAI_API_BASE 和 OPENAI_BASE_URL,代码在模块加载时自动完成。
核心模块说明
mem0_client.py — 核心客户端
类: Mem0Client
_init_memory()— 初始化 mem0 Memory 实例(Qdrant + DashScope Embedder 1024 维)start()— 启动异步写入队列的后台 worker(必须在 event loop 中调用)pre_hook_search()— Pre-Hook: 三阶段检索(public → project → private → legacy fallback),带缓存和超时post_hook_add()— Post-Hook: 智能过滤 + 自动分类(memory_type / visibility)+ 入队_execute_write()— 后台异步写入 Qdrant,附带 metadata 和 expiration_date
类: AsyncMemoryQueue
- 基于
collections.deque的有界异步队列 - 后台 worker 每秒轮询,批量处理
全局实例: mem0_client = Mem0Client() — 模块加载时自动创建
openclaw_interceptor.py — 拦截器
Gateway 调用入口。从 context dict 中提取 user_id、agent_id、visibility、project_id、memory_type,桥接到 mem0_client。
local_search.py — Layer 3 FTS5 Fallback
基于 SQLite FTS5 的本地全文检索,Qdrant 不可达时接管。
- CJK 字符逐字拆分 + ASCII 单词保持完整(过滤标点噪音)
- 每个 Agent 维护独立的 FTS5 索引文件
rebuild_index()扫描 MEMORY.md + memory/*.md + 共享核心文件
开发者注意事项
mem0 filter 格式
mem0 search() 的 filters 参数使用扁平 dict,多个条件为隐式 AND:
# 正确: 扁平 dict (mem0 Python SDK)
filters={"visibility": "private", "agent_id": "main"}
# 错误: 嵌套 AND (Qdrant 原生 API 语法,mem0 不支持)
filters={"AND": [{"visibility": "private"}, {"agent_id": "main"}]}
直接操作 Qdrant (如 memory_cleanup.py) 时使用原生 Filter 对象:
from qdrant_client.models import Filter, FieldCondition, MatchValue
Filter(must=[FieldCondition(key="visibility", match=MatchValue(value="public"))])
mem0 add() 的 agent_id
mem0.add() 必须同时传递 agent_id 作为顶层参数和 metadata 字段:
self.local_memory.add(
messages=messages,
user_id=user_id,
agent_id=agent_id, # 顶层: mem0 内部索引用
metadata={
"agent_id": agent_id, # metadata: 自定义 filter 查询用
"visibility": "private",
...
}
)
原因: mem0 的 search(agent_id=...) 匹配顶层字段;search(filters={"agent_id": ...}) 匹配 metadata 字段。两处都写入确保两种检索路径均能命中。
FTS5 中文分词
local_search.py 使用字符级分词(非 jieba),仅保留 CJK 统一表意文字 (U+4E00–U+9FFF) 和 ASCII 字母数字:
- 输入
"你好,world!"→ 输出"你 好 world" - 标点、emoji、特殊符号被过滤,避免 FTS5 索引噪音
- 搜索精度低于 jieba 词级分词,但零依赖、零内存开销
可见性自动分类
_classify_visibility() 只返回 "public" 或 "private"(不自动推断 "project")。项目级可见性必须由调用方通过 context 显式传入 visibility="project" + project_id。
记忆写入过滤规则
以下对话自动跳过写入:
- 用户消息长度 < 5 字符
- 匹配 SKIP_PATTERNS: 好的、收到、OK、嗯、行、没问题、感谢、谢谢 等
- 以
/开头的系统命令
命令
通过 Telegram 使用:
/memory add <内容> # 手动添加记忆
/memory search <关键词> # 搜索记忆
/memory list # 列出所有记忆
/memory delete <ID> # 删除记忆
/memory status # 查看状态
依赖
mem0ai # 核心记忆管理
qdrant-client # Qdrant 向量数据库客户端
pyyaml # YAML 配置解析
更新记录
v2.1 (2026-03-01)
- 修复:
_execute_searchfilter 格式从 Qdrant 嵌套语法改为 mem0 扁平 dict - 修复:
_execute_write补充agent_id顶层参数 - 修复:
session_init.py补充OPENAI_API_BASE环境变量 - 修复:
local_search.py中文分词过滤标点噪音 - 清理: 移除未使用的 import (Optional, os, re)
v2.0 (2026-02-28)
- 新增: 三级可见性 (public / project / private) + 三阶段检索
- 新增: 记忆衰减 (expiration_date)
- 新增: 智能写入过滤
- 新增: 项目注册表 (project_registry.yaml)
- 新增: Layer 3 SQLite FTS5 本地全文检索
- 新增: 月度清理脚本 (memory_cleanup.py)
- 安全: 所有 API Key 改为环境变量
v1.0 (2026-02-22)
- 初始版本: mem0 + Qdrant 基础集成