让 OMP agent 主动整理自己的上下文，同时保留可恢复的会话历史。
长任务会积累大量已消化的日志、试错和中间结果。OMP 原生 compaction 能在窗口压力下压缩历史，但它是面向容量恢复的单向摘要。omp-context 增加一套可逆的主动整理机制：agent 自己判断何时保存、观察或折叠上下文，原始路径仍留在会话树中。
一句话：OMP compaction 负责兜底，omp-context 负责可恢复地整理工作集。
| 工具 | 一句话 |
|---|---|
acm_checkpoint |
给一个会话节点添加语义化存档名，不改变当前上下文。 |
acm_timeline |
查看当前主干、存档点、搜索结果和会话树证据。 |
acm_travel |
把已消化过程折叠为结构化 handoff，并保留原始历史用于恢复。 |
安装后 agent 会根据正典 guidance 自主使用；也可以直接要求“存个档”“看看时间线”或“恢复到某个点”。
acm_travel 使用固定七字段交接单：
{
"goal": "完成 parser 迁移并保持现有行为。",
"state": "实现已完成，测试通过；仍需更新 README 示例。",
"evidence": "bun test；src/parser.ts；test/parser.test.ts",
"external": "src/parser.ts 已修改，尚未提交。",
"exclusions": "不再尝试 recursive-descent 方案。",
"recover": "parser-raw",
"next": "更新 README 中的 parser 示例。"
}- goal / state / next 必填：目标是什么、现在什么状态、下一步做什么。
- evidence / external / exclusions / recover 可选：证据在哪、改过哪些文件、放弃过哪些方向、想回头时去哪——用到才写，省略自动记为
none。简单场景三个字段就够。 - 每次折叠都会自动给折叠前的位置记一张"回程票"（archive alias），写进 Recover 行——想找回原文时直接 travel 过去。
合格标准是一个不知道前情的新 agent 能仅靠 handoff 和其中的指针继续工作。
非 ACM 工具结果末尾会带一行仪表（出错的结果除外）。大窗口模型上：
[ctx 75% budget(400K) · 300K/1M window · boundary · 3pts · fold@turn→24% -38msg · fold@task→11% -92msg]
小窗口（不超过 400K）模型上：
[ctx 43% window · 86K/200K · boundary · 3pts · fold@turn→24% -38msg]
行首的压力百分比自带它所度量的尺名，折叠针读数继承同一把尺：budget(400K) 是注意力预算（模型窗口和 400K 取小），大窗口上可以超过 100%，不截断；window 直接对着物理窗口读，100% 就是硬墙。旁边的裸 token 数（已用/窗口）始终报告对物理窗口的绝对位置——那是硬上限。然后是 boundary 标记（每个新请求的首次读数）、路径上的存档数，以及两根折叠针——折到上一段开头 / 折到最早存档点，各自显示折后剩余压力和会折掉的消息数。整数位变了才显示，每个新请求的首次读数必显示。
它只报数，从不建议做什么——什么时候整理，是 agent 自己的判断。设 ACM_GAUGE_DISABLED=1 可以关掉。
从 Git 仓库安装：
omp install github:KorenKrita/omp-context本地开发可在仓库目录安装：
bun install
omp install .- Travel 只改变 OMP 会话树及后续模型上下文，不回滚文件、进程、Git 提交或外部系统。
- 原始历史留在树中；checkpoint、节点 ID 或 raw archive alias 可用于恢复。
- 扩展不替代 OMP 原生 compaction。
- 变更返回
applied、not_applied或indeterminate等可核对结果，不把未知状态伪装成成功。 - Provider context 可在 finalized travel receipt 后切换；native AgentSession replacement 只在 OMP
session_stop且会话确实 idle、无 pending message 时执行。
当前精确支持并测试 OMP 17.2.1：
@oh-my-pi/pi-agent-core@oh-my-pi/pi-ai@oh-my-pi/pi-coding-agent@oh-my-pi/pi-tui
工具参数使用 OMP 注入的 pi.zod 严格 schema；Pi-only prompt metadata（promptSnippet/promptGuidelines）等价注入 before_agent_start.systemPrompt；Pi 的 agent_settled 语义映射到 OMP 原生 session_stop。
bun install --frozen-lockfile
bun run verify:acm完整 gate 包含 guidance 一致性、根测试、TypeScript 类型检查，以及真实 OMP 17.2.1 host fixture。架构、host 兼容性契约、文案宪法与维护规则见 AGENTS.md。
本项目将 KorenKrita/pi-context 的 ACM 行为移植到 OMP，并针对 OMP 生命周期、schema、rendering 和 session API 做宿主适配。
MIT License