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

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

存储结构

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

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

记忆粒度

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

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

生命周期

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

正向衰减（organize.py 三步）

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

组件

晋升机制

晋升条件（满足任一）

晋升后处理

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

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

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

逐层检索协议

触发条件

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

检索顺序

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

检索方法

# 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 个时缩小重试。

命中处理

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

未命中处理

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

> 1. 从未被记录过

> 2. 已物理删除（进入 forgotten 后 30 天无调用自动清理）

> 3. 关键词不对，换组词再试

引用计数联动

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

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

搜索决策树（速查）

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

注意要点

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