15 KiB

Raw Blame History

四层记忆架构 (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 接入步骤

新服务器安装 Tailscale 并加入同一 tailnet
配置 mem0 的 Qdrant host 指向中心节点 Tailscale IP
在 project_registry.yaml 中注册 agent 及其所属项目
在 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

15 KiB Raw Blame History

四层记忆架构 (Memory Layer Architecture)

架构概览

Layer 1: Core Memory (核心记忆)

关键文件

每个 Agent 的核心文件

差距与待改进

Layer 2: Daily Memory (日常记忆)

文件结构

差距与待改进

Layer 3: Short-term Memory (短期记忆 / QMD)

当前实现

硬件限制

两阶段策略

Layer 4: Mem0 Conversation Memory (对话记忆)

技术栈

三级可见性

记忆衰减策略

数据流

基础设施支撑 (与记忆层正交)

多 Agent 集群支持

同一服务器 (单实例多 Agent)

跨服务器 (多实例多 Agent)

项目注册表

跨服务器多 Agent 集群

网络拓扑

各层的集群行为

跨服务器 Agent 接入步骤

visibility 如何实现三种记忆隔离

安全措施

扩展路线

开发者注意事项

mem0 Python SDK 与 Qdrant 原生 API 的区别

agent_id 双写

Layer 3 FTS5 分词

待实现功能

变更记录

v2.2 (2026-03-16)

v2.1 (2026-03-01)

v2.0 (2026-02-28)

v1.0 (2026-02-22)

15 KiB

Raw Blame History