smartcompact 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +8 -5
- package/README.zh-CN.md +8 -5
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -6,12 +6,15 @@
|
|
|
6
6
|
[](https://github.com/coffeecoproject/SmartCompact/stargazers)
|
|
7
7
|
[](https://github.com/coffeecoproject/SmartCompact/blob/main/LICENSE)
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
<p align="center"><a href="https://github.com/coffeecoproject/SmartCompact/raw/main/docs/media/smartcompact-en.mp4"><img src="https://raw.githubusercontent.com/coffeecoproject/SmartCompact/main/docs/media/cover-en.jpg" alt="SmartCompact in 90 seconds (video)" width="100%"></a></p>
|
|
10
|
+
<p align="center"><sub>▶ Watch the 90-second explainer (click the image to play)</sub></p>
|
|
11
|
+
|
|
12
|
+
**SmartCompact lets long coding-agent sessions compact earlier, at a pause after a piece of work is finished.** On 18–60 consecutive coding tasks it cut cost by **7–44%** with no loss in hidden acceptance tests; the longer the session, the more it saves. In the longest runs (60 tasks, native sessions reaching 820k–960k tokens) the model missed 6 of 180 recall questions about details mentioned in passing much earlier ([test report](https://github.com/coffeecoproject/SmartCompact/blob/main/docs/TEST-REPORT.md), in Chinese).
|
|
10
13
|
|
|
11
14
|
Every request re-reads the whole context, so a long context makes every step expensive. Native auto-compaction waits until the context is nearly full (close to 1M tokens in Claude Code, up to 800k in Codex if configured), and it ignores timing, so it often lands in the middle of a task. SmartCompact works with Claude Code (CLI and desktop app), [Pi](https://github.com/earendil-works/pi) and the Codex CLI:
|
|
12
15
|
|
|
13
|
-
- **Compact at
|
|
14
|
-
- **Never in the middle of work.** It
|
|
16
|
+
- **Compact at a good moment.** Once the context passes the **allow line** (200k tokens by default), it compacts when a turn ends, if a piece of work has been finished since the last compaction (a commit, tests passing, a task completed).
|
|
17
|
+
- **Never in the middle of work.** It only decides when a turn ends, never mid-turn, and it waits while tests or the build are failing, errors keep repeating, or a background job is running.
|
|
15
18
|
- **A fallback.** If no good moment comes and the context passes the **grace line** (allow line × 1.3), it compacts at the end of a turn.
|
|
16
19
|
- **A progress ledger bridges the gap.** Files changed, the latest commit and test result, and decisions the agent recorded are handed back to the model after compaction.
|
|
17
20
|
- **No pointless compactions.** It skips compaction when it would not free enough space.
|
|
@@ -64,7 +67,7 @@ Codex hooks cannot postpone a compaction in the middle of a turn, so SmartCompac
|
|
|
64
67
|
|
|
65
68
|
| Setting | Default | Meaning |
|
|
66
69
|
|---|---|---|
|
|
67
|
-
| Allow line | 200000 | Above it, compact
|
|
70
|
+
| Allow line | 200000 | Above it, compact when a turn ends once a piece of work has been finished |
|
|
68
71
|
| Grace factor | 1.3 | Above allow line × factor, stop waiting for a finished piece of work |
|
|
69
72
|
| Minimum freed | 60000 | Skip compaction if it is expected to free less than this |
|
|
70
73
|
|
|
@@ -79,7 +82,7 @@ Codex hooks cannot postpone a compaction in the middle of a turn, so SmartCompac
|
|
|
79
82
|
|
|
80
83
|
## FAQ
|
|
81
84
|
|
|
82
|
-
**How does it know a piece of work is finished?** From the commands the agent runs. A commit counts if `git commit` actually ran and the tool call did not fail. A test command piped into something else (`| tail`) without `pipefail` does not count, since its exit code cannot be trusted.
|
|
85
|
+
**How does it know a piece of work is finished?** From the commands the agent runs. Any finished piece of work since the last compaction counts, not only one in the current turn: the end of a turn is already a pause, so waiting for the next commit would mostly just cost more. A commit counts if `git commit` actually ran and the tool call did not fail. A test command piped into something else (`| tail`) without `pipefail` does not count, since its exit code cannot be trusted.
|
|
83
86
|
|
|
84
87
|
**Will the model forget things after compaction?** Sometimes, for details mentioned in passing. The ledger only records files, commits, tests and decisions the model chose to record. Details the user mentions in passing are kept by asking the compaction summary to keep every specific fact the user stated. On Pi this clearly reduced losses, but it is not a guarantee.
|
|
85
88
|
|
package/README.zh-CN.md
CHANGED
|
@@ -6,12 +6,15 @@
|
|
|
6
6
|
[](https://github.com/coffeecoproject/SmartCompact/stargazers)
|
|
7
7
|
[](https://github.com/coffeecoproject/SmartCompact/blob/main/LICENSE)
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
<p align="center"><a href="https://github.com/coffeecoproject/SmartCompact/raw/main/docs/media/smartcompact-zh.mp4"><img src="https://raw.githubusercontent.com/coffeecoproject/SmartCompact/main/docs/media/cover-zh.jpg" alt="90 秒看懂 SmartCompact（视频）" width="100%"></a></p>
|
|
10
|
+
<p align="center"><sub>▶ 90 秒动画介绍（点击图片播放）</sub></p>
|
|
11
|
+
|
|
12
|
+
**SmartCompact 让编程 agent 的长会话早点压缩，挑在做完一件事之后的停顿处。** 在 18～60 个连续开发任务上，成本降低 **7%～44%**，隐藏验收测试没有损失，会话越长省得越多。最长的一组（60 个任务，原生组上下文到 82 万～96 万）里，很早之前随口提到的细节，180 道记忆题少答对 6 道（[测试报告](https://github.com/coffeecoproject/SmartCompact/blob/main/docs/TEST-REPORT.md)）。
|
|
10
13
|
|
|
11
14
|
agent 每发一次请求，都要把整段上下文重新读一遍，上下文越长，每一步越贵。原生的自动压缩要等到快满了才触发（Claude Code 接近 100 万，Codex 可以配到 80 万），而且不看时机，常常发生在一件事做到一半的时候。SmartCompact 支持 Claude Code（终端和桌面 App）、[Pi](https://github.com/earendil-works/pi) 和 Codex 命令行：
|
|
12
15
|
|
|
13
|
-
- **挑对时机压缩。** 上下文超过**允许压缩线**（默认 20
|
|
14
|
-
- **不在做到一半时压缩。**
|
|
16
|
+
- **挑对时机压缩。** 上下文超过**允许压缩线**（默认 20 万）以后，只要上次压缩以来做完过一件事（一次提交、测试通过、任务完成），就在这一轮结束时压缩。
|
|
17
|
+
- **不在做到一半时压缩。** 只在一轮结束时判断，从不在一轮中间主动压缩；测试失败、构建失败、连续报错或后台任务还在跑时先等着。
|
|
15
18
|
- **有兜底。** 一直等不到合适时机、上下文超过**宽限线**（允许压缩线 × 1.3）时，在一轮结束时压缩。
|
|
16
19
|
- **用进度笔记接上。** 改过的文件、最近的提交和测试结果、记下的决定，压缩后补回给模型。
|
|
17
20
|
- **不做白费的压缩。** 预计腾不出足够空间时不压缩，避免刚压缩完又压缩。
|
|
@@ -64,7 +67,7 @@ Codex 的 hook 不能推迟一轮中间的压缩，所以插件在一轮结束
|
|
|
64
67
|
|
|
65
68
|
| 参数 | 默认 | 含义 |
|
|
66
69
|
|---|---|---|
|
|
67
|
-
| 允许压缩线 | 200000 |
|
|
70
|
+
| 允许压缩线 | 200000 | 超过它、做完过一件事后，在一轮结束时压缩 |
|
|
68
71
|
| 宽限倍数 | 1.3 | 超过 允许压缩线 × 倍数 时不再等刚做完一件事 |
|
|
69
72
|
| 最少腾出空间 | 60000 | 预计腾出的空间少于它时不压缩 |
|
|
70
73
|
|
|
@@ -79,7 +82,7 @@ Codex 的 hook 不能推迟一轮中间的压缩，所以插件在一轮结束
|
|
|
79
82
|
|
|
80
83
|
## 常见问题
|
|
81
84
|
|
|
82
|
-
**怎么判断"
|
|
85
|
+
**怎么判断"做完一件事"？** 靠识别 agent 执行的命令。看的是上次压缩以来有没有做完过一件事，不要求正好在这一轮：一轮结束本身就是停顿点，非要等下一次提交，多半只是多花钱。提交只要真的执行了 `git commit` 且工具调用没报错就算；测试命令接了管道（`| tail`）又没开 `pipefail` 时退出码不可信，不算测试结果。
|
|
83
86
|
|
|
84
87
|
**压缩后模型会不会忘事？** 随口提到的细节有时会丢。进度笔记只记文件、提交、测试和模型主动记下的决定。用户在对话里随口交代的细节，靠压缩时要求摘要原样保留用户说过的具体信息。Pi 上这样做明显减少了丢失，但不能保证不丢。
|
|
85
88
|
|
package/package.json
CHANGED