Memory Optimization System

Operational Steps

1. 确认输入参数完整
2. 执行核心操作（参考本目录下的 scripts/ 或 references/）
3. 验证输出符合契约
4. 保存结果并报告

Pitfalls

-

-

Verification

-

-

-

-

1. 2. 3.

注意: 本技能是记忆管理的唯一入口。memory-enhancement 已合并至此。

记忆系统全面优化

记非日记，长养为要。散则聚之，独则连之。

IO_CONTRACT

• input: context_size: int — 当前会话上下文大小（bytes/lines）
• input: memory_entries: list[dict] — memory + fact_store 快照
• input: consolidation_trigger: str — 触发类型（qc_scan / cron_consolidation / context_overflow / session_end）
• output: optimization_report: dict — 优化结果（offloaded: list, merged: list, cleaned: list）
• output: context_refs: list[str] — 卸载的 context_refs/*.md 路径
• output: metrics: dict — 优化前后内存使用对比

  对应原则：P2（机械原子暴露输入输出规范）

已部署组件

1. 上下文卸载（Mermaid压缩）

触发条件

当任何工具输出超过 10KB 或 50行 时：

长输出 → [自动检测] ├── 保存原文到 ~/.hermes/context_refs/{hash}.md └── 替换为 Mermaid 摘要（保持上下文轻量）

实际工作流

1. 当检测到长输出时，自动执行: mkdir -p ~/.hermes/context_refs/
2. 保存原文（terminal 的输出被管道捕获）
3. 在回复中只用摘要 + 引用路径
4. 用户想看细节时: read_file ~/.hermes/context_refs/{hash}.md

卸载级别

2. 记忆巩固（Cron每天凌晨3点）

运行脚本

# 手动触发
python3 ~/.hermes/scripts/memory_consolidate.py

Cron 配置

// 已在 cron 注册:
{
  "job_id": "9926ae23cdbc",
  "name": "memory-consolidation",
  "schedule": "0 3 * * *",
  "script": "memory_consolidate.py",
  "no_agent": true
}

FSRS 评估逻辑（用于会话内手动评估记忆条目）

# 快速计算
def memory_health(entry_age_days, access_count):
    R = 1.0 / (1.0 + entry_age_days / (9.0 * 2.5))  # 假设 S=2.5天
    if access_count == 0 and entry_age_days > 14:
        return "可移除 — 从未访问且超过2周"
    if R < 0.3:
        return "低可检索 — 建议移出 memory 或降低优先级"
    if R > 0.7 and access_count >= 2:
        return "健康 — 频繁使用"
    return "正常"

3. Memory ↔ Fact Store 桥接

提升规则

memory 空间 > 90% → 扫描可提升到 fact_store 的条目 条件:

• 含明确实体名（方法/工具/人）→ 适合 fact_store
• 跨session有效 → 适合 fact_store
• 仅在当前 session 有用 → 留在 memory 或删除

fact_store → memory:

• fact_store 中 trust_score > 0.7 且 retrieval_count > 2 → 确保在 memory 中有提及
• 条件: 当前 memory 空间 < 80%

去重规则

memory 和 fact_store 中内容相似度 > 80% 的条目：

1. 以 fact_store 版本为准（有信任评分）
2. 压缩 memory 中对应的冗余条目
3. 记录合并日志到 memory 的合并字段

4. 会话内记忆管理检查清单

每次复杂任务（5+ 工具调用）后：

• memory 使用量 check: >90% 触发清理
• 是否有新的用户偏好/环境细节可保存
• 是否有过期条目（项目状态变化、PR已合并）可替换
• 长工具输出是否已卸载到 context_refs/
• fact_store 是否有新事实可添加

5. 自动化铁律

记忆管理必须是自动的，不应等待用户提醒。

执行规则

6. 陷阱：hidden Unicode 字符导致 memory remove/replace 静默失败

症状: memory 工具的 remove 和 replace action 使用 old_text 做精确字符串匹配。如果已存储的条目中包含不可见 Unicode 字符（如零宽空格 U+200B、箭头变体 U+2192→ vs U+2197↗ 等），匹配会失败，不报错、不提示、无任何输出。

根因: 用户的历史条目通过不同来源/输入法/工具链创建，某些字符被不可见地替换。如 →（U+2192 ARROW）在某些终端显示不同，或直接混入零宽空格（U+200B）。

修复方案:

1. 使用 remove 时，old_text 只取前 3-5 个 ASCII 字符（短而唯一）

   • ✅ memory(action='remove', old_text='核心哲学')
   • ❌ memory(action='remove', old_text='核心哲学: Synthos自进化为唯一目标...')

2. 如果 remove 静默失败（无输出），先用 add 写干净版本，再短前缀 remove 旧版本

3. 清理后务必做空间自检：查看 memory 输出，确认释放了预期空间

4. fact_store 同理 — 删除条目时 trust_score 低且 retrieval_count=0 的条目优先清理

5. 验证: 每次 remove 后，确认 memory 输出中的 capacity: X/2200 数字变化。如果不变，说明 old_text 匹配失败。

详细内容已移至 references/ 目录。

验证清单 · VERIFICATION

• 长工具输出（>10KB 或 >50行）已保存原文至 ~/.hermes/context_refs/{hash}.md，回复中仅保留 Mermaid 摘要 + 引用路径
• 手动触发 python3 ~/.hermes/scripts/memory_consolidate.py 成功执行，与 3:00 cron（job 9926ae23cdbc）行为一致
• FSRS 健康评估对记忆条目返回了可检索性分级（可移除 / 低可检索 / 正常 / 健康）
• memory 空间按铁律分级处理：>85% 主动清理、>90% 清理+压缩、>95% 强制压缩至 <70%
• memory↔fact_store 去重以 fact_store 版本为准（相似度>80%），memory 冗余条目已压缩并记录合并日志
• remove/replace 使用短而唯一的 ASCII 前缀匹配，操作后 capacity: X/2200 数字确有变化（无 hidden Unicode 静默失败）

Golden 集合 · GOLDEN SET

• Golden Input: 标准输入样本（覆盖正常路径）
• Golden Output: 预期输出（精确匹配或格式校验）
• Golden Error: 预期错误信息（覆盖失败路径）

Golden 集合是测试的单一真理来源。所有改进必须通过 golden 测试。

每项验证必须可执行、可记录、可复现。验证失败时记录原因和修复。

Memory Optimization System

Genes (策略基因)

紧凑策略表示。条件→策略。需要深度时参考完整文档。

• [MEMO-001] 工具输出超过 10KB 或 50 行 → 自动保存原文至 context_refs 并替换为 Mermaid 摘要以卸载上下文
• [MEMO-002] 记忆条目从未访问且年龄超过 14 天 → 标记为可移除以释放记忆空间
• [MEMO-003] 记忆空间使用率超过 85% → 触发主动清理机制，若超过 95% 则强制压缩至 70% 以下
• [MEMO-004] 记忆条目包含明确实体且跨会话有效 → 提升至 fact_store 以优化记忆分层存储
• [MEMO-005] Memory 与 Fact Store 内容相似度超过 80% → 以 Fact Store 版本为准并压缩 Memory 中的冗余条目
• [MEMO-006] 执行记忆删除或替换操作时 → 仅使用短且唯一的 ASCII 前缀作为匹配键以避免隐藏 Unicode 字符导致静默失败
• [MEMO-007] 复杂任务（5+ 工具调用）结束后 → 执行记忆管理检查清单以确认空间、偏好保存及过期条目清理

示例 · EXAMPLES

示例 1：长输出上下文卸载（L1）

• 输入: 工具输出 45KB（>10KB 触发线）
• 操作: 保存原文至 ~/.hermes/context_refs/{hash}.md，回复中仅保留 Mermaid 摘要 + 引用路径
• 验证: 文件存在且可读（read_file ~/.hermes/context_refs/{hash}.md 可回看细节），回复上下文轻量

示例 2：记忆空间超阈值的自动清理

• 输入: 复杂任务结束后 memory 空间 92%
• 操作: 按铁律分级立即清理 + 压缩；优先删 access_count=0 且年龄 >14 天的条目
• 验证: 清理后 memory 输出中 capacity: X/2200 数字下降，空间回落到 <90%

示例 3：hidden Unicode 导致的静默删除失败

• 输入: memory(action='remove', old_text='核心哲学: Synthos自进化...') 无输出
• 操作: 改用短而唯一的 ASCII 前缀 old_text='核心哲学' 重试；仍失败则先 add 干净版本再短前缀删除旧版本
• 验证: remove 后 capacity: X/2200 数字确有变化（不变即匹配失败）