heartbeat-memory

🌐 ClawHub:​ clawhub.ai/JustZeroX/heartbeat-memory

💻 GitHub:​ github.com/JustZeroX/skill-heartbeat-memory

Heartbeat 自动记忆保存 - 支持 Heartbeat 自动触发 和 手动触发 两种方式。自动检查新 sessions，使用 OpenClaw 主 LLM 生成/更新 daily 笔记，并定期提炼 MEMORY.md。

特点：​

• ✅ 双模式支持 - Heartbeat 自动触发 + 主 Agent 中手动调用

• ✅ 文件系统扫描 - 支持备份已删除的 sessions

• ✅ 智能日期检测 - 自动检测最早 session 日期

• ✅ 配置自动同步 - HEARTBEAT.md 自动更新

推荐安装位置：​ ~/.openclaw/skills/heartbeat-memory/（全局目录，所有工作区共享）

💡 路径说明：​ Skill 安装路径是全局的。运行时所有文件操作都相对于当前工作区根目录（./）。OpenClaw 在唤醒 Agent 时会自动将当前目录切换到该 Agent 的专属工作区，因此 ./ 始终指向正确的工作区。

🚀 快速开始

步骤 1：安装

方式 1：Via ClawHub（推荐 ⭐）​

# 1. 安装 ClawHub（如未安装）
npm install -g clawhub

# 2. 安装 heartbeat-memory
clawhub install heartbeat-memory

方式 2：Via GitHub

git clone https://github.com/JustZeroX/skill-heartbeat-memory.git ~/.openclaw/skills/heartbeat-memory

步骤 2：配置 Heartbeat

​⚠️ 重要：Heartbeat 默认是关闭的！​

方式 1：使用 CLI 命令（推荐）​

# 查看当前配置
openclaw config get agents.defaults.heartbeat

# 如未启用，编辑 openclaw.json 添加："agents": { "defaults": { "heartbeat": { "every": "30m" } } }

# 重启 Gateway
openclaw gateway restart

方式 2：手动编辑 openclaw.json

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m"
      }
    }
  }
}

验证是否生效：​

openclaw config get agents.defaults.heartbeat
# 输出：{"every": "30m"} 表示已启用

步骤 3：使用

方式 1：自动触发（推荐 ⭐）​

安装并启用 Heartbeat 后，Skill 会每 30 分钟自动执行，无需手动干预。

方式 2：手动触发

在聊天中直接发送：

执行 heartbeat-memory

AI 会在主会话中直接执行，无需额外配置。

✨ 核心功能

1. 自动记忆保存

• Heartbeat 触发：每 30 分钟自动执行

• 智能扫描：检测新的 sessions + 活跃 sessions（有新内容的已处理 session）

• 增量更新：对活跃 session 生成增量摘要，避免重复处理

• 智能消息处理：动态调整处理数量（8-20 条），优先用户消息（70%）

• LLM 提炼：生成结构化 Daily 笔记

• 状态追踪：记录每个 session 的最后处理位置，避免重复处理

2. Daily 笔记生成

输出位置：​ ./memory/daily/YYYY-MM-DD.md

💡 路径说明：​ 所有路径都是相对于当前工作区的根目录（./）。OpenClaw 运行时会自动切换 CWD 到当前 Agent 的工作区，因此无需手动指定工作区路径。

内容包含：​

• 当日总结（会话数、活跃度）

• 会话详情（标题、摘要、标签）

• 关键决策/发现

3. MEMORY.md 定期提炼

• 默认频率：每周日 20:00

• 自动提炼：从 Daily 笔记提取长期记忆

• 可配置：支持自定义频率和时间

4. 自动初始化

首次运行时会自动：

1. ✅ 创建配置文件

2. ✅ 初始化状态文件

3. ✅ 创建必要目录

4. ✅ 自动检测 processSessionsAfter 日期

5. ✅ 自动同步 HEARTBEAT.md 配置状态

📝 HEARTBEAT.md 自动同步

Skill 会自动维护 HEARTBEAT.md 中的"记忆自动保存"部分：​

• ✅ 自动检测配置变更（通过 hash 对比）

• ✅ 仅配置变更时更新（避免重复写入）

• ✅ 动态路径展示（自动适配多 workspace）

• ✅ 保留用户自定义内容（天气检查等不受影响）

示例：​

# HEARTBEAT.md - 心跳任务

## 🧠 记忆自动保存

\x3C!-- 此部分由 heartbeat-memory skill 自动维护，请勿手动修改 -->

- [x] 启用 heartbeat-memory Skill

- [x] 工作区：workspace（示例值，实际显示当前工作区名称）

- [x] 配置：处理 2026-03-06 之后的 sessions

- [x] 配置：每次最多处理 20 个 sessions

- [x] 配置：超时时间 1000 秒

**执行方式：​** Heartbeat 触发时自动执行 heartbeat-memory Skill

**配置文件：​** `./memory/heartbeat-memory-config.json`

**输出位置：​**

- Daily 笔记：`./memory/daily/YYYY-MM-DD.md`

- 长期记忆：`./MEMORY.md`

- 状态文件：`./memory/heartbeat-state.json`

⚙️ 核心配置

单工作区模式

编辑 ./memory/heartbeat-memory-config.json：

多工作区模式

每个工作区有独立的配置文件：​

💡 重要说明：​ 由于 OpenClaw 在运行时会自动将当前工作目录（CWD）切换到对应 Agent 的工作区，因此所有工作区的配置文件路径写法完全相同，均为 ./memory/heartbeat-memory-config.json。Skill 会自动识别当前所属工作区，无需手动指定。

自动检测：​ Skill 会自动识别当前所属工作区，无需手动指定。

详见：​ references/config.md

完整配置说明：​ 详见 references/config.md

📋 配置示例

基础配置（默认）

{
  "memorySave": {
    "enabled": true
  }
}

首次运行（避免大量历史）

💡 提示：​ 首次运行时，Skill 会自动检测最早的 session 日期或 workspace 创建日期，并自动保存到配置文件。

{
  "memorySave": {
    "enabled": true,
    "processSessionsAfter": "2026-03-01T00:00:00Z",
    "maxSessionsPerRun": 20
  }
}

大量 sessions（分批处理）

{
  "memorySave": {
    "enabled": true,
    "maxSessionsPerRun": 30,
    "timeoutSeconds": 1500,
    "batchSize": 5
  }
}

更多示例：​ 详见 references/config.md

📊 处理策略

处理流程：​

Heartbeat 触发
    ↓
sessions_list 获取会话列表
    ↓
sessions_history 获取消息内容
    ↓
sessions_spawn 启动 subagent 进行 LLM 提炼
    ↓
写入 Daily 笔记
    ↓
检查是否需要提炼 MEMORY.md
    ↓
发送完成通知

❓ 常见问题

Q: 如何手动触发？

A: 在聊天中发送："执行 heartbeat-memory"

Q: 为什么不能用 require 调用？

A: run() 依赖工具注入（sessions_list 等），只有 Heartbeat 自动触发或主 Agent 会话中工具才可用。

Q: 可以修改提炼频率吗？

A: 可以，编辑配置文件：

{
  "refineSchedule": {
    "type": "weekly",
    "dayOfWeek": "sunday",
    "time": "20:00"
  }
}

Q: 如何处理大量 sessions？

A: 自动分批处理，每次最多 50 个，剩余下次继续。也可手动限制：

{
  "maxSessionsPerRun": 20
}

Q: 通知未发送怎么办？

A: 检查 notifyTarget 配置，或删除该字段让 Skill 自动获取当前用户。

更多问题：​ 详见 references/troubleshooting.md

🔧 故障排查速查

Skill 不执行

# 1. 检查 Heartbeat 配置
openclaw config get agents.defaults.heartbeat
# 输出 {"every": "30m"} 表示已启用

# 2. 如未启用，编辑 openclaw.json 添加：
# "agents": { "defaults": { "heartbeat": { "every": "30m" } } }

# 3. 重启 Gateway
openclaw gateway restart

# 4. 重建配置文件（相对于当前工作区）
rm ./memory/heartbeat-memory-config.json

💡 路径说明：​ 故障排查命令中的路径都是相对于当前工作区（./）。在工作区目录下执行即可，无需指定完整路径。

HEARTBEAT.md 未更新

# 删除 configHash（强制重新同步）
# 编辑 heartbeat-state.json，删除 "configHash" 字段

处理速度慢

{
  "memorySave": {
    "maxSessionsPerRun": 20,
    "timeoutSeconds": 1500
  }
}

完整故障排查：​ 详见 references/troubleshooting.md

📖 参考文档

🎯 最佳实践

首次运行

1. 不设置 processSessionsAfter（自动检测）
2. 设置 maxSessionsPerRun: 20
3. 观察执行日志

日常使用

1. 保持默认配置
2. 定期查看 Daily 笔记
3. 根据需要调整提炼频率

性能优化

• 大量 sessions：maxSessionsPerRun: 30, timeoutSeconds: 1500
• 频繁触发：禁用 OK 通知（在 openclaw.json 中配置）
• 内存优化：batchSize: 3, maxSessionsPerRun: 10

最后更新：2026-03-27