context-lifecycle

Context Lifecycle Skill

管理 Claude Code 长时多轮任务中的上下文生命周期，避免压缩导致关键细节丢失。

架构概览

┌──────────────────────────────────────────────────────┐
│                 上下文窗口 (200K tokens)                │
│                                                        │
│  ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌────────┐ │
│  │  System   │ │  Ledger  │ │  Working   │ │ Buffer │ │
│  │  (10%)    │ │  (10%)   │ │  (65%)     │ │ (15%)  │ │
│  │ protected │ │ protected│ │ 主工作区    │ │ 溢出区  │ │
│  └──────────┘ └──────────┘ └────────────┘ └────────┘ │
└──────────────────────────────────────────────────────┘
         ↕ 渐进压缩                ↕ 按需召回
┌──────────────────────────────────────────────────────┐
│  L1: 摘要 + L2 引用   →   L2: 全文归档 (索引)         │
│  (替换 L0 原文)             (~/.claude/memory/)       │
│                                                        │
│  L3: 项目记忆 (跨会话)  →  docs/memory/ + Phase Ledger │
└──────────────────────────────────────────────────────┘

四层记忆模型

| 层级 | 名称 | 位置 | 内容 | 生命周期 |

|------|------|------|------|----------|

| L0 | 工作记忆 | 上下文窗口 | 当前对话、工具结果、代码 | 当前会话 |

| L1 | 摘要记忆 | 上下文窗口 (替换 L0) | 压缩摘要 + L2 归档引用 | 当前会话 |

| L2 | 详情归档 | ~/.claude/memory/sessions/{sid}/ | 完整原文、关键词索引 | 本地持久 |

| L3 | 项目记忆 | docs/memory/ | Phase Ledger、决策日志、经验 | 跨会话持久 |

渐进压缩策略

压缩基于 Working Zone 使用率，而非整体上下文使用率：

| Working 使用率 | 压缩级别 | 操作 |

|----------------|----------|------|

| < 60% | 无 | 保持 L0 原文 |

| 60% | L0→L1 | 摘要工具结果、旧对话，原文归档到 L2 |

| 75% | L1→L2 | 摘要 L1 内容，更老的摘要归档到 L2 |

| 90% | L2→L3 | 紧急压缩，决策提升到项目记忆 |

阶段感知优先级

压缩时的保留/归档决策受当前任务阶段影响：

| 阶段 | 优先保留 | 优先归档 |

|------|----------|----------|

| Planning | 需求、边界、约束 | 探索性讨论 |

| Design | 架构决策、接口契约 | 备选方案分析 |

| Implementation | 当前文件、测试结果 | 设计讨论 |

| Testing | 测试结果、缺陷 | 实现细节 |

| Review | 评审结论、修改建议 | 测试细节 |

核心组件

库模块 (scripts/lib/)

| 模块 | 职责 |

|------|------|

| phase_tracker.py | 任务阶段状态机，多信号检测（命令 / handoff / 工具启发） |

| phase_ledger.py | 阶段交接账页，在阶段切换时生成结构化 Markdown |

| context_budget.py | 四分区预算模型，Zone-aware 压缩级别判定 |

| context_archiver.py | L2 归档写入、关键词索引、去重、批量归档 |

| context_recall.py | 按需召回：关键词 / 阶段 / 类型 / 决策多维检索 |

| context_priority.py | 上下文元素优先级评分（已有） |

Hooks (scripts/hooks/)

| Hook | 触发点 | 作用 |

|------|--------|------|

| session_start.py | 会话开始 | 加载 Phase Timeline、未解决项、决策摘要 |

| pre_compact.py | 压缩前 | 分类元素为 keep/summarize/archive/discard |

| suggest_compact.py | 压缩建议 | 根据 Working Zone 使用率推荐渐进压缩策略 |

Skills (skills/)

| Skill | 用途 |

|-------|------|

| context-recall | /recall 命令，按需从 L2 归档和 Phase Ledger 检索 |

| context-lifecycle | 本文档，整体架构说明 |

| strategic-compact | 已有的 trigger-based 上下文重组能力 |

数据流

写入路径

对话/工具结果 (L0)
    ↓ Working Zone > 60%
pre_compact → categorize as "archive"
    ↓
context_archiver.archive_and_index()
    ├── 写入 L2 文件: ~/.claude/memory/sessions/{sid}/archived/{hash}.md
    ├── 更新索引: ~/.claude/memory/sessions/{sid}/index.json
    └── 返回 L1 摘要 (替换上下文中的原文)
    
阶段切换时
    ↓
phase_ledger.generate_ledger() + save_ledger()
    ├── 写入 L3: docs/memory/sessions/{sid}/phase-{N}-{name}.md
    └── 更新索引: /tmp/harness-phase-ledger-{sid}.json

读取路径

会话启动
    ↓
session_start → get_recall_context_for_session_start()
    ├── 读取 Phase Ledger 索引 → phase_timeline
    ├── 统计未解决项 → pending_items
    └── 统计决策数 → recall_hint

用户请求 /recall
    ↓
context_recall → recall_by_keyword/phase/type/decisions()
    ├── 搜索 L2 索引 (index.json)
    ├── 加载 L2 完整内容
    └── 搜索 Phase Ledger

使用指南

自动行为（无需干预）

1. 会话启动自动加载 Phase Timeline 和未解决项
2. 压缩时自动按阶段优先级归档而非丢弃
3. 阶段切换时自动生成 Phase Ledger

手动操作

1. /recall keyword — 从归档中按关键词搜索
2. /recall phase:design — 查看 design 阶段的完整交接记录
3. /recall decisions — 查看所有决策链路
4. /recall timeline — 查看阶段时间线

与现有能力的协同

• strategic-compact: 本系统的 L0→L1 压缩替代了 strategic-compact 的全量压缩，两者可共存
• error-experience-library: 错误经验在 L3 层跨会话持久保存
• continuous-learning: instinct 产物不受压缩影响，已在 L3 层

配置

可通过环境变量或 hooks.json 参数调整：

| 参数 | 默认值 | 说明 |

|------|--------|------|

| Zone ratios | 10/10/65/15 | System/Ledger/Working/Buffer 分区比例 |

| L0→L1 threshold | 60% | Working Zone 使用率触发 L0→L1 |

| L1→L2 threshold | 75% | Working Zone 使用率触发 L1→L2 |

| L2→L3 threshold | 90% | Working Zone 使用率触发 L2→L3 |