在长时间的会话或复杂的开发任务中，模型上下文窗口的容量是有限的。当上下文持续增长时，推理效率可能下降，关键信息也可能被淹没。Hawa Code 提供了两项上下文管理工具：消息归档（Message Archiving） 和 消息卸载（Memo），用于主动控制上下文规模并保留可复用的分析结论。
两项工具默认处于关闭状态，需通过环境变量手动启用。
1. 启用方式
| 工具 | 环境变量 | 作用 |
|---|---|---|
| 消息归档 | HAWA_CODE_MESSAGE_ARCHIVING=true |
对历史工具结果执行消息归档 |
| 消息卸载 | HAWA_CODE_MEMO=true |
将分析结论持久化到磁盘，按需读取 |
在项目的 .env 文件中添加以下配置即可启用：
HAWA_CODE_MESSAGE_ARCHIVING=true |
两项工具的功能互为补充：消息归档用于减少即时上下文的体积，消息卸载用于在多个会话阶段之间保留结构化信息。建议在处理复杂任务时同时启用。
2. 消息归档
2.1 功能说明
消息归档工具用于对当前上下文中已产生但不再直接使用的工具执行结果执行归档。被归档的结果不再占用模型上下文，但仍保留在会话状态中，必要时可恢复。
适合归档的内容包括：
- 已完成且与当前任务步骤无关的工具输出
- 内容较长、但关键信息已通过摘要提取的结果
- 临时查询过、后续大概率不再使用的文件或日志内容
不会被归档的内容包括：
- 内容较短（不超过 100 字符）的结果
- 当前推理仍依赖其结果的工具输出
2.2 界面反馈
当归档一批工具结果时，界面将显示：
⎿ Archived 3 tool result(s) |
当恢复已归档的结果时，界面将显示：
⎿ Unarchived 2 tool result(s) |
2.3 使用价值
- 降低上下文消耗：避免大段文件内容、日志输出长期滞留于对话上下文中。
- 自动化决策：当上下文规模增大时，Hawa Code 会主动判断并归档低相关性的结果。
- 可逆操作：已归档的结果在后续需要时可自动恢复。
3. 消息卸载
3.1 功能说明
消息卸载工具用于将跨多轮对话所需的关键信息保存到磁盘，例如分析结论、执行计划、错误记录或核心发现。写入后，完整内容会从当前上下文中移除，仅保留简短摘要；需要详细内容时可随时读取。
3.2 操作类型
消息卸载工具支持以下操作：
| 操作 | 用途 |
|---|---|
write |
写入或覆盖一条消息卸载。需提供 key、summary 和 content |
list |
列出当前会话中所有消息卸载，按最近更新时间倒序排列 |
read |
读取指定 key 的完整消息卸载内容 |
delete |
删除指定 key 的消息卸载 |
3.3 消息卸载结构
每条消息卸载由以下字段构成：
- key：消息卸载的唯一标识，例如
auth-flow-analysis - summary：不超过 300 字符的摘要，保留在上下文中用于快速判断是否需要读取
- content：消息卸载的完整内容，可包含任意长度的分析结果
3.4 存储路径
消息卸载的内容以 Markdown 文件形式持久化存储，其默认路径为：
~/.hcode/projects/{project-dir}/notes/{session-id}/{key}.md |
其中：
{project-dir}：当前工作目录转换后的项目目录名{session-id}：当前会话的唯一标识{key}：消息卸载的唯一标识
同一项目、同一会话下的所有消息卸载还会维护一份索引文件：
~/.hcode/projects/{project-dir}/notes/{session-id}/index.json |
消息卸载文件在本地磁盘中长期保留，只要不清除缓存或手动删除文件，内容即可在后续会话中继续使用。
3.5 使用价值
- 跨轮复用：即使会话已进行多轮，仍可精准调取先前保存的结论。
- 释放上下文空间：长篇分析仅保留摘要，降低持续推理时的上下文负担。
- 自动去重：相同
key重复写入将覆盖旧内容，不会重复计入消息卸载数量。 - 容量管理：每个会话最多保存 50 条消息卸载，达到上限后需手动删除过期内容。
4. 协同使用
消息归档与消息卸载可在复杂任务中按以下方式协同使用：
- 分析阶段：使用消息卸载保存代码结构、调用关系、关键发现等结构化结论。
- 执行阶段：使用消息归档对已读取完毕的消息卸载列表或消息卸载内容执行归档。
- 复用阶段：需要时通过
read操作重新加载相关消息卸载，使用完毕后再次归档。
两者的定位可概括为：
- 消息归档：将暂时不用的对话内容归档，保持当前上下文整洁。
- 消息卸载：将重要结论持久化到磁盘，需要时按需读取。
5. 总结
消息归档与消息卸载共同构成了 Hawa Code 的上下文管理机制。前者用于控制当前会话的上下文体积，后者用于在会话周期内保存和复用关键知识。在处理长对话、代码分析、多步骤开发等场景时，同时启用两项工具可显著提升会话的清晰度与持续性。