OpenClaw 记忆系统架构优化

> 本文介绍一套可落地、可扩展、可维护的 OpenClaw 记忆系统升级方案，包含设计动机、架构演进、实现步骤与维护流程。适用于希望提升 AI 助手记忆能力的 OpenClaw 用户。

0. 摘要 / TL;DR

• 原生 OpenClaw 记忆：memory-core 插件 + memory_search，只索引 MEMORY.md 与 memory/*.md（可选 sessions）。
• 痛点：缺乏结构化知识图谱、无法分层加载、会话检索成本极高、无衰减机制。
• 优化方案：

- 三层记忆：life/ 知识图谱 + memory/ 日记 + tacit_knowledge.md 用户画像

- 搜索层：

- memory_search 只管 memory/ + life/summary（小而稳）

- qmd 负责 life/items.json 与 sessions-clean（会话检索）

- 自动化：kg.py（抽取/刷新/衰减）+ sessions_sync.py（清洗会话）+ cron + heartbeat

• 效果：会话检索从 87MB raw 降至 3.2MB clean，embedding 从 ~50k chunks 降到 1588 chunks（2 分钟完成），检索质量更高、成本更低。

1. 原生 OpenClaw 记忆架构（Baseline）

1.1 记忆文件布局

• memory/YYYY-MM-DD.md：日记式记录（每天新增）
• MEMORY.md：长期记忆（主会话加载）

1.2 memory-core 插件

• 提供 memory_search / memory_get
• 索引位置：~/.openclaw/memory/{agentId}.sqlite
• 默认索引来源：memory/（可选 sessions）

1.3 默认检索方式

• 向量检索 + BM25 混合检索（自动）
• 配置项：

```json

agents.defaults.memorySearch = {

sources: ["memory"],

provider: "local"|"openai"|"gemini",

fallback: "none"|"openai"|"gemini",

extraPaths: [...]

}

```

1.4 原生不足

1. 缺少结构化知识图谱：只有扁平文本，无法按项目/人物/公司等实体组织。
2. 无法分层加载：所有内容同层级，难以"先 summary、再详情"。
3. 会话检索成本极高：sessions.jsonl 巨大且噪音多，向量化成本大。
4. 无衰减机制：长期记忆无法自动降权或归档。

2. 目标与设计原则

• 可持久化：记录不丢失，且能追溯历史。
• 可检索：支持关键词 + 语义检索，且可控成本。
• 可衰减：过期信息退居二线，但不删除。
• 自动化：每天自动抽取、每周自动更新摘要。
• 轻维护：新部署的 OpenClaw 也能一步完成配置。

3. 新架构总览（三层 + 搜索层）

3.1 三层记忆结构

clawd/
├── life/                  # 知识图谱（PARA）
│   ├── projects/
│   │   └── <project>/
│   │       ├── summary.md
│   │       └── items.json
│   ├── areas/
│   │   ├── people/<name>/
│   │   └── companies/<name>/
│   ├── resources/<topic>/
│   └── archives/
├── memory/                # 日记与临时记录
│   └── YYYY-MM-DD.md
└── memory/tacit_knowledge.md  # 用户画像

3.2 搜索层设计

• memory_search：只索引 memory/ + life/summary
• qmd：

- life collection：索引 items.json（结构化事实）

- sessions-clean collection：索引清洗会话文本

4. 关键数据结构

4.1 items.json（原子化事实）

{
  "entity": {
    "name": "openclaw-web-search",
    "type": "project",
    "createdAt": "2026-02-03"
  },
  "items": [
    {
      "id": "a1b2c3d4",
      "fact": "OpenClaw web.search.provider only supports brave/perplexity",
      "category": "context",
      "timestamp": "2026-02-01",
      "status": "active",
      "supersededBy": null,
      "relatedEntities": [],
      "lastAccessed": "2026-02-03",
      "accessCount": 2
    }
  ]
}

4.2 summary.md（分层摘要）

• 只写 Hot / Warm
• Cold 自动剔除

5. 实现步骤

Step 0 — 备份（强烈建议）

# 备份 OpenClaw 工作区和配置
tar -czf backup_$(date +%Y%m%d).tar.gz ~/clawd ~/.openclaw

Step 1 — 创建目录 & 模板

mkdir -p ~/clawd/life/{projects,areas/people,areas/companies,resources,archives,_templates}

# summary 模板
cat > ~/clawd/life/_templates/summary.md <<'EOF'
# {{ENTITY_NAME}}
更新时间: {{UPDATED_AT}}

## Hot (<=7天)
- （暂无）

## Warm (8-30天)
- （暂无）
EOF

# items 模板
cat > ~/clawd/life/_templates/items.json <<'EOF'
{
  "entity": {
    "name": "{{ENTITY_NAME}}",
    "type": "project|person|company|resource|other",
    "createdAt": "{{CREATED_AT}}"
  },
  "items": []
}
EOF

# tacit_knowledge
cat > ~/clawd/memory/tacit_knowledge.md <<'EOF'
# Tacit Knowledge (用户画像)

## 沟通偏好
- （待补充）

## 工作风格
- （待补充）

## 工具使用习惯
- （待补充）

## 边界 / 禁区
- （待补充）
EOF

Step 2 — 引入知识图谱脚本 kg.py

文件：~/clawd/scripts/memory/kg.py

核心能力：

• init：创建实体
• extract：从 daily notes 提取事实
• refresh：Hot/Warm/Cold 衰减重建 summary
• access：访问计数
• index：更新 qmd 索引

关键逻辑片段（衰减规则）：

HOT_DAYS = 7
WARM_DAYS = 30
FREQ_PROTECT_THRESHOLD = 10

def classify_fact(fact):
    last = fact.get("lastAccessed", fact.get("timestamp"))
    days_ago = (now - last_dt).days
    protect = fact.get("accessCount", 0) >= FREQ_PROTECT_THRESHOLD

    if days_ago <= HOT_DAYS: return "hot"
    elif days_ago <= WARM_DAYS: return "hot" if protect else "warm"
    else: return "warm" if protect else "cold"

Step 3 — 会话清洗脚本 sessions_sync.py

文件：~/clawd/scripts/memory/sessions_sync.py

策略：只保留 user/assistant 文本，压缩冗余。

• 默认 max-chars=20000
• 保留 head 20 + tail 80 消息

核心逻辑：

if len(messages) > head + tail:
    messages = head + ["... omitted ..."] + tail
if len(text) > max_chars:
    text = text[:head_chars] + "..." + text[-tail_chars:]

Step 4 — 配置 qmd collections

export PATH="$HOME/.bun/bin:$PATH"

# daily notes
qmd collection add ~/clawd/memory --name daily-logs --mask '**/*.md'

# workspace docs
qmd collection add ~/clawd --name workspace --mask '*.md'

# knowledge graph
qmd collection add ~/clawd/life --name life --mask '**/*.{md,json}'

# cleaned sessions
qmd collection add ~/clawd/sessions-clean --name sessions-clean --mask '**/*.md'

qmd update
qmd embed

Step 5 — OpenClaw 配置修改

修改 ~/.openclaw/openclaw.json：

agents.defaults.memorySearch = {
  sources: ["memory"],
  extraPaths: ["life"],
  fallback: "none",
  experimental: { sessionMemory: false }
}

Step 6 — 定时任务（cron）

# Daily Extract
openclaw cron add ...
# 逻辑：sessions_sync -> kg extract -> kg index

# Weekly Refresh
openclaw cron add ...
# 逻辑：sessions_sync -> kg refresh -> kg index

Step 7 — Heartbeat 调整

新增检查：

• sessions_sync 清洗同步
• kg status

6. 验证方法

# 创建测试实体
python3 kg.py init project test-project
python3 kg.py init person test-person

# 抽取事实
python3 kg.py extract --days 3

# 重建 summary
python3 kg.py refresh

# 查询
qmd search "openclaw" -c life
qmd vsearch "memory search" -c sessions-clean

7. 实际效果（关键提升）

| 项目 | 原始 sessions | sessions-clean |

|------|--------------|----------------|

| 体积 | 87MB | 3.2MB |

| Embedding chunks | ~49,000 | 1,588 |

| 运行时长 | ~1h 且易 SIGKILL | ~2min |

结论：会话检索质量更好、成本更低、维护更简单。

8. 维护 & 同步建议

• 每日：sessions_sync + kg extract + kg index
• 每周：kg refresh + kg index
• 心跳：sessions_sync + qmd update + kg status
• 冷知识保留：只降权，不删除，历史可追溯

9. 常见问题

Q: memory_search 还能搜 sessions 吗？

A: 本方案下禁用 sessions，避免重复索引。会话检索走 qmd sessions-clean。

Q: qmd embed 太慢？

A: 只对 sessions-clean 做 embedding，大幅缩短时间。

Q: 如何备份知识图谱数据？

A: 直接备份 ~/clawd/life/ 目录即可，所有结构化数据都在其中。

10. 附录：常用命令清单

# 创建实体
python3 ~/clawd/scripts/memory/kg.py init project my-project

# 抽取事实
python3 ~/clawd/scripts/memory/kg.py extract --days 3

# 刷新摘要
python3 ~/clawd/scripts/memory/kg.py refresh

# 会话清洗
python3 ~/clawd/scripts/memory/sessions_sync.py

# qmd 更新
qmd update
qmd embed