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.
350 lines
15 KiB
350 lines
15 KiB
# 四层记忆架构 (Memory Layer Architecture) |
|
|
|
**版本:** 2.2 |
|
**日期:** 2026-03-16 |
|
**维护者:** Eason (陈医生) |
|
|
|
--- |
|
|
|
## 架构概览 |
|
|
|
OpenClaw 采用四层记忆体系，从本地文件到分布式向量数据库逐层递进，兼顾离线可用性与跨 Agent 共享能力。 |
|
|
|
``` |
|
┌──────────────────────────────────────────────────────────────────┐ |
|
│ Memory Layer 1: Core Memory (核心记忆) │ |
|
│ MD 文件 — CORE_INDEX.md / IDENTITY.md / SOUL.md 等 │ |
|
│ 启动时首先加载，定义 Agent 身份与行为准则 │ |
|
│ 作用域: 每个 Agent 独立 │ |
|
├──────────────────────────────────────────────────────────────────┤ |
|
│ Memory Layer 2: Daily Memory (日常记忆) │ |
|
│ MEMORY.md (长期策略) + memory/*.md (每日记录) │ |
|
│ Git 版本控制保护，支持回溯 │ |
|
│ 作用域: 每个 Agent 独立，Git 备份 │ |
|
├──────────────────────────────────────────────────────────────────┤ |
|
│ Memory Layer 3: Short-term Memory (短期记忆 / QMD) │ |
|
│ SQLite FTS5 全文检索 + 可选 GGUF 本地向量 │ |
|
│ 离线可用，Layer 4 不可达时自动接管 │ |
|
│ 作用域: 每个 Agent 独立，纯本地 │ |
|
├──────────────────────────────────────────────────────────────────┤ |
|
│ Memory Layer 4: Mem0 Conversation Memory (对话记忆) │ |
|
│ Qdrant (mem0_v4_shared) + text-embedding-v4 (1024 维) │ |
|
│ 通过 Tailscale 可跨服务器共享 │ |
|
│ 三级可见性: public / project / private │ |
|
│ 元数据隔离: visibility + project_id + agent_id │ |
|
│ 记忆衰减: expiration_date (7d / 30d / permanent) │ |
|
└──────────────────────────────────────────────────────────────────┘ |
|
``` |
|
|
|
--- |
|
|
|
## Layer 1: Core Memory (核心记忆) |
|
|
|
**存储介质:** Markdown 文件 |
|
**符合度:** 90% |
|
|
|
### 关键文件 |
|
|
|
| 文件 | 用途 | 加载时机 | |
|
|------|------|----------| |
|
| `CORE_INDEX.md` | 核心索引，结构总览 | 会话启动时首先加载 | |
|
| `IDENTITY.md` | Agent 身份定义 | 会话启动 | |
|
| `SOUL.md` | 人格与行为准则 | 会话启动 | |
|
| `USER.md` | 用户信息 | 会话启动 | |
|
| `AGENTS.md` | Agent 运维指南 | 按需加载 | |
|
| `TOOLS.md` | 工具配置 | 按需加载 | |
|
|
|
### 每个 Agent 的核心文件 |
|
|
|
- **Main:** `/root/.openclaw/workspace/` |
|
- **Spoke agents:** `/root/.openclaw/workspace/agents/<agent_id>-workspace/` |
|
|
|
### 差距与待改进 |
|
|
|
- 缺少跨 Agent 的共享核心记忆索引 |
|
- 未来可通过 `shared/` 目录实现集群通用规则 |
|
|
|
--- |
|
|
|
## Layer 2: Daily Memory (日常记忆) |
|
|
|
**存储介质:** Markdown 文件 + Git |
|
**符合度:** 85% |
|
|
|
### 文件结构 |
|
|
|
- `MEMORY.md` — 长期决策、安全模板、架构要点 (380+ 行) |
|
- `memory/*.md` — 每日记忆文件 |
|
- `memory_strategy.md` — 记忆管理策略文档 |
|
|
|
### 差距与待改进 |
|
|
|
- MEMORY.md 混合了"长期决策"和"配置模板"，需结构化分类 |
|
- 日常记忆文件命名不统一 |
|
- 缺乏自动归档/淘汰机制 |
|
|
|
--- |
|
|
|
## Layer 3: Short-term Memory (短期记忆 / QMD) |
|
|
|
**存储介质:** SQLite (FTS5) + 可选 GGUF 向量 |
|
**符合度:** 85%（已实现自动 fallback） |
|
|
|
### 当前实现 |
|
|
|
- QMD 系统为每个 Agent 维护独立 SQLite 索引 |
|
- Main: `/root/.openclaw/agents/main/qmd/xdg-cache/qmd/index.sqlite` |
|
- Spoke: `/root/.openclaw/agents/<agent_id>/qmd/xdg-cache/qmd/index.sqlite` |
|
- 自动索引 `MEMORY.md` 和 `memory/**/*.md` |
|
- **自动 fallback**：`mem0_client._execute_search()` 检测到 Qdrant 完全不可达时（`_init_memory()` 失败或所有 phase 均报错），自动调用 `LocalSearchFallback` 进行 FTS5 检索，首次触发时懒加载并 `rebuild_index()`，无需手动干预 |
|
|
|
### 硬件限制 |
|
|
|
- CPU: 2 核 Xeon E3-12xx v2 (2.7GHz, AVX, 无 AVX2) |
|
- RAM: 3.8GB 总量，可用 ~850MB |
|
- GPU: 无 |
|
|
|
### 两阶段策略 |
|
|
|
**阶段 A: SQLite FTS5 全文检索** (零额外内存) |
|
- 覆盖 80% 离线检索需求 |
|
- 中文分词 + 关键词/短语搜索 |
|
|
|
**阶段 B: GGUF 按需加载** (需 >= 300MB 空闲内存) |
|
- 模型: `bge-small-zh-v1.5` Q4_K_M (~50MB) |
|
- 不常驻内存，用完释放 |
|
- Layer 4 不可达时自动切换 |
|
|
|
--- |
|
|
|
## Layer 4: Mem0 Conversation Memory (对话记忆) |
|
|
|
**存储介质:** Qdrant + text-embedding-v4 (1024 维，经 OneAPI) |
|
**符合度:** 100% |
|
|
|
### 技术栈 |
|
|
|
| 组件 | 技术 | 配置 | |
|
|------|------|------| |
|
| 向量数据库 | Qdrant v1.15.3 | localhost:6333 | |
|
| Collection | mem0_v4_shared | 统一共享 | |
|
| Embedding | text-embedding-v4 | 1024 维度，经 OneAPI 路由 | |
|
| LLM | MiniMax-M2.5 | 记忆提取/合并，经 OneAPI 路由 | |
|
| API 网关 | OneAPI | `http://100.115.94.1:3000/v1`，统一管理 Chat + Embedding | |
|
| 网络 | Tailscale | 跨服务器访问 | |
|
|
|
**LLM 与 Embedder 分工**：LLM 负责从对话中提取有价值的记忆并去重/合并；Embedder 负责向量化（读写均需调用）。两者共享 OneAPI 网关但各自独立路由，可配置不同渠道。 |
|
|
|
### 三级可见性 |
|
|
|
| 可见性 | 字段值 | 检索规则 | 适用场景 | |
|
|--------|--------|----------|----------| |
|
| **public** | `visibility=public` | 所有 Agent 可检索 | 集群通用信息 | |
|
| **project** | `visibility=project` | 同 `project_id` 成员可检索 | 项目共享知识 | |
|
| **private** | `visibility=private` | 仅 `agent_id` 本人可检索 | Agent 私有记忆 | |
|
|
|
### 记忆衰减策略 |
|
|
|
| 记忆类型 | 过期时间 | 示例 | |
|
|----------|----------|------| |
|
| session | 7 天 | "正在讨论服务器部署" | |
|
| chat_summary | 30 天 | "上周讨论了 Qdrant 迁移方案" | |
|
| preference | 永不过期 | "用户偏好 Tailscale 组网" | |
|
| knowledge | 永不过期 | "Qdrant 部署在 6333 端口" | |
|
|
|
**自动清理 (Cron)**：写入时设置的 `expiration_date` 不由 Qdrant 自动删除，通过每日 cron 任务强制执行： |
|
|
|
``` |
|
# /etc/cron.d/mem0-cleanup — 每天凌晨 3:00 UTC 执行 |
|
0 3 * * * root cd /root/.openclaw/workspace/skills/mem0-integration \ |
|
&& python3 memory_cleanup.py --execute |
|
|
|
# 日志: /root/.openclaw/workspace/logs/security/cleanup-cron.log |
|
# 审计日志: /root/.openclaw/workspace/logs/security/memory-cleanup-YYYY-MM-DD.log |
|
``` |
|
|
|
清理优先级：① `expiration_date` 字段（写入时设置）→ ② 写入时间 (`timestamp`) + 保留天数兜底。 |
|
手动触发（dry-run 预览）：`python3 memory_cleanup.py --dry-run` |
|
手动执行：`python3 memory_cleanup.py --execute` |
|
强制清理（覆盖所有类型阈值）：`python3 memory_cleanup.py --execute --max-age-days 14` |
|
|
|
### 数据流 |
|
|
|
``` |
|
用户消息 → 选择性过滤 → Post-Hook 异步写入 → Qdrant |
|
↓ |
|
自动设置 expiration_date |
|
自动标注 visibility / project_id |
|
↓ |
|
Mem0 ADD/UPDATE/DELETE/NOOP |
|
``` |
|
|
|
--- |
|
|
|
## 基础设施支撑 (与记忆层正交) |
|
|
|
| 基础设施 | 保护的记忆层 | 职责 | |
|
|----------|-------------|------| |
|
| Git | Layer 1 + Layer 2 | 版本控制、备份、回溯 | |
|
| Monitoring (systemd) | Layer 4 | 监控 Gateway/Qdrant 健康状态 | |
|
| Tailscale | Layer 4 | 跨服务器安全通信 | |
|
|
|
--- |
|
|
|
## 多 Agent 集群支持 |
|
|
|
### 同一服务器 (单实例多 Agent) |
|
|
|
- 共享同一 Gateway 实例 |
|
- 通过 Session 隔离各 Agent 上下文 |
|
- 共享 Qdrant Collection，metadata 软隔离 |
|
|
|
### 跨服务器 (多实例多 Agent) |
|
|
|
- 通过 Tailscale VPN 连接中心 Qdrant |
|
- `project_registry.yaml` 管理 Agent-项目映射 |
|
- `visibility` 字段控制记忆可见性 |
|
|
|
### 项目注册表 |
|
|
|
位置: `/root/.openclaw/workspace/skills/mem0-integration/project_registry.yaml` |
|
|
|
管理 Agent 与项目的归属关系，决定 project 级记忆的访问权限。 |
|
|
|
--- |
|
|
|
## 跨服务器多 Agent 集群 |
|
|
|
### 网络拓扑 |
|
|
|
``` |
|
┌──────────────────────────────────────────────────────────┐ |
|
│ Tailscale VPN (WireGuard) │ |
|
│ │ |
|
│ ┌──────────────────┐ ┌──────────────────┐ │ |
|
│ │ Server 1 (VPS) │ │ Server 2 │ │ |
|
│ │ 100.115.94.1 │ │ 100.64.x.x │ │ |
|
│ │ │ │ │ │ |
|
│ │ Qdrant Master │◄─────│ Agent-C │ │ |
|
│ │ :6333 │ │ (remote) │ │ |
|
│ │ │ └──────────────────┘ │ |
|
│ │ Agent-A (main) │ ┌──────────────────┐ │ |
|
│ │ Agent-B │ │ Server 3 │ │ |
|
│ │ │◄─────│ 100.64.x.x │ │ |
|
│ │ │ │ Agent-D │ │ |
|
│ └──────────────────┘ └──────────────────┘ │ |
|
└──────────────────────────────────────────────────────────┘ |
|
``` |
|
|
|
### 各层的集群行为 |
|
|
|
| 记忆层 | 同服务器多 Agent | 跨服务器多 Agent | |
|
|--------|-----------------|-----------------| |
|
| Layer 1 (Core) | 各 Agent 独立工作区 | 各服务器独立文件系统 | |
|
| Layer 2 (Daily) | 各 Agent 独立 memory/ | 各服务器独立，Git 同步 | |
|
| Layer 3 (QMD) | 各 Agent 独立 SQLite | 各服务器独立，纯本地 | |
|
| Layer 4 (Mem0) | 共享 Qdrant，metadata 隔离 | 通过 Tailscale 连接中心 Qdrant | |
|
|
|
### 跨服务器 Agent 接入步骤 |
|
|
|
1. 新服务器安装 Tailscale 并加入同一 tailnet |
|
2. 配置 mem0 的 Qdrant host 指向中心节点 Tailscale IP |
|
3. 在 `project_registry.yaml` 中注册 agent 及其所属项目 |
|
4. 在 `agents/registry.md` 中登记新 Agent |
|
|
|
### visibility 如何实现三种记忆隔离 |
|
|
|
``` |
|
通用信息 (全集群共享): |
|
写入: visibility=public |
|
检索: 所有 agent 的 Phase 1 自动检索 public 记忆 |
|
|
|
项目记忆 (项目内共享): |
|
写入: visibility=project, project_id=<项目标识> |
|
检索: Phase 2 查 project_registry.yaml 获取 agent 所属项目列表 |
|
仅检索自己所属项目的记忆 |
|
|
|
私密记忆 (仅自身可见): |
|
写入: visibility=private, agent_id=<自身> |
|
检索: Phase 3 仅检索 agent_id 匹配的私密记忆 |
|
``` |
|
|
|
### 安全措施 |
|
|
|
- Tailscale WireGuard 端到端加密传输 |
|
- Qdrant 仅绑定 127.0.0.1，不暴露公网 |
|
- Pre-hook 强制注入 agent_id filter，防止跨域访问 |
|
- 审计日志记录所有跨域检索尝试 |
|
|
|
### 扩展路线 |
|
|
|
- **短期**: 单 Qdrant 实例 + Tailscale 远程访问 (当前) |
|
- **中期**: Qdrant 快照定期备份，灾备恢复 |
|
- **长期**: Qdrant 集群模式或 Qdrant Cloud (按负载决定) |
|
|
|
--- |
|
|
|
## 开发者注意事项 |
|
|
|
> 详细代码级文档: `skills/mem0-integration/SKILL.md` |
|
|
|
### mem0 Python SDK 与 Qdrant 原生 API 的区别 |
|
|
|
| 操作 | mem0 SDK (mem0_client.py) | Qdrant 原生 (memory_cleanup.py) | |
|
|------|--------------------------|-------------------------------| |
|
| filter | 扁平 dict: `{"key": "val"}` | `Filter(must=[FieldCondition(...)])` | |
|
| 多条件 | 多 key 隐式 AND: `{"a": 1, "b": 2}` | `Filter(must=[cond1, cond2])` | |
|
| 搜索 | `m.search(query, filters=...)` | `client.search(collection, query_vector, ...)` | |
|
|
|
混用格式是常见 bug 来源。mem0 `search(filters=...)` 不支持 Qdrant 的嵌套 `{"AND": [...]}` 语法。 |
|
|
|
### agent_id 双写 |
|
|
|
`mem0.add()` 需要同时传递 `agent_id` 为顶层参数和 metadata 字段。顶层参数供 mem0 内部索引，metadata 字段供自定义 filter 检索。漏写任一会导致特定检索路径失效。 |
|
|
|
### Layer 3 FTS5 分词 |
|
|
|
使用字符级分词，仅保留 CJK 统一表意文字 (U+4E00–U+9FFF) 和 ASCII 字母数字。标点和特殊符号被过滤，避免索引噪音。精度低于 jieba 词级分词，但零额外依赖。 |
|
|
|
### 待实现功能 |
|
|
|
| 功能 | 优先级 | 说明 | |
|
|------|--------|------| |
|
| 审计日志 | P2 | 跨域检索审计记录，防止越权访问 | |
|
| GGUF 按需加载 | P3 | Layer 3 本地向量，需 >= 300MB 空闲内存 | |
|
| Qdrant 集群化 | P3 | 按负载增长决定 | |
|
|
|
--- |
|
|
|
## 变更记录 |
|
|
|
### v2.2 (2026-03-16) |
|
- **架构**: mem0 LLM + Embedder 切换到 OneAPI 网关（`http://100.115.94.1:3000/v1`），API 端点和密钥与 OpenClaw Agent 共用 `.env` 中的 `LLM_BASE_URL` / `LLM_API_KEY`，移除 DashScope 直连依赖 |
|
- **Layer 3**: FTS5 fallback 由手动调用改为自动触发，Qdrant 不可达时无感切换，首次触发懒加载索引 |
|
- **可见性分类**: `_classify_visibility()` 支持三级自动推断（public / project / private），project 关键词从 `project_registry.yaml` 动态提取 |
|
- **cleanup 脚本修复**: 修复死代码导致的 `--max-age-days` 覆盖 per-type 保留策略 bug；修复按 `expiration_date` 字段判断过期（原先错误使用 `timestamp` 写入时间）；修复 `PointIdsList` 调用格式；移除无关的 DashScope API key 初始化 |
|
- **自动清理 cron**: 接入 `/etc/cron.d/mem0-cleanup`，每天凌晨 3:00 UTC 自动执行 `memory_cleanup.py --execute`，Layer 4 符合度达到 100% |
|
|
|
### v2.1 (2026-03-01) |
|
- 修复: `_execute_search` 三阶段检索 filter 格式 (嵌套 AND → 扁平 dict) |
|
- 修复: `_execute_write` 补充 `agent_id` 顶层参数确保检索可达 |
|
- 修复: `session_init.py` 补充 `OPENAI_API_BASE` 环境变量 |
|
- 修复: `local_search.py` FTS5 分词过滤 CJK 标点噪音 |
|
- 清理: 移除未使用的 import |
|
|
|
### v2.0 (2026-02-28) |
|
- 新增: 三级可见性 + 三阶段检索 |
|
- 新增: 记忆衰减 (expiration_date) |
|
- 新增: 智能写入过滤 + 自动分类 |
|
- 新增: 项目注册表 (project_registry.yaml) |
|
- 新增: Layer 3 SQLite FTS5 本地检索 |
|
- 新增: 月度清理脚本 |
|
- 安全: 全部 API Key 改为环境变量 |
|
- 新增: CORE_INDEX.md Memory Architecture 章节 |
|
|
|
### v1.0 (2026-02-22) |
|
- 初始部署: mem0 + Qdrant + DashScope 集成 |
|
|
|
--- |
|
|
|
**最后更新:** 2026-03-01
|
|
|