omp-context

让 OMP agent 主动整理自己的上下文，同时保留可恢复的会话历史。

它解决什么问题

长任务会积累大量已消化的日志、试错和中间结果。OMP 原生 compaction 能在窗口压力下压缩历史，但它是面向容量恢复的单向摘要。omp-context 增加一套可逆的主动整理机制：agent 自己判断何时保存、观察或折叠上下文，原始路径仍留在会话树中。

一句话：OMP compaction 负责兜底，omp-context 负责可恢复地整理工作集。

三个工具

工具	一句话
acm_checkpoint	给一个会话节点添加语义化存档名，不改变当前上下文。
acm_timeline	查看当前主干和存档点，搜索整棵历史树，或只读打开一个节点的完整文本。
acm_travel	把已消化过程折叠为结构化 handoff，并保留原始历史用于恢复。

安装后 agent 会根据正典 guidance 自主使用；也可以直接要求“存个档”“看看时间线”或“恢复到某个点”。

找旧细节时按最轻的路径取回：先用 timeline search 定位；一个节点就够时，用 view=node 读取完整文本，当前分支不会改变；只有需要整条归档分支作为上下文时才 travel。search 的工作量有四层边界：每次最多扫描 5,000 个节点、每个节点最多读取 65,536 个 source chars、全调用最多读取 2,000,000 个 source chars，最后再受结果条数和当前上下文输出预算约束。取消、扫描上限、文本上限和输出 fitting 会分别标明；部分搜索不会伪装成“全树没有结果”。

Handoff

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 只有在 matching、non-error、mutationStatus: applied 的 finalized travel receipt 后才切换；拒绝的 receipt 会终止 ticket。旧 compact packet 也只有在它与当前 provider 前缀可验证衔接、合并后协议仍有效时才复用，否则保留并修复当前 run 的消息，不会盲目重放旧 cache。native AgentSession replacement 仍只在 OMP session_stop 且会话确实 idle、无 pending message 时执行。
• 扩展默认在 PI_CODING_AGENT_DIR/state/acm-boundary-ledger.jsonl（未设置时回退到 ~/.pi/agent/state/）异步追加匿名运行计数：时间、压力百分比、消息/存档数量、gauge cohort、CORE digest 和 provider/id 模型标识；不含对话正文，也不上传。队列最多 256 行、单行 16 KiB、文件 8 MiB。同一 lock protocol 的进程通过固定 owner marker 串行写入，不抢占遗留锁，也不降级为无锁写入；marker token 只能在检查点 best-effort 发现替换，不承诺抵抗有权限在检查与 I/O 之间任意删除/替换 pathname 的外部进程——该残余风险最多影响本地诊断行的顺序、丢失或文件上限，不影响工具结果。session_shutdown 最多等待约 500ms；超时或写入异常同样只会计数并丢弃诊断行。设 ACM_LEDGER_DISABLED=1 可完全关闭。

OMP 兼容契约

当前发布 omp-context 0.5.0，精确支持并测试 OMP 18.0.0：

• @oh-my-pi/pi-agent-core
• @oh-my-pi/pi-ai
• @oh-my-pi/pi-coding-agent
• @oh-my-pi/pi-tui

Fold/travel 的 token 投影使用 OMP 18 的 model-aware Tokenizer：同一会话按 tokenizer family 复用计数缓存，模型族变化时切换，无法读取模型时使用安全的近似计数。

工具参数使用 OMP 注入的 omptype-backed 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
bun run bench             # 17 个 deterministic hot-path host-read / CPU / retention 场景

完整 gate 包含 guidance 一致性、根测试、TypeScript 类型检查，以及真实 OMP 18.0.0 host fixture。架构、host 兼容性契约、文案宪法与维护规则见 AGENTS.md。

运行时 cache 按 SessionManager 隔离；travel、tree navigation、compaction、session reset 和 tokenizer family 变化都会使相应层失效。benchmark 的 wall time 只作诊断，cache correctness 与 host-read 次数由 deterministic tests 锁定。

来源

本项目将 KorenKrita/pi-context 的 ACM 行为移植到 OMP，并针对 OMP 生命周期、schema、rendering 和 session API 做宿主适配。

MIT License