Proactive Memory Agent 🧠⚡
The ultimate memory optimization system for OpenClaw agents.
OpenClaw 智能体终极记忆优化系统。
Combines the best of three worlds:
- - 🦞 Proactive Agent — WAL protocol, Working Buffer, learning system
- 📊 Context Budgeting — Strict 10/40/20/20 partitioning
- 🗂️ Memory Tiering — Automatic HOT/WARM/COLD archiving
Result: 60-70% context reduction + complete learning retention + zero maintenance
效果：降低60-70%上下文占用 + 完整保留学习记录 + 零维护成本
快速开始 / Quick Start
中文简介
Proactive Memory Agent 是一个专为 OpenClaw 设计的记忆优化系统，解决长会话中的上下文爆炸问题。
核心特性：
- - 🔥 WAL 预写协议 — 关键决策先写后回，确保信息不丢失
- ⚠️ 工作缓冲区 — 危险区(>60%)自动记录所有对话
- 📊 上下文预算 — 严格 10/40/20/20 分区控制
- 🗂️ 三级记忆架构 — HOT→WARM→COLD 自动归档
- 📝 学习记录系统 — 自动记录错误、纠正和最佳实践
适用场景：
- - 长会话 (>50条消息)
- 复杂任务 (多步骤、多文件)
- 高频交互 (需要记住用户偏好)
- 成本控制 (降低token消耗)
预期效果：
- - Context 占用降低 60-70%
- Token 消耗降低 50-60%
- 信息丢失风险 几乎为零
Memory Architecture / 记忆架构
CODEBLOCK0
The Four Protocols / 四大协议
1️⃣ WAL Protocol (Write-Ahead Logging) / 预写协议
Law: Context is a BUFFER, not storage. Write first, respond second.
法则： 上下文是缓冲，不是存储。先写再回。
SCAN every message for:
扫描每条消息中的：
- - ✏️ Corrections — "It's X, not Y" / "Actually..." / 纠正
- 📍 Proper nouns — Names, places, products / 专有名词
- 🎨 Preferences — Colors, styles, approaches / 偏好
- 📋 Decisions — "Let's do X" / "Go with Y" / 决策
- 🔢 Specific values — Numbers, dates, IDs, URLs / 具体数值
The Protocol:
- 1. STOP — Do not start composing your response / 停止，不要开始回复
- WRITE — Update SESSION-STATE.md with the detail / 写入 SESSION-STATE.md
- THEN — Respond to your human / 然后回复用户
2️⃣ Working Buffer Protocol / 工作缓冲区协议
Purpose: Capture EVERY exchange in the danger zone (>60% context).
目的： 在危险区(>60%上下文)记录每一条消息。
中文说明：
当上下文使用率超过 60% 时，系统自动启用工作缓冲区，记录每一条对话。即使发生压缩，也能从缓冲区恢复。
How:
- 1. At 60% context: Clear old buffer, start fresh
- Every message after 60%: Append to INLINECODE0
- After compaction: Read buffer FIRST, extract important context
- Leave buffer as-is until next 60% threshold
3️⃣ Context Budgeting (10/40/20/20) / 上下文预算分区
Strict partitioning / 严格分区：
| Zone | % | Content | File | 中文说明 |
|---|
| Objective | 10% | Core task, active constraints | SESSION-STATE.md | 核心任务 |
| Short-term |
40% | Recent 5-10 turns raw dialogue | Working Buffer | 短期对话 |
|
Decision Log | 20% | Summarized outcomes | .learnings/*.md | 决策日志 |
|
Background | 20% | High-relevance snippets | MEMORY.md | 背景知识 |
Rule: When any zone exceeds quota, oldest content moves to lower tier.
规则： 任何分区超出配额时，最旧内容移至下一层级。
4️⃣ Memory Tiering (HOT → WARM → COLD) / 记忆分层归档
Automatic lifecycle / 自动生命周期：
CODEBLOCK1
| Tier | Location | Update Frequency | Retention | 中文 |
|---|
| HOT | SESSION-STATE.md | Every message | Current task only | 当前任务 |
| WARM |
.learnings/ | When learning occurs | Until promoted | 学习记录 |
| COLD | MEMORY.md | Weekly archival | Permanent | 长期存档 |
使用脚本 / Scripts
快速设置 / Quick Setup
CODEBLOCK2
日常使用 / Daily Operations
# 检测当前状态 / Check current status
~/.openclaw/workspace/skills/proactive-memory-agent/scripts/detect.sh
# 搜索记忆 / Search memories
~/.openclaw/workspace/skills/proactive-memory-agent/scripts/search.sh "关键词"
# 执行记忆分层归档 / Run memory tiering
~/.openclaw/workspace/skills/proactive-memory-agent/scripts/tiering.sh
# 创建预压缩检查点 / Create pre-compaction checkpoint
~/.openclaw/workspace/skills/proactive-memory-agent/scripts/checkpoint.sh
学习记录系统 / Learning System (.learnings/)
何时记录 / When to Record
| 场景 / Situation | 记录位置 / Record To | 类别 / Category |
|---|
| 命令失败 / Command fails | ERRORS.md | error |
| 用户纠正 / User corrects |
LEARNINGS.md | correction |
| 缺失功能 / Missing feature | FEATURE
REQUESTS.md | featurerequest |
| 知识过时 / Knowledge outdated | LEARNINGS.md | knowledge_gap |
| 更好方法 / Better approach | LEARNINGS.md | best_practice |
记录格式 / Format
CODEBLOCK4
提升路径 / Promotion Path
CODEBLOCK5
心跳集成 / Heartbeat Integration
Add to HEARTBEAT.md:
添加到心跳文件：
CODEBLOCK6
核心原则 / Key Principles
- 1. Write before respond — WAL is non-negotiable / 先写再回，WAL不可妥协
- Buffer the danger zone — >60% = automatic logging / 缓冲危险区，>60%自动记录
- Strict budgeting — 10/40/20/20, no exceptions / 严格预算，10/40/20/20无例外
- Auto-tiering — HOT→WARM→COLD without manual effort / 自动分层，无需手动
- Promote aggressively — Recurring patterns become permanent / 积极提升，重复模式永久化
- Never lose context — Working Buffer + Compaction Recovery / 永不丢失，缓冲+恢复
预期效果 / Expected Results
| Metric / 指标 | Before / 之前 | After / 之后 | Improvement / 改进 |
|---|
| Context usage / 上下文占用 | 100% | 30-40% | 60-70% reduction |
| Token consumption / Token消耗 |
Baseline / 基准 | -50-60% |
Major savings |
| Maintenance / 维护成本 | High / 高 | Minimal / 极低 |
Auto-tiering |
| Information loss / 信息丢失 | Risk / 有风险 | Zero / 零 |
Buffer protection |
Changelog / 更新日志
v1.0.1 (2026-03-24)
- - Added Chinese documentation / 添加中文文档
- Improved README with bilingual support / 改进双语支持
- Fixed minor formatting issues / 修复格式问题
v1.0.0 (2026-03-24)
- - Initial release / 初始版本
- Integrated: proactive-agent + context-budgeting + memory-tiering / 整合三大技能
- 5 management scripts included / 包含5个管理脚本
- Full documentation in SKILL.md / 完整文档
License / 许可证
MIT License — Free to use, modify, distribute.
MIT 许可证 — 自由使用、修改、分发。
Part of the Hal Stack 🦞 + Self-Improvement Integration
Integrated by @silaszhu技能名称: proactive-memory-agent
详细描述:
Proactive Memory Agent 🧠⚡
OpenClaw 智能体终极记忆优化系统。
融合三大优势：
- - 🦞 主动智能体 — WAL协议、工作缓冲区、学习系统
- 📊 上下文预算 — 严格的10/40/20/20分区
- 🗂️ 记忆分层 — 自动HOT/WARM/COLD归档
效果：降低60-70%上下文占用 + 完整保留学习记录 + 零维护成本
快速开始 / Quick Start
中文简介
Proactive Memory Agent 是一个专为 OpenClaw 设计的记忆优化系统，解决长会话中的上下文爆炸问题。
核心特性：
- - 🔥 WAL 预写协议 — 关键决策先写后回，确保信息不丢失
- ⚠️ 工作缓冲区 — 危险区(>60%)自动记录所有对话
- 📊 上下文预算 — 严格 10/40/20/20 分区控制
- 🗂️ 三级记忆架构 — HOT→WARM→COLD 自动归档
- 📝 学习记录系统 — 自动记录错误、纠正和最佳实践
适用场景：
- - 长会话 (>50条消息)
- 复杂任务 (多步骤、多文件)
- 高频交互 (需要记住用户偏好)
- 成本控制 (降低token消耗)
预期效果：
- - Context 占用降低 60-70%
- Token 消耗降低 50-60%
- 信息丢失风险 几乎为零
Memory Architecture / 记忆架构
workspace/
├── SESSION-STATE.md # 🔥 HOT: 当前任务 (WAL目标)
├── .learnings/ # 🌡️ WARM: 学习记录
│ ├── ERRORS.md — 错误记录
│ ├── LEARNINGS.md — 学习/纠正记录
│ └── FEATURE_REQUESTS.md — 功能请求记录
├── MEMORY.md # ❄️ COLD: 长期归档
├── memory/
│ ├── hot/HOT_MEMORY.md # 快速恢复检查点
│ ├── warm/ # 稳定偏好/配置
│ ├── cold/ # 长期归档
│ └── working-buffer.md # ⚠️ 危险区日志
└── AGENTS.md/SOUL.md/TOOLS.md — 只读参考
四大协议 / The Four Protocols
1️⃣ WAL协议 (预写日志) / WAL Protocol (Write-Ahead Logging)
法则： 上下文是缓冲，不是存储。先写再回。
Law: Context is a BUFFER, not storage. Write first, respond second.
扫描每条消息中的：
SCAN every message for:
- - ✏️ 纠正 — 是X，不是Y / 实际上... / Corrections
- 📍 专有名词 — 名称、地点、产品 / Proper nouns
- 🎨 偏好 — 颜色、风格、方法 / Preferences
- 📋 决策 — 我们做X / 采用Y / Decisions
- 🔢 具体数值 — 数字、日期、ID、URL / Specific values
协议：
- 1. 停止 — 不要开始撰写回复 / STOP
- 写入 — 将细节更新到 SESSION-STATE.md / WRITE
- 然后 — 回复用户 / THEN
2️⃣ 工作缓冲区协议 / Working Buffer Protocol
目的： 在危险区(>60%上下文)捕获每一条交流。
Purpose: Capture EVERY exchange in the danger zone (>60% context).
中文说明：
当上下文使用率超过 60% 时，系统自动启用工作缓冲区，记录每一条对话。即使发生压缩，也能从缓冲区恢复。
方法：
- 1. 在 60%上下文时：清除旧缓冲区，重新开始
- 60%之后的每条消息：追加到 memory/working-buffer.md
- 压缩后：先读取缓冲区，提取重要上下文
- 保持缓冲区原样，直到下一个60%阈值
3️⃣ 上下文预算 (10/40/20/20) / Context Budgeting (10/40/20/20)
严格分区 / Strict partitioning：
| 区域 | % | 内容 | 文件 | 中文说明 |
|---|
| 目标 | 10% | 核心任务、活跃约束 | SESSION-STATE.md | 核心任务 |
| 短期 |
40% | 最近5-10轮原始对话 | Working Buffer | 短期对话 |
|
决策日志 | 20% | 总结结果 | .learnings/*.md | 决策日志 |
|
背景 | 20% | 高相关性片段 | MEMORY.md | 背景知识 |
规则： 任何分区超出配额时，最旧内容移至下一层级。
Rule: When any zone exceeds quota, oldest content moves to lower tier.
4️⃣ 记忆分层 (HOT → WARM → COLD) / Memory Tiering (HOT → WARM → COLD)
自动生命周期 / Automatic lifecycle：
🔥 HOT (当前会话) Current session
↓ (任务完成) Task complete
🌡️ WARM (重复使用) Recurring use
↓ (30天旧/已提升) 30 days old / promoted
❄️ COLD (归档) Archive
| 层级 | 位置 | 更新频率 | 保留 | 中文 |
|---|
| HOT | SESSION-STATE.md | 每条消息 | 仅当前任务 | 当前任务 |
| WARM |
.learnings/ | 学习发生时 | 直到提升 | 学习记录 |
| COLD | MEMORY.md | 每周归档 | 永久 | 长期存档 |
使用脚本 / Scripts
快速设置 / Quick Setup
bash
~/.openclaw/workspace/skills/proactive-memory-agent/scripts/init.sh
日常使用 / Daily Operations
bash
检测当前状态 / Check current status
~/.openclaw/workspace/skills/proactive-memory-agent/scripts/detect.sh
搜索记忆 / Search memories
~/.openclaw/workspace/skills/proactive-memory-agent/scripts/search.sh 关键词
执行记忆分层归档 / Run memory tiering
~/.openclaw/workspace/skills/proactive-memory-agent/scripts/tiering.sh
创建预压缩检查点 / Create pre-compaction checkpoint
~/.openclaw/workspace/skills/proactive-memory-agent/scripts/checkpoint.sh
学习记录系统 / Learning System (.learnings/)
何时记录 / When to Record
| 场景 / Situation | 记录位置 / Record To | 类别 / Category |
|---|
| 命令失败 / Command fails | ERRORS.md | error |
| 用户纠正 / User corrects |
LEARNINGS.md | correction |
| 缺失功能 / Missing feature | FEATURE
REQUESTS.md | featurerequest |
| 知识过时 / Knowledge outdated | LEARNINGS.md | knowledge_gap |
| 更好方法 / Better approach | LEARNINGS.md | best_practice |
记录格式 / Format
markdown
[LRN-YYYYMMDD-XXX] category
Logged: ISO-8601 timestamp
Priority: low | medium | high | critical
Status: pending | in_progress | resolved | promoted
Summary / 摘要
一句话描述学到了什么
Details / 详情
What happened, what was wrong, correct approach
发生了什么，哪里错了，正确做法
Suggested Action / 建议操作
Specific fix or improvement
具体的修复或改进建议
提升路径 / Promotion Path
Learning in .learnings/ 在学习记录中
↓
IF recurring (3+ times) OR broadly applicable 如果重复(3+次)或广泛适用
↓
Promote to / 提升到:
├─ Behavioral patterns → SOUL.md 行为模式
├─ Workflow improvements → AGENTS.md 工作流改进
└─ Tool gotchas → TOOLS.md 工具技巧
心跳集成 / Heartbeat Integration
Add to HEARTBEAT.md:
添加到心跳文件：
markdown
Memory Management / 记忆管理 (每30分钟)
- - [ ] Run detect.sh — 检查context使用率
- [ ] If >80%: Create checkpoint with checkpoint.sh / 创建检查点
- [ ] If >70%: Run tiering.sh to archive old content / 归档旧内容
- [ ] Review .learnings/ for pending items / 检查待处理项
核心原则 / Key Principles
- 1. Write before respond — WAL
