openClaw_agent_dm/docs/MEMORY_ARCHITECTURE.md

# 四层记忆架构 (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 的核心文件

- **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 向量
**符合度:** 60%

### 当前实现

- 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`

### 硬件限制

- 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         │      │  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.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