上下文压缩器（Context Compactor）

将长对话压缩为结构化摘要。通过用高密度、可检索的摘要替代原始对话历史，显著节省 token 消耗。

运行要求

• 运行时环境：Python 3.10+（仅标准库）
• 操作系统：Linux、macOS
• 环境变量：
  • OPENCLAW_WORKSPACE — 工作区根目录（默认值：~/.openclaw/workspace）
• 环境：OPENCLAW_WORKSPACE（默认值：~/.openclaw/workspace）

安全规范

写入限制（硬性规则）

Agent 仅允许向以下位置写入：

• memory/compacts/ — 仅限 compact 文件
• SESSION-STATE.md — 仅可通过 smart-memory 技能（非本技能）写入

Agent 绝对禁止写入以下位置：

• 工作区以外的任意目录
• 系统目录（如 /etc、/usr、/var、/tmp（会话缓存除外））
• 用户主目录根路径（如 ~/.ssh、~/.config、~/.aws 等）
• 工作区根目录下任意以 .* 开头的隐藏文件或隐藏目录
• 任何不匹配 memory/compacts/*.md 模式的文件

读取限制

Agent 仅允许从以下位置读取：

• 当前对话上下文（已自动提供）
• memory/compacts/ — 用于列出或读取历史 compact 文件

Agent 绝对禁止读取以下内容：

• /etc/passwd、/etc/shadow 或任何系统凭证文件
• ~/.ssh/、~/.aws/、~/.config/openclaw/ 或类似路径
• 工作区以外的任意文件（除非用户明确要求）

脱敏执行检查表

在写入任意 compact 文件前，Agent 必须完成以下检查清单：

1. ✅ 移除所有文件路径（替换为 ）
2. ✅ 移除所有 URL（替换为 ）
3. ✅ 移除所有内网 IP 地址（替换为 ）
4. ✅ 彻底删除所有密码、token、API 密钥
5. ✅ 不包含超出工作上下文的个人身份信息

若任一检查项未通过 → 必须修复后方可写入 compact。

隐私边界

Compact 文件允许包含的内容

• 决策结论、已确认事实、待办事项、阻塞问题
• 项目名称与功能描述

Compact 文件严禁包含的内容

• 文件系统路径（统一使用 占位符）
• 内网 URL、服务端点或基础设施细节
• API 密钥、token、密码、密钥等敏感凭据（脚本级正则过滤）
• 私钥或证书
• 超出工作上下文的用户个人信息

Agent 行为准则

• 保存 compact 前，必须清除或脱敏所有路径、内网 URL 与凭证信息
• 推荐使用标准化占位符：、、
• 对是否敏感存疑的内容，一律执行脱敏
• compact 的核心是记录“做了什么决策”，而非“资源部署在哪”

数据隔离机制

• 关键词提取：完全本地化 —— 无网络请求、无外部数据传输
• LLM 提取（可选）：将对话文本发送至 Agent 配置的 LLM 服务商。该行为属于使用任意基于 LLM 的压缩方案的固有特性，不由本技能控制。本技能仅提供 prompt 模板；实际 API 调用由 Agent / 平台层处理。
• 最多保留 30 个 compact 文件，超限时自动删除最旧者
• compact 文件全程本地存储、本地读取 —— 本技能自身绝不发起任何网络调用

工作原理

长对话（10,000+ tokens）
    ↓
compact_session.py --extract
    ↓
结构化摘要（约 500 tokens）
    ↓
保存至 memory/compacts/YYYY-MM-DD-HHMM.md
    ↓
新会话启动时自动加载最新 compact

压缩比：约 20:1 —— 10,000 token 对话压缩为约 500 token 摘要。

快速参考

压缩执行机制：Agent 先草拟 compact 内容，再通过管道传入 --write 参数执行写入。该参数强制实施全部安全校验（路径/URL/IP/密钥脱敏），校验通过后才落盘。此设计确保安全策略由程序强制执行 —— Agent 永远不会直接写入磁盘。

Compact 文件格式

# Session Compact — 2026-03-31 17:00 UTC
**Turns**: 45 | **Est. tokens saved**: ~9,500

## Decisions Made
- [2026-03-31] Chose SQLite over Redis for golden3 prompts
- [2026-03-31] Decided to use zero-dependency approach for smart-memory

## Facts Established
- [PROJ] golden3 site at golden3.killclaw.xyz, repo github.com/zgjq/golden3
- [TECH] Prompts stored in data/golden3.db, table `prompts`, category `scoring`
- [PREF] User prefers direct, no-nonsense communication style

## Pending Actions
- [ ] Publish smart-memory to ClawHub
- [ ] Fix scoring display from 100-point to 10-point scale

## Technical Context
- Server: ubuntu-4gb-hel1-1, Node v24.14.0
- Golden3 uses node:sqlite (DatabaseSync)

## Blockers / Open Questions
- Need ClawHub login token to publish

## Session Summary
Built smart-memory skill from Claude Code architecture study. Published to ClawHub
as smart-memory-zero-dep. Memory system now active with WAL protocol, type
classification, temporal decay, and snapshot/restore.

Agent 行为规范

何时触发压缩

• 对话轮次超过约 50 轮
• 上下文窗口接近容量上限（参见 AGENTS.md 中关于 token 使用纪律的规则）
• 用户发出指令：“compact”、“summarize”、“fresh start”、“压缩”

如何执行压缩

Agent 草拟 compact 内容后，通过以下方式保存：

echo "compact content" | python3 scripts/compact_session.py --write

--write 参数以编程方式强制执行全部安全校验：路径/URL/IP/密钥脱敏、写入路径限定于工作区范围内、文件命名合规。Agent 永远不会直接写入磁盘。

何时注入 compact 内容

• 新会话启动时 —— 自动检测是否存在近期 compact
• 用户询问 “what were we working on”
• 上下文搜索无结果，但存在可用 compact

提取规则

从对话中提取以下五类信息：

1. 决策（Decisions） —— 包含 “chose X over Y”、“decided to”、“going with” 等明确判断表述
2. 事实（Facts） —— URL、文件路径、配置项、技术细节、用户偏好等客观信息
3. 待办（Pending） —— 未完成任务，含 “later”、“TODO”、“next step” 等关键词
4. 阻塞项（Blockers） —— “need X first”、“blocked by”、“waiting for” 等依赖声明
5. 概览（Summary） —— 2–3 句简明总结本次会话核心进展

以下内容应跳过提取：

• 问候语、寒暄、简单应答（如 “ok”、“嗯”）
• 已在 MEMORY.md 中存在的重复信息
• 调试过程中的冗余日志（除非该过程引出明确经验教训（LESSON））
• 敏感数据（token、密码等）

与 smart-memory 的集成

本技能与 smart-memory 协同工作：

• compact 文件引用 smart-memory 分类系统中的 [TYPE] 标签
• compact 中的待办事项可导入 wal pending 队列
• compact 中的关键事实可提升至 MEMORY.md
• compact 文件存放于 memory/compacts/ 目录 —— 由 smart-memory 的归档系统进行时效衰减管理

文件结构

~/.openclaw/workspace/
├── memory/
│   └── compacts/
│       ├── 2026-03-31-1700.md   # Session compact
│       ├── 2026-03-30-1430.md
│       └── ...