context-lifecycle

name	context-lifecycle
description	上下文生命周期管理总览：四层记忆架构（L0-L3）、任务阶段感知、 渐进压缩策略、按需召回与四分区预算模型。
origin	harness-engineering

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