You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
208 lines
7.5 KiB
208 lines
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: |
|
|
|
```python |
|
# 正确: 扁平 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 对象: |
|
|
|
```python |
|
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 字段: |
|
|
|
```python |
|
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`。 |
|
|
|
### 记忆写入过滤规则 |
|
|
|
以下对话自动跳过写入: |
|
1. 用户消息长度 < 5 字符 |
|
2. 匹配 SKIP_PATTERNS: 好的、收到、OK、嗯、行、没问题、感谢、谢谢 等 |
|
3. 以 `/` 开头的系统命令 |
|
|
|
--- |
|
|
|
## 命令 |
|
|
|
通过 Telegram 使用: |
|
|
|
``` |
|
/memory add <内容> # 手动添加记忆 |
|
/memory search <关键词> # 搜索记忆 |
|
/memory list # 列出所有记忆 |
|
/memory delete <ID> # 删除记忆 |
|
/memory status # 查看状态 |
|
``` |
|
|
|
--- |
|
|
|
## 依赖 |
|
|
|
``` |
|
mem0ai # 核心记忆管理 |
|
qdrant-client # Qdrant 向量数据库客户端 |
|
pyyaml # YAML 配置解析 |
|
``` |
|
|
|
--- |
|
|
|
## 更新记录 |
|
|
|
### v2.1 (2026-03-01) |
|
- 修复: `_execute_search` filter 格式从 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 基础集成
|
|
|