---
name: cold-memory-archive
description: "四层架构(Hot->Cold->Config->Runtime) + Memory Schema v1(Learning Event) + Tool Metadata + Project State + Observation Week + Skill Archive + Retrieval Logging"
---

# Cold Memory Archive — Runtime Protocol

> 架构文档、设计原理、5-state Kernel 详情 → `references/cognitive-architecture.md`

## 四层架构（完整系统模型）

系统不是三层，是四层：

```
① Hot Memory（路由提示层）— 存 capability exists + how to find it + special warnings
     ↓
② Cold Memory（结构化知识层）— 3-tier JSON (episodic/semantic/procedural)
     ↓
③ Config / Script（可执行真值层）— 端点、认证格式、retry逻辑、payload schema
     ↓
④ Runtime（执行层）— load config → execute
```

**核心原则：Hot Memory 不是知识层，而是调度层。** 它不存可执行真值，只做路由提示。Kimi API 的完整配置在 Config/Script 层，hot memory 只需要一条 "requires thinking:disabled" 的注意事项。

### 三层信息分类（数据放在哪）

每次处理信息时，先判断它属于哪一层：

| 层 | 回答的问题 | 存哪 | 是否跨session |
|----|-----------|------|-------------|
| **Session History** | "刚才我们说了什么？" | session_search（FTS5全文检索） | ❌ 不跨 |
| **Project State** | "项目做到哪了？" | cold storage → 1个milestone-triggered snapshot JSON | ✅ 一定跨 |
| **Cold Memory** | "长期应该记住什么？" | cold storage（3-tier JSON: episodic/semantic/procedural） | ✅ 一定跨 |

**判断标准：** 信息该放哪一层，只看它回答什么问题。
- Where am I? → Project State
- What do I know? → Cold Memory
- What were we talking about? → Session

**Hot Memory 的定位：** 不属于上述三层中的任何一层。它是"调度层"——提示能力存在、有特殊注意事项，但不存储可执行细节。详见 references/4-layer-architecture.md。

## Project State（milestone-triggered snapshot）

### 作用
解决"跨session不知道进行到哪了"的问题。下次session开始时读取它，不需要用户重新描述背景。

### 格式
```json
{
  "project": "项目名称",
  "phase": "当前阶段（如 'Round 2 - Merge Review'）",
  "completed": ["已完成事项"],
  "pending": ["待办事项"],
  "next_action": "下一步做什么",
  "updated_at": "ISO时间戳"
}
```
phase字段回答"我们现在在哪"，比todo列表更重要。

### 存储位置
cold storage JSON（`~/.hermes/memory/cold/project_state.json`），和冷记忆同一套存储。

当前项目状态文件的例子：
```json
{
  "phase": "memory-schema-v1",
  "completed": ["四层架构定型", "Memory Schema v1", "Tool Metadata", "Observation Week checklist"],
  "pending": ["小Q离线修复", "Observation Week — 收集数据"],
  "next_action": "正常使用 Hermes，按 observation-checklist.md 记录",
  "updated_at": "2026-07-02"
}
```

### 写时机
只有 **Project Milestone** 时才更新。不是每次变化都写，不是每个session都更新。
- ✅ 完成一个Round / 完成一次架构重构 / 决策发生改变 / 项目阶段改变
- ❌ 改了一条prompt / Archive一个skill / 修了一个typo / 调整一个阈值

### Session启动流程
1. session开始时，去cold storage读最近的project_state
2. 如果没有 → 新建一个
3. 如果有 → 从phase/completed/pending/next_action知道进行到哪了

### 与session-wrap-up的关系
**互补但独立。** project_state跟踪项目进度（"做到哪了"），session-wrap-up提取学习总结（"学到了什么"）。两者写时机不同、目标不同，不要混在一起。

## Promotion & Demotion（冷→热晋升）

当冷记忆条目需要提升到热记忆时，有两种机制：

### A. Usage-based promotion
``` 
cold → hot
条件：同一条目被频繁引用（如3次/24h）
用途：提升可见性，减少路由延迟
```
适用于：API是否重要、工具是否常用。

### B. Failure-based promotion
```
runtime error / missing field / hallucination
→ 自动上升 cold memory importance
```
适用于：经常出错的API、经常timeout的wrapper、经常变的endpoint。错误记录驱动重要性提升，让系统从失败中学习。

## 两条轨道

| 模式 | 触发条件 | 执行协议 |
|------|----------|---------|
| **默认** | 常规问答，红灯未命中 | Activation Gate → Observe → Answer |
| **复杂/调试** | 红灯命中 / 证据不足 / 用户明确要求深度分析 | Activation Gate → 加载5-state Kernel（references/） |

## Activation Gate（每次回答前必过）

快速判断是否需要查冷记忆或 session 历史：

| 信号 | 触发词 |
|------|--------|
| 过去引用 | 之前、上次、以前、昨天、刚才、我记得、怎么回事 |
| 配置/状态 | key、token、配置、密码、凭证、repo、仓库 |
| 怀疑/纠正 | 确定吗、你确定、不对、不是、错了、你再想想 |
| 原因追问 | 为什么 |

**无信号 → 直接答。有信号 → 调 cold_memory_search / session_search。**

## 默认模式：Observe → Answer

1. 看见什么就是什么，不自动补全
2. 直接答，不绕弯
3. 不确定的标置信度（Confidence Brake）：高/中/低/不知道

## 复杂/调试模式（红灯命中时激活）

红灯条件（任一命中即进入调试模式）：
- 第一次出现的新事实（无历史对照）
- 涉及密码/Token/凭证/配置修改/删除/部署
- 言论无来源引用
- 用户指出过错误后仍需验证

**进入调试模式后：** 加载 `references/cognitive-architecture.md` 中的 5-state Kernel 协议。按 Observe → Separate → Expand → Evaluate → Commit 走完整流程，输出按 4-layer Protocol（Fact → Evidence → Judgment → Action）。

## Hot Memory Archive（Memory > 70% 时执行）

### Hot Memory 文件位置

热记忆作为两个纯文本文件存储在磁盘上，每条记录以单独的 `§` 行分隔：

| 文件 | 路径 | 内容 | 容量目标 |
|------|------|------|----------|
| MEMORY.md | `~/AppData/Local/hermes/memories/MEMORY.md` | 系统热记忆（教训/偏好/原则/配置路由提示） | ~2200 chars |
| USER.md | `~/AppData/Local/hermes/memories/USER.md` | 用户画像（身份/沟通风格/方法论） | ~2200 chars |

格式示例（§ 为分隔符）：
```
> 最后更新：2026-07-03
§
[教训] 具体教训内容
§
[偏好] 用户偏好
```

**关键发现：** 这些文件位于文件系统上，通过 `read_file`/`write_file` 工具可直接读取和修改，不依赖 `memory()` 工具。

### 标准流程（活跃会话中）

当 hot memory 使用率 > 70% 时：

1. **检查使用率** — 通过 `memory()` 工具或直接统计 `wc -c MEMORY.md USER.md`
2. **识别可归档条目** — >30天 / 已完成任务 / 稳定配置 / 重复偏好 / 可推导的原则
3. **写入冷存储** — `cold-memory.py add --type <type> "<content>" --tags <tags> --importance <n>`
4. **移除热记忆条目** — 用 `write_file` 重写文件（删除对应 `§` 段）
5. **验证** — 校对文件大小是否降低到目标容量以下

### Cron 环境下的 Hot→Cold 归档（本 Session 验证可行）

`memory()` 工具和 `execute_code` 在 cron 中不可用，但 hot memory 是纯文件系统上的 Markdown 文件，**可以通过 terminal/read_file/write_file 直接操作**。

| 操作 | Cron | 方法 |
|------|------|------|
| `cold-memory.py archive`（冷记忆过期清理） | ✅ | `terminal()` |
| `cold-memory.py health`（冷记忆健康检查） | ✅ | `terminal()` |
| 检查 hot memory 使用率 | ✅ | `wc -c MEMORY.md USER.md` via `terminal()` |
| 读取热记忆分析 | ✅ | `read_file()` |
| `cold-memory.py add`（写入冷存储） | ✅ | `terminal()` 直接调用 |
| 移除热记忆条目 | ✅ | `write_file()` 重写文件 |
| `memory()` 工具调用 | ❌ | Hermes 服务端管理，cron 无此工具 |
| `execute_code` | ❌ | cron 沙箱限制 |

**Cron 归档步骤：**
```bash
# ⚠️ 所有 python cold-memory.py 调用都需 cygpath -w 转路径
PYCMD="python \"$(cygpath -w ~/.hermes/memory/cold/cold-memory.py)\""

# Step 1: 检查使用率（用 -m 统计字符数）
wc -m ~/AppData/Local/hermes/memories/MEMORY.md ~/AppData/Local/hermes/memories/USER.md

# Step 2: 读取热记忆识别可归档条目
# 用 read_file() 逐行分析 MEMORY.md 和 USER.md

# Step 3: 写入冷存储
# 方式 A（推荐——可靠）: 直接写冷文件 + 更新 index.json
#   用 write_file 写入 ~/.hermes/memory/cold/{episodic|procedural|semantic}/<name>.md
#   再 write_file 更新 ~/.hermes/memory/cold/index.json（追加条目到对应分类）

# 方式 B（尝试）: 通过 cold-memory.py 脚本
$PYCMD add --type semantic "<完整条目>" --tags tag1,tag2 --importance 0.6

# 批量方式（推荐 - 已验证2026-07-11可行）：
# 构建 {content: importance} JSON 作为命令行参数传递
$PYCMD hot-archive '{"条目1": 0.6, "条目2": 0.4}'

# 也可以从 stdin 管道输入
echo '{"条目内容": 0.8}' | $PYCMD hot-archive

# 如果 hot-archive 命令不存在 → 回退到方式 A（手动 write_file 冷文件 + index.json）

# Step 4: 用 write_file 重写热记忆（删除已归档的 § 段落，合并重复条目）
#   删除对应 § 分隔的段落，合并重复同类条目
#   更新元数据行的时间戳

# Step 5: 验证（用 -m 检查字符数）
wc -m ~/AppData/Local/hermes/memories/MEMORY.md ~/AppData/Local/hermes/memories/USER.md
# MEMORY.md 应低于 1540 chars，USER.md 应低于 963 chars
```

### 使用率计算

**⚠️ 中文文本必须用 `wc -m`（字符数），不要用 `wc -c`（字节数）。**

`memory_char_limit` 是**字符数**（见 config.yaml），而中文 UTF-8 每个字占 3 字节。
用 `wc -c` 在中文占多数的文本里会高估 3 倍，导致虚高触发归档。

正确做法：

```bash
# ✅ 统计字符数（中英文统一按字符算）
wc -m ~/AppData/Local/hermes/memories/MEMORY.md
wc -m ~/AppData/Local/hermes/memories/USER.md

# ❌ 不要用 wc -c（字节数，中文场景严重不准）

# 使用率计算示例：
# MEMORY.md = 1883 chars / 2200 limit = 85.6% → 触发归档
# USER.md = 1220 chars / 1375 limit = 88.7% → 触发归档

# 安全阈值：单个文件 chars > limit × 70% 触发归档
# MEMORY limit: 2200 chars (70% = 1540)
# USER limit: 1375 chars (70% = 963)
```

**注意检查两个文件**：`MEMORY.md`（memory_char_limit: 2200）和 `USER.md`（user_char_limit: 1375）各自独立计算使用率。任何一个超过 70% 都应触发对应文件的归档。

### 可归档条目类型判断标准

| 应保留在 Hot | 可归档到 Cold |
|-------------|-------------|
| 用户身份（姓名/学校/专业/年级） | 稳定硬件spec（天选6Pro 等） |
| 核心目标（专升本/四级/入团） | API 详细配置（endpoint+key） |
| 活跃硬规则（"所有人讨论必须调API"） | 工具列表（已装软件） |
| 近期教训（<30天） | 架构决策（已稳定不再改的） |
| 活跃警告（zangxiangAI等） | 重复/可推导的原则 |
| 沟通底线（"直说"/"先这样"等） | 旧偏好（用户没再提的） |
| 小Q 昵称等活跃偏好 | 方法论框架（5-state Kernel等） |

## Observation Week（使用驱动验证）

当系统从设计阶段进入使用阶段后，每天结束时回答三个问题：

详细观察清单：`~/.hermes/memory/cold/observation-checklist.md`（7 项维度 + Week End 决策矩阵）

每天结束时回答三个问题：

1. **今天 Hermes 真正帮我省了一次什么事？**
2. **今天 Hermes 真正让我卡住了一次什么事？**
3. **如果今天完全没有 Hermes，我会不会明显更麻烦？**

### 防确认偏差（2026-07-02 新增）

Observation Week 最大的风险不是数据太少，而是**确认偏差（confirmation bias）**。
对于每条 Architecture Hypothesis，验证标准里必须包含"什么证据会让我放弃这个假设"（反证条件）：

**反证示例：**
- **H-001（Search Policy）：** 反证 = 绝大多数请求已靠 Router 正确决策，独立 Search Policy 增益几乎为零
- **H-002（Safety Policy）：** 反证 = 现有工具白名单已覆盖所有工作流需求
- **H-003（Decision Principles）：** 反证 = 原则自然沉淀在各 Agent 中，抽离无额外收益

### 反证收集（2026-07-05 新增）

Observation Week 不只是验证假设成立，也要主动收集**反证**（证据否定假设）：

| 反证信号 | 含义 |
|---------|------|
| Tool 没有稳定共现 | H-004 不成立 |
| Provider 一直很稳定 | H-005 优先级下降 |
| 几乎不需要搜索 | H-001 不需要复杂化 |
| Memory 容量不再满 | 压缩策略无需进一步设计 |

> 一周后能否定一个原本很好的想法，也是一次成功的 Observation。

### 架构冲动日志（Architecture Impulses — 2026-07-05 新增）

Obs Week 期间每天记录"想到但没有实现的新架构点"。格式：

```text
- **想法：**
- **为什么没有实现：**
- **是否影响今天正常使用：** 是 / 否
```

如果连续多天"想到了但没必要" → Feature Freeze 成功。
如果出现"影响正常使用 = 是" → 值得在 Architecture Review 中讨论。

> 目标：记录事实，不设计未来；收集证据，不寻找证据。

### Reference Notes 模式（2026-07-05 新增）

当发现外部参考（GitHub PR、社区讨论、其他项目设计）时，不要升级为 Backlog 或修改 Hypothesis。
保存为轻量 **Reference Notes**：

```
architecture/references/
  └── 2026-07-05-provider-routing-notes.md   ← 日期+主题
```

内容结构：
- 来源（链接）
- 关键设计点（要点列表，不展开）
- 验证问题（Architecture Review 时对照的数据问题）

**不是** Observation（不是数据）、**不是** Backlog（不是待办）、
**不是** Proposal（不是设计）、**不是** Hypothesis（不是待验证假设）。
它只是"别人已经验证过一种设计"的证据，不能证明"你的系统需要它"。

### 设计原则（2026-07-05 确立）

Observation Week 期间确立的关键设计原则：

1. **Capability First, Adapter Second, Software Last** — 用户说需求，Hermes 想 Capability，Router 选 Adapter
2. **每增加一层抽象，都必须能消除至少两个具体问题；否则只是新的复杂度。**
3. **记录事实，不设计未来；收集证据，不寻找证据。** — Obs Week 的纪律信条

### Obs Week 结束: ADR Review 四问

不要直接 `provisional → validated`。每条 Hypothesis 逐条回答四个问题才能升级状态：

1. **证据是否足够？**
2. **收益是否大于新增复杂度？**
3. **有没有更简单的替代方案？**
4. **如果今天重新设计 Hermes，还会不会做同样的选择？**

只有四个问题都过了，再 upgrade 状态。

### 边界规则

- 只有**重复暴露**才算真实问题
- "感觉不顺"先记，**连续三次同类不顺**再动架构
- 单次偶发不触发架构变更

### 判断标准

一周后评估：
- 第一问越来越具体 ✅ 系统在产生价值
- 第二问越来越少 ✅ 系统在变稳定
- 第三问多数回答"会" ✅ 系统不可替代

反之，如果每天都在"今天又发现一个协议可以优化" → 说明还没离开调试台。

## 技能生命周期管理（Skill Archive 协议）

当需要清理 Agent Skill 时：

1. **快照** — 存当前 Active 列表 + Pin 状态 + 时间戳
2. **按"未来30天是否进推理路径"分类** — 不是按"never-used"
3. **先 Archive 低争议类别**（creative / mlops / email 等不影响核心工作流的）
4. **观察 1-2 天** — 判断标准：有没有"想用找不到"的情况
5. **不要追求目标数字** — 先减到 ~80，评估效果后再决定是否继续

## Retrieval Logging（Observation 数据采集）

从 2026-07-01 开始，每次 cold memory 搜索自动记录到 `~/.hermes/memory/cold/_search_log.ndjson`。

### 格式
```json
{"ts": "2026-07-01T09:33:55Z", "query": "Xiaomi API", "hits": 5, "layer": "all"}
```

### 设计约束
- **fire-and-forget** — 记录失败不得阻塞搜索（try/except 包住）
- **纯 instrumentation** — 不影响 retrieval 逻辑、memory 层级、trust policy
- **schema 固定** — 不随迭代扩展成"顺便记一下"
- **Observation Week 数据源** — 周结束时统计 0-hit 次数、命中率等

### 查看日志
```bash
cat ~/.hermes/memory/cold/_search_log.ndjson
```

## Tool Metadata（2026-07-02 定型）

给 Hermes 所有工具加了两组声明式标记：

| 标记 | 含义 | 用途 |
|------|------|------|
| `isReadOnly: true` | 不修改状态 | 可安全并行调用 |
| `isDestructive: true` | 永久修改状态 | 必须串行执行 |

定义在 `~/.hermes/memory/cold/hermes.agents.yaml` 的 `tool_manifest` 节。详见 `references/tool-manifest.md`。

### 当前分类

- **ReadOnly + 可并行**（8个）：read_file, search_files, session_search, skill_view, browser_snapshot, browser_vision, vision_analyze, process（list/poll 只读模式）
- **Destructive + 串行**（14个）：terminal, write_file, patch, memory, skill_manage, delegate_task, todo, execute_code, browser_navigate, browser_click, browser_type, browser_scroll, browser_press, browser_back

### 使用原则

- 先有 Metadata，再改 Router — 当前只声明存在，不改路由逻辑
- Observation Week 验证标记准确率（accuracy < 80% 再修正）
- 保持二元判定简单，不支持"依赖参数动态判定"

## Memory Schema v1（2026-07-02 定型）

来自 Claude Code 源码分析（[how-claude-code-works](https://github.com/Windy3f3f3f3f/how-claude-code-works) 2.9k⭐），详见 `references/memory-schema-v1.md`。
完整 15 章架构分析存于 `~/.hermes/memory/cold/claude-code-architecture.md`。

## Architecture Governance（2026-07-03 定型）

详见 `~/.hermes/memory/cold/GOVERNANCE.md`（完整的治理文档，5 问定稿）。

### 四对象治理模型

| 类型 | 是否需要验证 | 是否指导实现 | 例子 |
|------|-----------|-----------|------|
| **Constraint** | ❌ 否，强制执行 | ✅ 是 | Register≠Expose 分离、Memory Admission Rule |
| **Hypothesis** | ✅ 需要 Obs Week 验证 | ⏳ 验证通过后 | Tool Gating、Provider Health Score |
| **Backlog** | ❌ 暂时不 | ❌ 否 | Hook System、Lineage Compression |
| **Proposal** | ❌ 设计阶段 | ❌ 否 | AP-001: Capability驱动架构 |

### 状态流转

```
Idea → Proposal（产出 AP-xxx.md） → Backlog
  │ 满足三条件 ↓
  → Hypothesis Review
    ├── 通过 → Hypothesis (provisional) → observational → validated/invalidated
    └── 不通过 → 退回 Backlog + 书面理由 + 重审触发条件
```

详见 `references/governance-model.md`（完整治理模型参考）。

### Backlog → Hypothesis 升级条件

满足全部三条后**自动进入评审**，不得无理由搁置：
1. **可验证的假设陈述**（Hypothesis Statement）
2. **最小验证方案**（Minimum Validation Plan）— 在现有资源约束内可执行
3. **验证标准**（Verification Criteria）— 明确定义成功/失败标准

### Feature Freeze（Observation Week 期间生效）

- **禁止：** 新增架构层、Runtime 行为、Router 逻辑、Memory Schema 字段、Tool 生命周期
- **允许：** Bug 修复、文档完善、日志补充、Metrics 采集、Observation Checklist 调整
- **退出条件：** 核心数据完成 or 阻断性问题 or 预定期满

### Architecture Constraint（2026-07-03 新增）

**Register → Expose → Invoke 分离** — 接口边界，不依赖验证结果，强制执行。
即使 Tool Gating 验证失败，这个边界依然成立。因为它决定的是 API 怎么设计，不是 Router 怎么决策。

### Observation Week 纪律

进入 Obs Week 后不得新增架构能力。成功标准不是"实现了多少功能"，而是"否定了多少未经证据支持的想法"。Obs Week 结束做 ADR Review 四问（见下方）。

## Architecture Hypotheses（ADR 层 — 定型于 2026-07-03）

管理尚未验证的架构假设，与已验证的 Learning Event 分离。

### 定位

| 类型 | 内容 | 状态 |
|------|------|------|
| **Learning Event** | 已验证的经验 | `active / deprecated / verified` |
| **Architecture Hypothesis** | 待验证的架构假设 | `provisional → informed → observational → validated / invalidated / graduated` |

### 核心规则

1. **上限 5 条** — 超出时必须有 Hypothesis 被 invalidated 或 graduated 才能加新
2. **可证伪性门槛** — 新增时必回答："Obs Week 结束后用什么证据验证它？"
3. **来源标注** — 必须记录假设来源（来自哪个系统/哪次讨论）
4. **Alternative considered** — 每条记录备选方案，避免"只有一个答案"的偏误

### 结构

```yaml
id: H-001
type: architecture_hypothesis
statement:        假设内容
rationale:        为什么考虑这个方向
confidence:       0.0-1.0（初始不高）
verification_criteria: { level_1, level_2, level_3 }
alternatives_considered: [备选方案]
status: provisional | informed | observational | validated | invalidated | graduated
source:           来源
owner:            负责人
created_at:       ISO时间
```

### 当前活跃假设（2026-07-03）

详见 `references/architecture-hypotheses.md`。文件存于 `~/.hermes/memory/cold/architecture_hypotheses/`。

| ID | 假设 | 置信度 | 状态 |
|----|------|--------|------|
| H-001 | Router层应独立Search Policy | 0.6 | provisional |
| H-002 | 安全响应应抽象为独立Safety Policy | 0.5 | provisional |
| H-003 | 顶层应存在独立Decision Principles | 0.7 | provisional |
| H-004 | Tool Gating（按任务暴露工具） | 0.6 | provisional |
| H-005 | Provider Health Score（动态评分路由） | 0.5 | provisional |

### 状态机

```
provisional （新提出，纯理论推导）
    ↓
informed （有间接证据支持）
    ↓
observational （在 Observation Week 中收集数据）
    ↓
validated （数据确认） → graduated（升级为正式原则）
    OR
invalidated（被实验否定）→ 标注原因后归档
```

已验证原则不是永久真理 —— Learning Event 也允许 `validated → reconsider → updated` 循环。

### 与 Learning Event 的关系

| 维度 | Learning Event | Architecture Hypothesis |
|------|---------------|----------------------|
| 写入时机 | 事实确认后 | 设计决策讨论后 |
| 证据要求 | 已有证据 | 等待证据 |
| 预期寿命 | 长期 | 1-2个Obs Week |
| 状态机 | active → deprecated/verified | provisional → validated/invalidated |

## Claude 系统提示词分析（2026-07-02）

来自 [CL4R1T4S](https://github.com/elder-plinius/CL4R1T4S)（⭐44K）—— 各 AI 厂商泄露系统提示词合集。
Claude Opus 4.6/4.7 完整 system prompt（149KB）已分析并存于 cold memory。

关键发现：
- Claude 用 XML tag 分区组织结构（`<core_search_behaviors>`, `<file_handling_rules>` 等）
- 搜索行为规范和安全规则部分对 Hermes 最有用
- Skills 系统、Memory 系统与 Hermes 方向一致

定义文件：`~/.hermes/memory/schema.yaml`（YAML 前端 + Markdown 正文，纯规范文档，不作机器解析）。

### 三个原则

1. **只记不可推导的信息** — 能重新获得的（Git 历史 / README / 代码结构）不存
2. **可失效** — 用 status 状态机管理生命周期（active → challenged → deprecated / verified）
3. **可验证** — 每条经验附带 evidence 来源，支持按可信度排序

### Learning Event 结构

```yaml
observation:  发生了什么（事实）— ✅ 必需
why:          为什么这么做（原因）— ✅ 必需
apply_when:   什么情况下复用（适用范围）— ✅ 必需
avoid_when:   边界条件（防止过度泛化）— 建议
confidence:   可信度 0-1 — 可选
evidence:     证据来源（user_feedback / benchmark / repeated_success）— 可选
status:       生命周期状态（active / challenged / deprecated / verified）— 可选
```

### 压缩流水线

```
Raw Event → 摘要（统一表达）→ 语义去重 → 再摘要（合并）→ 存储
```

先摘要再去重。先摘要标准化才能发现语义重复。

## CLI Quick Reference

```bash
# ⚠️ Windows/git-bash: python 是 Windows 二进制，~ 展开后路径错误
# 必须用 cygpath -w 转成原生 Windows 路径：
PYCMD="python \"$(cygpath -w ~/.hermes/memory/cold/cold-memory.py)\""

# 搜索冷记忆
$PYCMD search "keyword" --limit 5

# 健康检查
$PYCMD health

# 列出所有条目
$PYCMD list --type semantic

# 归档过期条目
$PYCMD archive

# 查看搜索日志
cat ~/.hermes/memory/cold/_search_log.ndjson

# 一键归档脚本（含健康检查 + 过期清理 + 孤立索引修复）
bash ~/.hermes/memory/cold/cold-memory-archive.sh
```

如果不想用变量，每次直接写完整命令：
```bash
python "$(cygpath -w ~/.hermes/memory/cold/cold-memory.py)" health
```

## Index Integrity: Orphaned Entry Prevention（2026-07-10 新增）

### 问题

cold-memory index.json 中的条目引用了不存在的 JSON 文件。这发生在：
- 手动删除 cold/ 目录中的 .json 文件而未同步更新 index.json
- 文件系统操作（备份/恢复/同步）中途中断
- 旧版 cold-memory.py 的 bug 导致只写了 index 没写文件

### 发现

2026-07-10 cron 运行发现 4 个孤立索引条目：
- `mem_c_learning_0709` — C语言学习记录（文件丢失）
- `mem_openclaw_sync_0709` — OpenClaw同步待办（文件丢失）
- `mem_tools_installed_0709` — 工具安装记录（文件丢失）
- `mem_env_config_0709` — 环境配置（文件丢失）

每个条目的 summary 存在，但磁盘上无对应 JSON 文件。这些条目的 `importance` 值较低（<0.5），本质是 session 快照型数据在归档过程中文件写入失败导致。

### 自动检测与修复

`cold-memory-archive.sh` 现已包含自动孤立条目清理步骤：

```python
# 伪代码逻辑
for t in ['episodic', 'semantic', 'procedural']:
    for eid in index['entries'][t]:
        fp = os.path.join(t, f'{eid}.json')
        if not os.path.exists(fp):
            del index['entries'][t][eid]  # 从索引删除
            total -= 1
_save_index(index)  # 写回
```

步骤在 `health` + `archive` 之后执行。只删除索引引用，不影响其他条目。

### 手动修复

```bash
cd ~/.hermes/memory/cold
python -c "
import json, os
idx = json.load(open('index.json','r',encoding='utf-8'))
orphaned = []
for t in ['episodic','semantic','procedural']:
    for eid in list(idx['entries'].get(t,{})):
        fp = os.path.join(t, f'{eid}.json')
        if not os.path.exists(fp):
            orphaned.append((t, eid, idx['entries'][t][eid].get('summary','')[:60]))
            del idx['entries'][t][eid]
if orphaned:
    total = sum(len(idx['entries'].get(t,{})) for t in ['episodic','semantic','procedural'])
    idx['stats']['total_entries'] = total
    json.dump(idx, open('index.json','w',encoding='utf-8'), indent=2, ensure_ascii=False)
    for t, eid, s in orphaned:
        print(f'  [CLEAN] {t}/{eid}: {s}')
    print(f'Removed {len(orphaned)} orphaned entries')
else:
    print('No orphaned entries')
"
```

## Pitfalls

- **Builder Mode Recurrence (see references/builder-mode-recurrence.md):** 刚建立"使用驱动"原则后，第一反应仍可能是"半小时就能集成X"。每次提议新集成前先问：这是证据驱动还是新奇驱动？

- **Windows/git-bash: python ~/path 路径断裂** — git-bash 把 ~ 展开为 /c/Users/xxx/，而 python 是 Windows 二进制，把 /c/ 当成 C:\\c\\ 解析导致找不到文件。所有 python 调用必须用 cygpath -w 转原生路径：python "$(cygpath -w ~/.hermes/memory/cold/cold-memory.py)"。bash 命令（bash cold-memory-archive.sh）和 wc -m 不受此影响。

- **不要归档用户身份**（name, school, goals）— 留在 hot memory
- **不要归档活跃偏好**（<30天）— 用户会需要重复
- **不要编造检索结果** — 冷记忆搜不到就说搜不到
- **不要给系统叙事代替行为验证** — "我改了X、Y、Z"不是修好了的证据
- **发现成本 > 恢复成本** — Archive 的 skill 如果用户忘了它存在，等于丢了。保留轻量索引（archived list）。
- **"所有人讨论" = 实际调 API** — 用户说"所有人讨论"/"让Kimi和小米看看"时，必须实际调用它们的API，不能凭自己猜它们会说什么。用户明确踩过这条线，直接骂过。调用失败（超时/Key失效）就如实报告失败，不要用自己的判断代替。
- **不要只是全部同意** — 用户要求全面审视/所有人讨论时，如果各方只说"同意/支持/合理"，用户会认为在敷衍。每个模型（包括你自己）都应给出独立的批评性分析，而不是简单附议。用户明确说过"他妈的你们就完全支持吗"——这是回避深度分析的信号。
- **先展示讨论结果，等用户确认再执行** — 当需要 KIMI/XIAOMI 参与讨论时，先把它们的回复展示给用户看，等用户说"干吧"再动手。不要自己埋头写文件/改代码——你得到的讨论结果用户还没看过。用户会问"你们讨论了吗"。流程：调用API → 展示结果 → 用户确认 → 执行。
- **所有模型都应独立批评，而非全部附议** — 当用户要求"所有人讨论"时，如果所有模型只说"同意/支持/合理"，用户会认为在敷衍。每个模型（包括你自己）都应给出独立的批评性分析。用户明确说过"你们就完全支持吗"——回避深度分析会被察觉。确保至少一个模型提出具体的质疑点或补充建议。
- **两个 archive 脚本可能不同步** — `~/.hermes/memory/cold/cold-memory-archive.sh`（规范版本，含 orphan cleanup）和 `~/.hermes/scripts/cold-memory-archive.sh`（cron 实际调用的版本）可能不同步。cron 从 `~/.hermes/scripts/` 读取。每次修改规范版本后，检查 `~/.hermes/scripts/cold-memory-archive.sh` 是否也需要更新。技能内的 `scripts/cold-memory-archive.sh` 也应保持最新。

- **Cron 环境下 `memory()` 不可用，但 Hot Memory 文件可直接操作** — `memory` 工具由 Hermes 服务端管理，在 cron 上下文中不可用。但 hot memory 实际存储为 `~/AppData/Local/hermes/memories/MEMORY.md` 和 `USER.md` 两个纯文件——通过 `read_file`/`write_file`/`terminal` + `wc -c` 可直接读取、计算使用率、写入冷存储和剪裁。cron 可以做 hot→cold 归档的唯一约束是：`memory()` 调用、`execute_code` 和 `delegate_task` 不可用。见上方的完整 cron 归档流程。

## 关联文件

- `references/governance-model.md` — 完整治理模型（四对象 + Feature Freeze + 升级流程）（2026-07-03）
- `references/available-toolchain.md` — 全部可用工具链清单（Ollama/Qwen3/AnySearch/Claude Code等）（2026-07-02）
- `references/ap-001-capability-architecture.md` — Capability驱动架构提案（Phase 2 路线图）（2026-07-03）
- `references/ecc-cross-reference.md` — ECC(224k⭐) 交叉参考 & Hermes 方向验证（2026-07-01）\n- `references/hermes-agents-yaml.md` — hermes.agents.yaml 三脑分工配置文件说明（2026-07-01）\n- `references/local-qwen3-integration.md` — 本地 Qwen3-8B 模型集成说明（2026-07-01）\n- `references/loop-engineering.md` — Loop Engineering 概念 & 工具（4692⭐, 2026-07-01）
- `references/agent-contracts.md` — Agent 输入输出合约 & Circuit Breaker & 7 层网关架构（2026-07-02）
- `references/omniroute-cross-reference.md` — OmniRoute 4-tier fallback 交叉参考（2026-07-02）
- `references/claude-code-memory-system.md` — Claude Code 记忆系统 vs Hermes 冷记忆对比分析（2026-07-02）
- `references/gateway-7-layer-architecture.md` — AI 网关 7 层架构模型（Task→Capability→Intent→Policy→Adapter→Router→Provider）（2026-07-02）
- `references/hermes-roadmap-phases.md` — Hermes 演进路线图 Phase 0-4（定型于2026-07-02）
- `references/cognitive-architecture.md` — 完整 5-state Kernel + L2 Metadata Policy + 置信度刹车
- `references/4-layer-architecture.md` — 四层架构完整设计（定型于2026-07-01）
- `references/project-state-design.md` — 三层信息分类 + project_state 设计记录
- `references/observation-week-framework.md` — 使用驱动的工作流验证框架
- `references/trace-results-v1.md` — 边界测试结果
- `references/github-inspirations.md` — 设计来源
- `references/provider-quirks.md` — Kimi/Xiaomi API 注意事项
- `references/tool-manifest.md` — 工具 isReadOnly/isDestructive 标记设计（2026-07-02）
- `scripts/cold-memory.py` — 冷记忆管理脚本
- `scripts/cold-memory-archive.sh` — 冷记忆归档 shell 包装（含 health + archive + orphan cleanup）。**这是规范版本。**
- `scripts/xiaomi_stable.py` — 小米 API 稳定调用封装
- `~/.hermes/memory/cold/hermes.agents.yaml` — 三脑分工 + 路由规则配置文件