# Memory Optimization System

> memory-optimization-system

- Skill: `yakeworld/memory-optimization-system` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add yakeworld/memory-optimization-system`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yakeworld/memory-optimization-system/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: yakeworld (https://skillmd.com/u/yakeworld)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/yakeworld/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（机械原子暴露输入输出规范）
## 已部署组件

| 组件 | 脚本 | Cron | 模式 |
|:-----|:-----|:----:|:----:|
| **QC批量扫描** | `qc_batch_scan.py` | 每6h | no_agent |
| **记忆巩固** | `memory_consolidate.py` | 每天3:00 | no_agent |
| **上下文卸载** | 本skill（工作流） | 无cron | 会话内 |

## 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

### 卸载级别

| 级别 | 触发条件 | 行为 |
|:----:|:---------|:-----|
| L1 | 输出 > 10KB | 保存原文 + Mermaid摘要 |
| L2 | 输出 > 50KB | 只保存，回复中仅写"已保存到 {path}" |
| L3 | 命令行交互输出 | 只保存关键结果行 |

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

### 运行脚本

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

### Cron 配置

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

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

```python
# 快速计算
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. 自动化铁律

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

### 执行规则

| 条件 | 行动 |
|:-----|:------|
| memory 空间 > 85% | 本次会话主动清理 |
| memory 空间 > 90% | 立即清理 + 压缩 |
| memory 空间 > 95% | 强制清理至 < 70% |

## 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` 数字确有变化（不变即匹配失败）