AI实战丨OpenClaw 记忆系统设计：让你的 AI 伙伴拥有长期记忆

AI实战丨OpenClaw 记忆系统设计：让你的 AI 伙伴拥有长期记忆

AI有招 · AI实战 #36

以下内容可以直接转给你的 OpenClaw 伙伴阅读。

---

引言：AI 最大的短板不是智力，是记忆

你有没有遇到过这种情况——

你和 AI 聊了一整天，配好了服务器、写好了脚本、排查了 Bug。第二天新开会话，它问你：「请问你的服务器 IP 是什么？」

大模型天生没有长期记忆。每次会话都是全新的白纸。会话结束，一切归零。

这在闲聊场景无所谓，但在长期项目协作中是致命伤。你的 AI 伙伴需要知道：

• 集群有哪几台机器，怎么连
• 上次备份脚本改了什么，为什么改
• 昨天排查的那个 Bug 结论是什么
• 哪些坑踩过了，不要再踩

记忆系统就是解决这个问题的。不是靠模型本身记住，而是用文件系统给 AI 造一个外部大脑。

本文分享我们如何从零设计并运行一套完整的记忆系统。这套系统已经稳定运行两周，支撑了 30+ 篇文章发布、集群运维、多平台内容分发等全部日常工作。

---

一、设计理念：分层记忆 + 自动注入

人类记忆有层次：核心身份（我是谁）→ 长期记忆（项目经验）→ 短期记忆（今天做了什么）→ 工作记忆（当前任务上下文）。

AI 的记忆系统也应该分层：

┌─────────────────────────────────────────────────┐
│            自动注入层（每次会话必读）                  │
│  SOUL.md → MEMORY.md → TOOLS.md → AGENTS.md     │
│  ~20KB，定义身份+全局状态+工具+规则                   │
├─────────────────────────────────────────────────┤
│            按需深入层（执行任务时读取）                  │
│  memory/shared/must-read.md   规则+快速查找表       │
│  memory/projects/index.md     完整项目索引           │
│  memory/projects/*/            各项目详情            │
├─────────────────────────────────────────────────┤
│             日志层（每日滚动）                         │
│  memory/YYYY-MM-DD.md         当日操作日志           │
│  memory/daily-tasks/          每日任务摘要           │
│  memory/archives/YYYY-MM/     月度归档               │
├─────────────────────────────────────────────────┤
│            结构化知识层（长期积累）                      │
│  knowledge-base.json          踩坑经验知识库          │
│  snippets.json                经验碎片              │
│  reflections.md               复盘记录              │
└─────────────────────────────────────────────────┘

核心原则：

1. 写文件，不做"心理笔记" —— 所有经验必须落盘，不能只在会话里说"我记住了"
2. 分层加载，控制 token —— 不是每次都读所有文件，按需读取
3. 多节点同步 —— 多台机器共享同一份记忆
4. 机器可读 —— JSON 格式的知识库，方便检索

---

二、自动注入层：AI 的「核心身份」

OpenClaw 支持把 workspace 下的特定文件自动注入到每次会话的 system prompt 中。这是记忆系统的根基。

2.1 SOUL.md —— 人格与行为准则

# SOUL.md - [你的 AI 名字]

[角色定义，一句话]

## 启动
读 memory/shared/must-read.md → memory/projects/index.md → MEMORY.md(主会话)

## 原则
- 自己能验证的不问用户，执行后验证结果
- 做事前先找轮子：skill 市场、GitHub、现有工具
- 不等指令，主动推进目标，有产出才行动
- 改配置前备份
- 断网操作设回退定时器，密钥不输出日志

## 审批
⚠️ 支付>100元、断网操作、不可恢复删除、公开发帖 → 先问

要点：

• SOUL.md 定义了 AI 的性格和行为边界
• 启动 部分告诉 AI 每次醒来后先读什么——这是记忆链的入口
• 审批 明确了需要人工确认的高风险操作
• 整个文件控制在 1KB 以内，不浪费 token

2.2 MEMORY.md —— 全局状态摘要

# 全局记忆 — 最后更新 2026-03-07

## 集群概览
N 节点 Tailscale 组网，OpenClaw gateway + node 架构。

| 角色 | 名称 | 用途 |
|------|------|------|
| 主节点 | Mac Mini | 统筹调度、写稿、API |
| 维护节点 | 云服务器 | Gateway、备份、cron |
| 工作节点 | 台式机 VM | 浏览器自动化、ADB |

## 项目清单
| 项目 | 状态 | 详细文档 |
|------|------|---------|
| 集群基础设施 | 运行中 | memory/projects/infra/ |
| 传播矩阵 | 运行中 | memory/projects/channel/ |

## 关键路径速查
- 项目索引: memory/projects/index.md
- 每次必读: memory/shared/must-read.md
- 账号密码: memory/shared/accounts.md（加密存储）

要点：

• 这是 AI 的全局地图——每次醒来就知道整体状态
• 包含一个路径速查表——新会话可以据此自行导航
• 更新频率：每当项目有重大变化时更新
• 大小：控制在 3-5KB

2.3 TOOLS.md —— 工具与基础设施

# TOOLS.md

## 节点分工（必须遵守）
- 维护节点：只做维护、备份、cron。禁止跑浏览器自动化
- 工作节点：浏览器自动化、ADB、CDP、Playwright
- 主节点：统筹调度、写稿、API 调用

## 连接方式
- 维护节点: ssh user@<维护节点IP>
- 工作节点: ssh user@<工作节点IP>

## 集群脚本
位置: ~/cluster/scripts/（init-node.sh, sync-config.sh, backup.sh...）

要点：

• AI 随时需要连接其他节点——连接信息必须在这里
• 节点分工很关键——防止 AI 在错误的机器上跑重活
• 脚本路径——避免 AI 每次都要 find 半天

2.4 AGENTS.md —— 行为规范

# AGENTS.md

## 🚨 认知一致性（最高优先级）
做完任何事情后，必须更新状态。不更新 = 没做过。
- 完成任务 → 更新任务状态
- 新发现/新问题 → 记录为新任务
- 踩坑/经验 → 写入知识库

## 记忆
- 日志: memory/YYYY-MM-DD.md
- 长期: MEMORY.md
- 写文件，不做"心理笔记"

要点：

• 「认知一致性」是最重要的规则——做了事但不记录，等于没做
• 明确了记忆写入的具体位置和格式

自动注入的总预算

文件	大小	内容
SOUL.md	~1KB	人格、启动流程、审批规则
MEMORY.md	~3KB	集群概览、项目状态、路径速查
TOOLS.md	~2KB	连接方式、节点分工、脚本位置
AGENTS.md	~2KB	行为规范、记忆规则
USER.md	~0.2KB	用户信息（时区、偏好）
合计	~8KB	约 2000-3000 tokens

每次会话固定消耗 ~3K tokens 用于身份注入。以 Claude Sonnet 的 input 价格（$3/M tokens），一天 50 次会话 = 150K tokens =$0.45。完全可承受。

---

三、按需深入层：项目记忆的组织

自动注入只给了 AI 一张地图。具体执行任务时，AI 需要深入读取项目详情。

3.1 目录结构

memory/
├── shared/                    # 多节点共享（自动同步）
│   ├── must-read.md          # 每次必读规则
│   ├── accounts.md           # 账号信息（加密或脱敏存储）
│   ├── knowledge-base.json   # 结构化知识库
│   └── snippets.json         # 经验碎片
├── projects/                  # 项目文档
│   ├── index.md              # 项目索引（入口）
│   ├── infra/                # 集群基础设施
│   │   ├── cluster.md
│   │   └── backup.md
│   └── channel/              # 传播矩阵
│       ├── strategy.md
│       ├── topic-pool.md
│       └── sop-publish.md
├── archives/                  # 月度归档
│   └── YYYY-MM/
├── daily-tasks/               # 每日任务
├── reflections.md             # 复盘记录
└── YYYY-MM-DD.md             # 当日日志

3.2 must-read.md —— 每次必读清单

这是一个精心维护的「快速查找表」：

# 每次必读

## 规则
1. 执行后验证，改配置前备份
2. 不改自己的 openclaw.json
3. 断网操作设回退定时器
4. 绝不让用户手动操作能自动化的事
5. 定时任务用 openclaw cron，禁止系统 crontab

## 查找
账号 → memory/shared/accounts.md
项目索引 → memory/projects/index.md
  公众号SOP → memory/projects/channel/sop-publish.md
  选题库 → memory/projects/channel/topic-pool.md
  发文数据 → memory/projects/channel/metrics.md

设计逻辑：相当于 Linux 的 /etc/motd —— 登录后第一眼看到的东西。减少一层跳转。

3.3 projects/index.md —— 项目索引

# 项目索引

## 项目一：集群基础设施 (infra/)
| 文件 | 说明 |
|------|------|
| infra/cluster.md | 集群架构、设备、网络 |
| infra/backup.md | 备份策略 |

## 项目二：渠道建设 (channel/)
| 文件 | 说明 |
|------|------|
| channel/strategy.md | 渠道总策略 |
| channel/sop-publish.md | 发文 SOP |
| channel/topic-pool.md | 选题库 |

注意：index.md 只索引，不放内容。保持它的角色清晰——目录，不是百科全书。

---

四、日志层：短期记忆的管理

4.1 当日日志

每天一个文件，格式 memory/YYYY-MM-DD.md：

# 2026-03-07 日志

## 网关代理配置调优
### 完成的操作
1. 禁用 IPv6（per-interface）
2. sing-box 路由改为全局代理模式
3. 新增国内直连规则
### 出口验证
- 国外出口: 正常（美国节点）
- 国内出口: 正常（直连）

要点：

• 每个操作记录：做了什么、为什么做、验证结果
• 不怕写多——日志是给未来的自己看的
• 复杂操作单独开文件：2026-03-07-proxy-tuning.md

4.2 月度归档

月末日志过多时，把当月日志移入 memory/archives/YYYY-MM/：

mkdir -p memory/archives/2026-02
mv memory/2026-02-*.md memory/archives/2026-02/

归档不是删除——只是从一级目录移到二级目录，需要时仍可读取。

---

五、结构化知识层：AI 的长期记忆

日志是流水账，知识库是提炼后的精华。

5.1 knowledge-base.json —— 结构化知识库

{
  "entries": [
    {
      "id": "kb-001",
      "title": "163 邮箱 IMAP 收发经验",
      "content": "163 要求 IMAP 客户端在 LOGIN 前发 ID 命令...",
      "category": "experience",
      "tags": ["邮件", "163", "踩坑"],
      "project": "infra",
      "source": "实战经验",
      "created": "2026-03-07T16:37:56Z"
    }
  ]
}

使用方式：

# 查询知识库
curl http://localhost:9800/api/kb?project=infra
curl http://localhost:9800/api/kb?q=代理

# 踩坑后写入知识库
curl -X POST http://localhost:9800/api/kb \
  -H "Content-Type: application/json" \
  -d '{"title":"某踩坑记录","content":"...","project":"infra","tags":["踩坑"]}'

为什么用 JSON 不用 Markdown：

• JSON 可以被程序精确检索（按 tag、project 过滤）
• Dashboard API 可以 CRUD
• Markdown 适合人读，JSON 适合 AI 读

5.2 snippets.json —— 经验碎片

比知识库更轻量的记录：

{
  "snippets": [
    {
      "key": "小内存服务器禁止全局更新",
      "value": "1 核 1G 内存的服务器禁止 npm update -g，会撑爆内存导致网络中断",
      "added": "2026-03-04"
    }
  ]
}

5.3 reflections.md —— 复盘记录

定期复盘，提炼模式和教训：

# 复盘思考记录

## 2026-03-04 整理复盘

### 数据洞察
- 人文类是流量引擎，阅读量是技术类的 5-10 倍
- 多图文副条阅读极低（1-3），说明用户几乎只看头条

### 思考
- 内容资产已积累，但粉丝增长才是核心瓶颈
- 多平台分发有助于技术类文章找到精准读者

---

六、多节点记忆同步

多台机器需要共享同一份记忆。我们用 rsync + OpenClaw cron 实现。

6.1 同步架构

主节点 (master) ←→ 维护节点 (hub) ←→ 工作节点 (worker)
      ↕                   ↕                     ↕
  本地 memory/shared/  本地 memory/shared/  本地 memory/shared/

维护节点是同步中枢——每 5 分钟双向同步所有节点的 memory/shared/ 目录。

6.2 同步脚本

在维护节点上创建同步脚本：

#!/bin/bash
# 记忆同步脚本 - 维护节点执行
# 每5分钟由 openclaw cron 触发

MASTER="user@<主节点IP>"
WORKER="user@<工作节点IP>"
LOCAL="/path/to/workspace/memory/shared/"
LOG="/var/log/oc-sync.log"

echo "[$(date)] 开始同步" >> $LOG

# 1. 从 master 拉取最新
rsync -avz --checksum -e ssh "$MASTER:$MASTER_PATH" "$LOCAL" >> $LOG 2>&1

# 2. 推送到 worker
rsync -avz --checksum -e ssh "$LOCAL" "$WORKER:$WORKER_PATH" >> $LOG 2>&1

# 3. 把 worker 可能产生的新内容拉回来（不覆盖已有）
rsync -avz --checksum --ignore-existing -e ssh \
  "$WORKER:$WORKER_PATH" "$LOCAL" >> $LOG 2>&1

# 4. 再推回 master
rsync -avz --checksum -e ssh "$LOCAL" "$MASTER:$MASTER_PATH" >> $LOG 2>&1

echo "[$(date)] 同步完成" >> $LOG

6.3 注册为 OpenClaw cron 任务

openclaw cron add sync-shared-files \
  --schedule "*/5 * * * *" \
  --command "/path/to/sync-shared.sh"

关键设计决策：

• 用 openclaw cron 而不是系统 crontab——统一管理，AI 可以查看和修改
• 用 --checksum 而不是时间戳——避免时区差异导致误判
• 用 --ignore-existing 拉取 worker——不覆盖 master 已有内容，防冲突
• 同步的是 memory/shared/ 不是整个 memory/——日志不需要全节点同步

---

七、Dashboard API：记忆的读写接口

我们搭建了一个简易 Dashboard（Node.js），提供 RESTful API 让 AI 以编程方式管理知识库和任务：

# 查询知识库
GET /api/kb
GET /api/kb?project=infra
GET /api/kb?q=代理

# 写入新条目
POST /api/kb
{ "title": "某踩坑记录", "content": "...", "project": "infra", "tags": ["踩坑"] }

# 查看项目任务
GET /api/tasks

# 标记完成
PUT /api/tasks/{projectId}/{taskId}
{ "done": true }

这条规则的力量在于：AI 不只是执行命令，而是主动维护自己的记忆。每次踩坑都会沉淀为知识库条目，下次遇到同类问题自动检索。

---

八、实战：新会话冷启动流程

一个全新的会话是这样启动的：

1. OpenClaw 自动注入 SOUL.md + MEMORY.md + TOOLS.md + AGENTS.md
   → AI 获得基本身份和全局状态（~3K tokens）

2. SOUL.md 中的启动指令触发：
   读 memory/shared/must-read.md
   → 获得规则清单和路径速查表

3. 如果需要执行某项目任务：
   读 memory/projects/index.md → 找到对应目录 → 读具体 .md

4. 如果需要查踩坑经验：
   GET /api/kb?q=关键词 → 搜索知识库

5. 如果需要看今天做了什么：
   读 memory/daily-tasks/YYYY-MM-DD.md → 获得当日上下文

整个流程：自动注入 → 规则校准 → 按需深入 → 开始工作。

从全新会话到完全恢复上下文，总 token 消耗约 5K-8K。不到 $0.03。

---

九、踩过的坑与最佳实践

❌ 坑 1：MEMORY.md 越写越长

早期把所有经验都堆在 MEMORY.md 里，很快膨胀到 20KB+。每次自动注入就吃掉 5K tokens。

解法：MEMORY.md 只放「摘要 + 路径」，详细内容下沉到子目录。

❌ 坑 2：AI 说"我记住了"但没写文件

AI 在会话中信誓旦旦说"已记录"，但实际没有写入任何文件。下次会话全忘。

解法：在 AGENTS.md 中明确写 写文件，不做"心理笔记"。这句话效果非常显著。

❌ 坑 3：多节点修改同一文件导致覆盖

主节点和工作节点同时修改同一文件，同步后一方被覆盖。

解法：

• memory/shared/ 目录约定只有主节点负责修改
• 其他节点可以新增文件，但不修改已有文件
• rsync 用 --ignore-existing 防止覆盖

❌ 坑 4：日志文件堆积

memory/ 目录下几十个日志文件，AI ls 后不知道读哪个。

解法：日志按日期命名，定期归档到 archives/YYYY-MM/。在 must-read.md 中只索引活跃文件。

✅ 最佳实践 1：启动链

在 SOUL.md 中明确列出启动时的文件读取顺序：

## 启动
读 memory/shared/must-read.md → memory/projects/index.md → MEMORY.md

比依赖 AI 自己决定读什么可靠得多。

✅ 最佳实践 2：路径速查表

在 must-read.md 中维护路径索引，AI 不需要遍历目录树。

✅ 最佳实践 3：知识库用 JSON

JSON 比散落的 Markdown 更适合机器检索。支持按 tag、project 过滤，AI 可以用 jq 查询。

✅ 最佳实践 4：高风险操作的安全网

AGENTS.md 要求高风险操作先审批。这不是信任问题，是记忆系统的安全阀——AI 记错了上下文时，审批流程可以拦住。

---

十、实际效果

运行两周后的对比：

指标	之前（无记忆）	之后（有记忆）
新会话恢复上下文	需要人工告知背景	自动恢复，0 人工干预
重复犯错	经常踩同一个坑	知识库自动命中
跨节点协作	各自为政	共享记忆，统一认知
项目交接	需要大量口头说明	读 index.md 即可上手
token 消耗	N/A	每次 ~3K 自动注入

最显著的变化：AI 开始有了「连续性」。它不再是每次见面都要重新介绍自己的陌生人，而是一个记得你昨天做了什么、知道项目全局的协作伙伴。

---

十一、从零搭建的完整步骤

如果你也想给自己的 OpenClaw 搭建记忆系统：

Step 1：创建目录结构

cd ~/.openclaw/workspace
mkdir -p memory/shared memory/projects memory/archives memory/daily-tasks

Step 2：创建 SOUL.md

cat > SOUL.md << 'EOF'
# SOUL.md - [你的AI名字]

[角色定义，一句话]

## 启动
读 memory/shared/must-read.md → MEMORY.md

## 原则
- 自己能验证的不问用户
- 做事前先找轮子
- 改配置前备份
- 写文件，不做"心理笔记"

## 审批
⚠️ 支付>100元、不可恢复删除 → 先问
EOF

Step 3：创建 MEMORY.md

cat > MEMORY.md << 'EOF'
# 全局记忆

## 环境
[写你的机器信息]

## 项目
[列出当前在做的项目]

## 关键路径
- 项目索引: memory/projects/index.md
EOF

Step 4：创建 AGENTS.md

cat > AGENTS.md << 'EOF'
# AGENTS.md

## 记忆规则
- 日志: memory/YYYY-MM-DD.md
- 长期: MEMORY.md
- 踩坑: memory/shared/knowledge-base.json
- 写文件，不做"心理笔记"
EOF

Step 5：创建知识库

echo '{"entries":[]}' > memory/shared/knowledge-base.json
echo '{"snippets":[]}' > memory/shared/snippets.json

Step 6：验证

开一个新会话，问 AI：「你知道我们在做什么项目吗？」

如果它能回答出来，记忆系统就生效了。

---

十二、进阶方向

1. 向量检索：知识库条目做 embedding，语义搜索代替关键词匹配
2. 自动摘要：日志写满一周后自动生成周报
3. 记忆衰减：30 天未访问的条目自动归档
4. 跨用户记忆：多人共用集群时的记忆隔离与共享
5. 记忆可视化：Dashboard 展示哪些知识最常被访问

但在当前阶段，文件系统 + JSON + rsync 已经足够好。不要过度设计——先跑起来，遇到瓶颈再迭代。

---

总结

AI 记忆系统的核心不是什么高深技术，就是文件系统 + 约定 + 纪律：

层次	载体	更新频率	作用
身份	SOUL.md	很少改	人格、原则、审批规则
全局状态	MEMORY.md	项目变化时	全局地图、路径速查
工具	TOOLS.md	基础设施变化时	连接方式、节点分工
规范	AGENTS.md	发现新问题时	行为规范、记忆写入规则
项���详情	memory/projects/	持续更新	具体项目的深度文档
日志	memory/YYYY-MM-DD.md	每天	操作记录、验证结果
知识库	knowledge-base.json	踩坑时	结构化经验，可检索
复盘	reflections.md	定期	模式识别、策略调整

记住这句话：写文件，不做"心理笔记"。

这是整个记忆系统最重要的一条规则。

---

本文基于 OpenClaw 集群实际运行经验撰写。记忆系统已稳定运行两周，支撑日均 3 篇内容发布 + 集群运维 + 多平台分发。

AI有招，让 AI 有章可循。