---
name: "memory-lifecycle-protocol"
version: "1.0.0"
origin: "captured"
generation: 0
parent_skill_ids: []
status: "trial"
description: "记忆生命周期协议。定义 INITIALIZE → PREFETCH → SYNC → CHECKPOINT → EXTRACT 五阶段记忆管理，确保 Agent 在会话中高效利用三层记忆（用户/仓库/会话），并在会话结束时提取可持久化知识。借鉴 Hermes MemoryProvider ABC 生命周期。"
trigger_phases: ["all"]
applicable_agents: ["Copilot Orchestrator", "Copilot Implementation", "Copilot Architect"]
priority: 2
---

# Memory Lifecycle Protocol — 记忆生命周期协议

> **来源**：Hermes `memory_provider.py` 的 MemoryProvider ABC：`initialize → prefetch → sync_turn → on_pre_compress → on_session_end → shutdown`。
> **关键适配**：Hermes 运行时 Python ABC → IMEX Prompt 层声明式协议；Hermes SQLite → IMEX 文件系统 `/memories/`。

## 何时触发

| 触发条件 | 说明 |
|---|---|
| 会话开始 | INITIALIZE 阶段 |
| 切片开始 | PREFETCH 阶段 |
| Agent 完成一段有实质性输出后 | SYNC 阶段 |
| Phase 切换时 | CHECKPOINT 阶段 |
| 会话即将结束 | EXTRACT 阶段 |

## 谁来调用

| Agent | 职责 |
|---|---|
| **Copilot Orchestrator** | 管理 INITIALIZE、PREFETCH、CHECKPOINT、EXTRACT |
| **所有实施/验证类 Agent** | 执行 SYNC（每轮结束后评估是否有值得记录的发现） |

---

## §1 五阶段生命周期

### 1.1 INITIALIZE — 会话初始化

> **触发**：会话开始时（自动）。

| 步骤 | 动作 | 说明 |
|---|---|---|
| 1 | 自动加载 `/memories/` 用户记忆（前 200 行） | VS Code Copilot Chat 内置行为 |
| 2 | 列出 `/memories/repo/` 仓库记忆文件清单 | 了解已有知识库 |
| 3 | 列出 `/memories/session/` 已有会话文件 | 检查是否有前次会话的未完成工作 |
| 4 | 如存在 `summary-*.md` 文件 → 读取最近一个摘要恢复上下文 | 与 `context-summary-protocol` 联动 |

### 1.2 PREFETCH — 选择性预加载

> **触发**：切片开始时，Orchestrator 确定切片涉及的业务域后。

**规则**：

1. **关键词匹配**：基于切片标识和业务域关键词，选择性读取 repo memory：
   - 切片涉及 EAM → 读取 `/memories/repo/eam-*.md`
   - 切片涉及前端 → 读取 `/memories/repo/frontend-*.md`
   - 切片涉及 Schema → 读取 `/memories/repo/schema-*.md`

2. **不盲目加载**：仅加载与当前切片相关的 repo memory 文件（≤5 个），避免 token 浪费。

3. **预加载清单声明**：Orchestrator 在路由指令中声明已预加载的 memory 文件：
   ```
   Prefetched Memory:
     - /memories/repo/frontend-codebase-structure.md (切片涉及前端)
     - /memories/repo/platform-capabilities.md (新模块开发)
   ```

### 1.3 SYNC — 每轮同步

> **触发**：Agent 完成一段有实质性输出后（非简单回答/确认）。

**评估标准**：本轮是否产生值得记录的发现？

| 发现类型 | 目标存储 | 示例 |
|---|---|---|
| 新发现的平台能力/坑 | `/memories/repo/` 追加 | "BladeX 的 `@TenantDS` 在多表 JOIN 时需要显式指定" |
| 用户偏好/纠正 | `/memories/` 追加 | "用户要求所有前端页面使用深色主题作为默认" |
| 任务进度/决策 | `/memories/session/` 追加 | "已完成 Entity 层，Controller 待 FK 翻译确认后继续" |

**去重规则**：写入前检查 memory 文件中是否已存在相同/相似内容。如存在，仅更新而非追加。

**频率控制**：同一文件在同一会话中最多追加 10 次，防止文件膨胀。

### 1.4 CHECKPOINT — 阶段检查点

> **触发**：Phase 切换时（由 Orchestrator 在路由下一阶段前执行）。

| 步骤 | 动作 |
|---|---|
| 1 | 触发 `context-summary-protocol` 生成阶段摘要 |
| 2 | 同步 Skill 使用指标到 `/memories/session/skill-metrics-{sliceId}.md` |
| 3 | 评估是否有新的 repo memory 需要写入（跨阶段发现） |

### 1.5 EXTRACT — 会话结束知识提取

> **触发**：会话即将结束时（用户发出明确的结束信号 / Orchestrator 判断切片已 closure）。

**提取阈值**：仅当会话中有 ≥3 个有价值发现时触发知识提取。

| 提取内容 | 目标 | 条件 |
|---|---|---|
| 重复出现的用户纠正模式 | `/memories/` 用户偏好 | 同一纠正出现 2+ 次 |
| 新发现的代码模式/工具技巧 | `/memories/repo/` | 可跨会话复用 |
| 技能使用偏差记录 | `/memories/repo/skill-deviations.md` | POST-10 记录的偏差 |
| 会话摘要归档 | agentLog（通过 `structured-execution-recording`） | 切片 closure |

**VS Code 限制说明**：VS Code Copilot Chat 无法拦截"会话结束"事件。EXTRACT 依赖以下启发式判断：
- 用户说"完成"、"结束"、"下次再说"等
- 切片所有阶段门禁通过
- Orchestrator 输出 closure artifact

---

## §2 Memory 文件组织规范

### 2.1 目录结构

```
/memories/
├── preferences.md          # 用户偏好（SYNC 写入）
├── patterns.md             # 常见模式（SYNC/EXTRACT 写入）
├── debugging.md            # 调试经验（SYNC 写入）
├── repo/
│   ├── frontend-codebase-structure.md   # 前端结构
│   ├── platform-capabilities.md         # 平台能力
│   ├── agent-system-analysis.md         # Agent 分析
│   ├── skill-deviations.md              # Skill 偏差记录（POST-10）
│   └── {domain}-notes.md               # 业务域发现
└── session/
    ├── summary-{sliceId}-{phase}.md     # 上下文摘要（context-summary-protocol）
    ├── skill-metrics-{sliceId}.md       # Skill 指标（skill-effectiveness-tracker）
    └── skill-deviations.md              # 当前会话偏差（POST-10 临时记录）
```

### 2.2 文件大小限制

| 文件类型 | 最大行数 | 超限处理 |
|---|---|---|
| `/memories/*.md` | 200 行 | 自动加载到上下文，须精简 |
| `/memories/repo/*.md` | 500 行 | 超限时拆分或归档旧内容 |
| `/memories/session/*.md` | 150 行 | 与 `context-summary-protocol` §2.3 一致 |

---

## §3 安全与隐私

| 规则 | 说明 |
|---|---|
| 不将敏感信息写入 `/memories/` | 密码、Token、API Key 禁止持久化 |
| 用户偏好记录需可审查 | 用户可通过 `memory view` 查看所有已存储偏好 |
| EXTRACT 前用户确认 | 在 EXTRACT 阶段，如将发现写入 `/memories/`（持久化），应向用户说明将要存储的内容 |

---

## §4 与其他 Skill 的关系

| Skill | 关系 | 说明 |
|---|---|---|
| `context-summary-protocol` | **集成** | CHECKPOINT 阶段触发摘要生成 |
| `agent-hook-lifecycle` | **集成** | POST-10 偏差记录写入 session memory |
| `skill-effectiveness-tracker` | **集成** | CHECKPOINT 同步 Skill 指标到 session memory |
| `structured-execution-recording` | **集成** | EXTRACT 时 session recordings 归档 |

---

## §5 变更日志

| 版本 | 日期 | 变更说明 |
|---|---|---|
| 1.0.0 | 2025-04-17 | 初始版本。五阶段生命周期、存储规范、安全规则。借鉴 Hermes MemoryProvider ABC。 |