# 四层记忆架构 (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/-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//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