Context Clear

Memory management system with automated tiered storage (hot/warm/gist/forgotten), time-decay organization, promotion engine, layer-search protocol, and session-injection plugin. Use when managing conversation memory, running /refresh, organizing checkpoint files, retrieving past memories, promoting important content to long-term storage, or cleaning up stale context.

Context Clear — 记忆整理与上下文清空

纯文件系统的 SRS（间隔重复）记忆管理方案 + OpenClaw 插件。核心目标：在 token 成本和信息保留之间做自动平衡。

存储结构

text

~/.openclaw/memory_fs/
├── hot/       (< 3h)            原始完整    ← 自动注入 session
├── warm/      (3h~7d)           原始完整
├── gist/      (7d~30d)          摘要+标签    ← warm/ 保留同名原始文件
└── forgotten/ (≥14d 无检索)      等待物理删除

~/.openclaw/refcount.json    ← 引用计数 + 检索记录

记忆粒度

各层能提供的信息量不同 — 检索时据此判断结果的可信度：

层	时间窗	粒度	内容形式	检索置信度
hot/	< 3h	🔴 原始完整	对话原文、工具输出、checkpoint 全文	高 — 可精确引用原文
warm/	3h~7d	🟠 原始完整	同上，未被压缩	高 — 同 hot
gist/	7d~30d	🟡 摘要标签	#标题\n标签: xxx\n摘要	中 — 定位话题，细节可回 warm/ 看同名原件
forgotten/	≥14d 无检索	🔵 遗忘中	原始/摘要格式	极低 — 即将物理删除

设计原则： 记忆质感随时间自然衰减。近 3h 的事可精确复述，3h7d 可回顾细节，7d30d 仅能回忆话题方向。warm/ 始终保留原始文件（gist 是它的摘要副本），检索命中 gist 时可按文件名回 warm/ 读原文。

---

生命周期

text

创建
  │
  ├─3h→ hot/     (原始完整，自动注入 session)
  │
  ├─7d→ warm/    (原始完整)
  │     │
  │     ├── copy → gist/ (摘要副本，keep warm 原件)
  │     │
  │     └── 14d 无检索 → forgotten/
  │                     │
  │                     └── 30d → 物理删除
  │
  检索命中（任一层）
       │
       └── 轮动回 hot/ (forgotten 回 warm/)

正向衰减（organize.py 三步）

步骤	职责	判据
1. mtime 分层	hot→warm（move），warm→gist（copy，warm 保留原件）	文件 mtime
2. 遗忘检查	warm/gist→forgotten	refcount 最后检索时间距今 >14d
3. 清理	forgotten 中 >30d → 物理删除	mtime，跳过 user_marked

逆向轮动（检索命中 → 回热层）

来源	动作	原因
hot/	不动	已在最热层
warm/	mv 回 hot/ + touch	被回查 = 仍相关
gist/	mv 摘要文件回 hot/；warm 原件同回 hot/	完整信息双份带回
forgotten/	mv 回 warm/ + 标记 user_marked	被检索 = 仍需要，从 warm 重新走衰减

---

组件

组件	功能
organize.py	三步职责：mtime 分层（warm→gist copy）→ 14d 遗忘检查 → forgotten 清理
promote.py	读取 refcount.json，筛选晋升候选，输出 promote_report.md
插件 /refresh	触发 organize → promote → session reset

晋升机制

晋升条件（满足任一）

条件	门槛
7天内引用	≥ 3 次
14天内引用	≥ 5 次
总引用	≥ 8 次
用户标记	user_marked = true

晋升后处理

子 session 读取 promote_report.md 分类搬运：

• Skill 类 → skills/<skill>/docs/retrospect.md
• 偏好/事实类 → MEMORY.md
• 需判定 → 留待人工分类

晋升后从 refcount 标记 promoted: true，不再重复提名。

---

逐层检索协议

触发条件

当前 session 上下文找不到答案时启动：

信号	表现
用户提之前讨论过的话题	"我们上次是不是讨论过 XXX"
用户问之前达成的共识	"XX 的结论是什么"
自我感知	我注意到信息不在当前上下文中
用户明示	"之前说过""之前写过"

检索顺序

text

hot/ → warm/ → gist/ → forgotten/    找到即停

检索方法

bash

# hot/warm — 原始内容，关键词 grep
grep -ril "关键词1\|关键词2" ~/.openclaw/memory_fs/hot/
grep -ril "关键词1\|关键词2" ~/.openclaw/memory_fs/warm/

# gist — 先按标签再按关键词
grep -ril "tag1\|tag2" ~/.openclaw/memory_fs/gist/
grep -ril "关键词" ~/.openclaw/memory_fs/gist/

# forgotten — 最低优先级
grep -ril "关键词" ~/.openclaw/memory_fs/forgotten/

关键词：从用户问题+上下文提炼 2-5 个核心词。匹配 >3 个时缩小重试。

命中处理

步骤	动作
1	读入匹配文件内容
2	轮动：按来源层执行逆向轮动（见上表）
3	更新 refcount：total +1，timestamps 追加时间戳
4	gist 层命中但摘要不够 → 去 warm/ 读同名原始文件（原件完好 ✓）

匹配 >3 个文件 → 缩小关键词重试，不一次性读入。

未命中处理

memory_fs 中未找到关于 'XXX' 的记录。可能原因：

1. 从未被记录过
2. 已物理删除（进入 forgotten 后 30 天无调用自动清理）
3. 关键词不对，换组词再试

引用计数联动

每次命中递增 refcount → 频繁被回查的信息自然达到晋升门槛 → 自动存入 MEMORY.md。

json

{
  "warm/my-checkpoint.md": {
    "total": 5,
    "7d": 3,
    "timestamps": [1748073600, 1748160000],
    "user_marked": false,
    "summarized": false,
    "created": 1748000000
  }
}

搜索决策树（速查）

text

当前上下文找不到信息？
  → hot/ → 命中？→ 读入，不轮动
  → warm/ → 命中？→ 读入，mv 回 hot/
  → gist/ → 命中？
     → 摘要够？→ 直接读，摘要文件 mv 回 hot/
     → 不够？→ warm/ 读同名原始文件，双份回 hot/
  → forgotten/ → 命中？
     → mv 回 warm/ + 标记 user_marked，提醒用户已找回历史记忆
  → 都没找到 → 如实告知

---

注意要点

• 始终优先搜 hot/（最近、最相关）
• 先读文件名确认相关，再读文件内容
• gist 摘要不够用时，warm/ 有同名原始文件可读 — organize.py 已从 move 改为 copy
• forgotten 命中后轮动回 warm/，从 warm 重新走衰减周期