| name | context-recall |
| description | 按需召回已归档的上下文细节:支持按关键词、阶段、类型和决策维度检索, 从 L2 归档和 Phase Ledger 中恢复压缩丢失的信息。
|
| origin | harness-engineering |
Context Recall Skill
按需召回已归档的上下文细节,从 L2 归档索引和 Phase Ledger 中恢复压缩过程中被移出工作记忆的信息。
何时激活
- 用户输入
/recall 命令
- 需要恢复早期对话中的代码细节、工具输出或决策上下文
- 当前上下文中缺少之前阶段的关键信息
- 用户提到"之前讨论过"、"之前的方案"、"找一下之前的…"等表述
使用方式
基本命令
/recall <keyword> # 按关键词搜索归档
/recall phase:<phase_name> # 按阶段召回(如 phase:implementation)
/recall type:<element_type> # 按类型召回(如 type:tool_result)
/recall decisions # 召回所有决策记录
/recall timeline # 显示阶段时间线概览
组合查询
/recall phase:design keyword # 在 design 阶段中搜索关键词
/recall type:code_change api # 在代码变更中搜索 api 相关内容
核心功能
1. 关键词召回
从 L2 归档索引中按关键词匹配,返回相关的归档元素摘要和完整内容引用。
工作原理:
- 搜索
~/.claude/memory/sessions/{sid}/index.json 中的 keywords 字段
- 按匹配度排序返回结果
- 提供 L1 摘要和 L2 完整内容的访问路径
2. 阶段召回
从 Phase Ledger 中按阶段名称检索,返回该阶段的结构化交接记录。
输出包含:
- 阶段目标与完成情况
- 关键决策列表
- 代码变更清单
- 未解决项
3. 决策召回
跨所有阶段收集决策记录,构建完整的决策链路。适用于需要理解"为什么这样做"的场景。
4. 类型召回
按上下文元素类型检索:
tool_result: 工具执行结果
assistant_message: 助手回复
user_message: 用户消息
code_change: 代码变更
decision: 决策记录
技术实现
依赖模块
| 模块 | 路径 | 职责 |
|---|
context_recall | scripts/lib/context_recall.py | 召回逻辑核心 |
context_archiver | scripts/lib/context_archiver.py | L2 归档索引读取 |
phase_ledger | scripts/lib/phase_ledger.py | Phase Ledger 读取 |
数据源
| 源 | 路径 | 内容 |
|---|
| L2 归档索引 | ~/.claude/memory/sessions/{sid}/index.json | 关键词索引、元素摘要 |
| L2 归档文件 | ~/.claude/memory/sessions/{sid}/archived/*.md | 完整归档内容 |
| Phase Ledger | docs/memory/sessions/{sid}/phase-*.md | 阶段交接记录 |
| Ledger 索引 | /tmp/harness-phase-ledger-{sid}.json | Ledger 快速索引 |
调用示例
from scripts.lib.context_recall import (
recall_by_keyword,
recall_by_phase,
recall_by_type,
recall_decisions,
get_phase_timeline,
format_recall_results,
)
results = recall_by_keyword(session_id, "api contract")
print(format_recall_results(results))
results = recall_by_phase(session_id, "design", project_path)
print(format_recall_results(results))
results = recall_decisions(session_id, project_path)
print(format_recall_results(results))
timeline = get_phase_timeline(session_id, project_path)
print(timeline)
输出格式
召回结果以 Markdown 格式返回:
## 召回结果: "api contract"
### 匹配 1: [tool_result] API 设计讨论
- **阶段**: design
- **归档时间**: 2025-01-15 14:30
- **摘要**: 确定了 RESTful API 契约,包括认证方式和错误码规范...
- **完整内容**: ~/.claude/memory/sessions/abc123/archived/a1b2c3d4e5f6.md
### 匹配 2: [decision] 选择 OpenAPI 3.0
- **阶段**: design
- **摘要**: 决定使用 OpenAPI 3.0 作为 API 契约格式...
与其他能力的关系
| 能力 | 关系 |
|---|
strategic-compact | compact 时归档 → recall 时恢复 |
pre_compact hook | 产生 L2 归档和索引 → recall 消费 |
session_start hook | 启动时自动加载 Phase Timeline |
phase_tracker | 提供阶段上下文用于精确召回 |
phase_ledger | 提供结构化阶段交接 → recall 检索 |
限制
- 召回内容来自归档,可能不包含最近未被压缩的对话
- 关键词匹配基于词频提取,复杂语义查询可能不精确
- Phase Ledger 依赖阶段检测正确性,手动阶段切换可能遗漏
- L2 归档文件存储在本地,跨机器不可用