13 KiB

Raw Blame History

四层记忆架构 (Memory Layer Architecture)

版本: 2.1 日期: 2026-03-01 维护者: 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 的核心文件

Eason (main): /root/.openclaw/workspace/
张大师 (life): /root/.openclaw/workspace/agents/life-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 向量 符合度: 60%

当前实现

QMD 系统为每个 Agent 维护独立 SQLite 索引
Main: /root/.openclaw/agents/main/qmd/xdg-cache/qmd/index.sqlite
Life: /root/.openclaw/agents/life/qmd/xdg-cache/qmd/index.sqlite
自动索引 MEMORY.md 和 memory/**/*.md

硬件限制

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 维) 符合度: 85%

技术栈

组件	技术	配置
向量数据库	Qdrant v1.15.3	localhost:6333
Collection	mem0_v4_shared	统一共享
Embedding	text-embedding-v4	1024 维度
LLM	DashScope Qwen Plus	记忆提取/合并
网络	Tailscale	跨服务器访问

三级可见性

可见性	字段值	检索规则	适用场景
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 端口"

数据流

用户消息 → 选择性过滤 → 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 (life)  │      ┌──────────────────┐         │
│  │                  │      │  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.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

13 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.1 (2026-03-01)

v2.0 (2026-02-28)

v1.0 (2026-02-22)

13 KiB

Raw Blame History