1 +#
Decay Compaction Extension Plan 4 +**Status:** Implemented; release gate passed
5 +**Extension:** `decay`
6 +**Objective:** Replace Pi's default summary strategy with recency-weighted structured compaction, a configurable model, observable classification progress, and a responsive nonmodal terminal animation.
10 +This document is the binding Decay design and implementation plan.
11 +Implementation may change only after this document changes deliberately.
15 +- [Animated browser mockup](./2026-08-22-decay-compaction-mockup.html)
16 +- [Runnable terminal experiment](./2026-08-22-decay-compaction-experiment.mjs)
21 +node docs/super/plans/2026-08-22-decay-compaction-experiment.mjs
24 +Run its deterministic checks:
27 +node docs/super/plans/2026-08-22-decay-compaction-experiment.mjs --self-test
30 +The browser mockup establishes composition and motion.
31 +The terminal experiment is authoritative for terminal-cell behavior, current labels, responsive sizing, and repaint strategy.
35 +Decay intercepts `session_before_compact` and returns a custom `CompactionResult`.
36 +It preserves Pi's prepared `firstKeptEntryId`, so Pi still retains approximately `compaction.keepRecentTokens`, 20,000 by default, verbatim.
37 +It replaces only the summary-generation strategy.
39 +Decay has three visible differences from default compaction:
41 +1. A fixed recency-and-recurrence strategy.
42 +2. An extension-owned model setting.
43 +3. A passive progress animation above Pi's editor followed by a compact completion notification.
45 +Any non-abort Decay failure returns `undefined` from the hook so Pi runs default compaction.
46 +A user cancellation returns `{ cancel: true }` and never starts default compaction behind the cancellation.
50 +Decay reads merged global and project Pi settings through `SettingsManager.create(ctx.cwd)`.
51 +Project settings override global settings.
56 + "model":
"openai-codex/gpt-5.6-luna" 61 +`decay.model` accepts `provider/model`, `null`, or omission.
62 +`null` and omission use `ctx.model`, the current session model.
63 +A configured string resolves through `ctx.modelRegistry`.
64 +An invalid or unavailable configured model warns and falls back to Pi's default compaction rather than silently selecting another model.
66 +The real global setting will use `openai-codex/gpt-5.6-luna`.
70 +Decay summarizes an agentic coding session with recency bias.
71 +Newer information receives more summary budget than older information.
72 +Meaningful semantic recurrence increases budget.
73 +Repeated raw tool output never increases recurrence.
75 +The following information is protected from decay:
77 +- User laws and constraints.
78 +- Decisions and their rationale.
79 +- Active goals and current state.
80 +- Unresolved blockers and questions.
81 +- Exact paths, identifiers, commands, and error messages required to continue.
83 +Stale and superseded implementation detail collapses first.
84 +The newest confirmed state overrides conflicting older state.
86 +###
Permanent and one-run instructions 88 +Strategy instructions are permanent Decay policy.
89 +Manual instructions come from `/compact ...` and apply only to that compaction.
90 +They remain separate prompt sections because one-run focus must not mutate permanent policy.
92 +The classifier and summarizer receive manual instructions as explicit untrusted focus text.
93 +Conversation content and manual focus never become executable system instructions.
99 + ├─ messagesToSummarize
100 + ├─ turnPrefixMessages
103 + ├─ firstKeptEntryId
107 +numbered deterministic source chunks
110 +classifier model stream
111 + └─ one record_chunk tool call per chunk
114 +validated canonical JSONL
115 + ├─ passive widget progress
116 + └─ current memory atoms
118 +previous Decay atoms from CompactionEntry.details
121 +deterministic merge, scoring, and budget allocation
124 +summarizer model call
127 +model summary + deterministic file appendix
130 +CompactionResult + structured Decay details
133 +The two model phases are intentional.
134 +The classifier creates inspectable structured memory and honest chunk progress.
135 +The summarizer converts already-ranked memory into concise continuation prose.
139 +Local code creates numbered chunks before any model call.
140 +Chunks preserve message order and never split a message content block.
141 +A split-turn prefix remains tagged as `split-prefix`.
142 +Normal discarded history remains tagged as `history`.
144 +Pi creates a split turn when one user, assistant, and tool sequence exceeds the retained-token budget and the cut lands inside that turn.
145 +`turnPrefixMessages` are the discarded beginning while the suffix remains verbatim after `firstKeptEntryId`.
146 +Decay classifies the prefix so the retained suffix remains understandable.
148 +The target size is 6,000 estimated tokens, but one oversized message remains intact.
149 +Each chunk allows at most 16 atoms, each key at most 120 characters, and each text at most 600 characters.
150 +The chunk count is known before classification and is the progress denominator.
151 +The classifier sees all numbered chunks in one request so it can detect semantic recurrence across chunks.
153 +##
Classifier contract 155 +The classifier receives exactly one tool definition named `record_chunk`.
156 +It must call that tool once for every numbered chunk.
157 +It may call chunks in any order.
158 +Local reconciliation sorts by chunk number.
160 +The TypeBox parameter schema requires:
162 +- `chunk`: integer chunk number.
163 +- `of`: total chunk count.
164 +- `atoms`: classified semantic memory atoms.
168 +- Stable semantic key.
169 +- Concise factual text.
170 +- Kind such as constraint, decision, goal, state, blocker, exact literal, or ordinary context.
171 +- Locally assigned chunk provenance.
172 +- Active or superseded state.
174 +The stable semantic key is also the recurrence key.
175 +On repeated Decay compactions, the classifier receives a prior-atom identity catalog containing only key, text, kind, and status.
176 +The catalog is capped at 128 atoms and 32,000 serialized characters, ranking active, protected, recent, and recurring atoms first.
177 +A catalog entry is not a source occurrence and does not increase frequency by itself.
178 +The classifier must reuse an exact catalog key for a semantic match, including paraphrases, and mint a new key only when no catalog atom matches.
183 +constrainedSampling: {
type:
"json_schema",
strict:
"prefer" }
186 +`prefer` enables provider-side constrained JSON Schema sampling when supported and ordinary tool calling otherwise.
187 +Local TypeBox validation remains authoritative in both cases.
188 +Text outside tool calls is ignored for records and causes classification failure when required coverage is absent.
190 +Every chunk must appear exactly once with the expected `of` value.
191 +The classifier does not emit source positions because recurring atoms otherwise tempt models to reuse provenance from earlier chunks.
192 +Local code assigns each accepted atom its chunk's first source position.
193 +Unknown fields, invalid records, duplicates, and missing coverage fail classification.
194 +Decay performs no repair-model call in v1.
195 +Failure clears the widget, removes temporary data, warns once, and delegates to default compaction.
197 +##
Streaming and JSONL 199 +Decay resolves the selected model and provider through `ctx.modelRegistry`.
200 +Every registered Pi AI provider exposes `stream` and `streamSimple`.
201 +Decay resolves auth through `ctx.modelRegistry.getApiKeyAndHeaders()` and streams through the owning provider without changing Pi APIs.
203 +Only finalized, TypeBox-valid tool arguments become records.
204 +Partial model bytes never reach disk.
205 +Decay canonicalizes each accepted record with `JSON.stringify()` and appends one newline.
207 +The file lives in a run-specific directory created with Node's OS temporary-directory APIs.
208 +The JSONL file is created with mode `0600` where the platform supports POSIX modes.
209 +The directory and file are removed in `finally` on success, failure, and cancellation.
210 +No session text enters logs or notifications.
212 +The progress reader tails appended JSONL, handles coalesced filesystem notifications by reading from its last byte offset, and performs a final drain before classification reconciliation.
213 +Progress is the count of unique valid chunks divided by total chunks.
219 +This is real output progress, not an estimate of hidden model computation.
221 +##
Structured memory and recency 223 +A prose previous summary cannot carry reliable recency metadata.
224 +Decay therefore stores structured memory in `CompactionEntry.details` while still returning ordinary Markdown summary text to Pi.
243 +The next Decay run reads the latest Decay details from `branchEntries` and merges them with current classifier records.
244 +`firstSeen` and `lastSeen` are monotonic source ordinals, so recency distinguishes chunks inside one compaction as well as later compactions.
245 +Current records update `lastSeen` and `seenCount` by semantic key.
246 +The same key can increase `seenCount` at most once per chunk, so duplicate atoms inside one classifier record gain no weight.
247 +Conflicting current active state supersedes older state.
248 +Unmatched prior atoms age normally.
250 +An existing non-Decay previous summary has no structured details.
251 +The first Decay run classifies that summary once as the oldest source epoch so enabling Decay does not erase earlier compacted context.
252 +Future Decay runs use structured details.
254 +###
Deterministic weighting 256 +The model does not decide what recency means.
257 +Local code computes atom age and recurrence from stored metadata.
259 +For newest source ordinal `N`, an atom's recency is `1 / (1 + (N - lastSeen))`.
260 +Its recurrence factor is `1 + min(2, log2(max(1, seenCount)))`.
261 +Its ordinary weight is recency multiplied by recurrence.
263 +The output limit is 80 percent of Pi's reserve-token setting, capped by the model maximum.
264 +Seventy-five percent of that output limit is the memory allocation budget.
265 +Protected kinds enter before ordinary weighted allocation and receive between 24 and 128 tokens each.
266 +Ordinary atoms divide the remaining budget proportionally by weight and receive at most 128 tokens each.
267 +Superseded atoms receive no allocation.
268 +Repeated raw tool output never changes `seenCount` because classifier policy forbids it and local merge counts a key at most once per chunk.
270 +These constants live beside tests as exported data, not prompt folklore.
271 +Changing them changes Decay behavior and requires updating this plan.
273 +##
Summarizer contract 275 +The summarizer receives:
277 +- Permanent strategy instructions.
278 +- One-run manual instructions when present.
279 +- Already-merged, ranked, and budgeted memory atoms.
280 +- Split-prefix facts already represented on atoms.
282 +The summarizer does not receive raw file-operation sets.
283 +It does not decide recency scores, recurrence counts, protected status, or token allocation.
284 +It formats selected memory into continuation-ready Markdown.
286 +The summarizer may use `ctx.modelRegistry.complete()` because merge progress is indeterminate.
287 +The UI switches from determinate `CLASSIFY n/N` to indeterminate `MERGE` while retaining the real elapsed timer.
289 +An empty summary, tool call, provider error, abort, or malformed terminal response fails Decay.
290 +Classifier and summarizer usage are combined and returned in `CompactionResult.usage`.
294 +File operations are machine facts.
295 +Decay carries prior Decay file lists forward, merges the current preparation's `read`, `written`, and `edited` sets locally, sorts them, and appends the file section deterministically after the model summary.
296 +The summarizer never receives or rewrites that appendix.
300 +The production UI is a Pi TUI component, not raw ANSI terminal control.
301 +The MJS experiment proves the original motion vocabulary and repaint contract only; the passive widget is authoritative for production composition.
303 +Decay installs a passive `ctx.ui.setWidget()` component above Pi's editor during its hook.
304 +The widget never receives focus or implements keyboard handling, so Pi's editor remains active while compaction runs.
305 +Submitting with Enter uses Pi's native compaction queue for steering messages.
306 +Escape uses Pi's native compaction abort handler, which aborts the event signal and both model phases.
308 +The normal widget is exactly eight lines high.
309 +Two fragmented history rows retain the old-to-new texture, a transfer lane carries animated cells, a sorted summary bank accumulates accepted chunks, and the retained 20,000-token region remains bright and stationary.
310 +Gold marks meaningful recurrence independently of recency shape.
311 +The final two rows group the legend, model, input size, and native editor controls.
314 +╭─ DECAY.EXE · CLASSIFY 17/42 · 4.2s · gpt-5.6-luna ─╮
315 +│ HISTORY 79K ░░▒▒▓▓██◆ ║ 20K KEPT │
316 +│ ░▒░░▒▓▒▓██ ║ ▓▓▓▓▓▓▓▓▓▓ │
317 +│ TRANSFER ·········▝························▶ │
318 +│ SUMMARY [░░▒▒▓▓██··························] │
319 +│ LEGEND ░ old ▒ established ▓ recent █ newest ◆ │
320 +│ INPUT 99,474 · luna Enter queues steer · Esc │
321 +╰──────────────────────────────────────────────────────╯
324 +Viewports below 24 rows use a fixed four-line form with one history flow and one summary row.
325 +The rendered width always equals the supplied width, and animation never changes widget height.
326 +This stable common region preserves editor position and prevents chat re-scroll.
327 +Animation uses deterministic bounded geometry and a 55 ms frame cadence.
328 +Elapsed time, spinner state, or data changes request a Pi render.
329 +No timer writes directly to the terminal.
331 +After successful compaction, Decay emits one notification containing information absent from Pi's default result:
334 +Decay · gpt-5.6-luna · 42/42 classified · 20,000 kept · 4.2s
337 +Pi's built-in collapsed and expanded compaction summary remains unchanged.
339 +##
Experiment evidence 341 +The experiment uses Node `v26.4.0`, stdlib only, and the terminal alternate screen.
342 +Production will use Pi TUI rendering instead of its ANSI writer.
346 +- Deterministic self-test validates exact frame dimensions, source-cell vacancy, moving sub-cell glyphs, sorted `░░▒▒▓▓██` summary, stable retained tail, and elapsed output.
347 +- Snapshot checks cover 40x24, 50x24, 59x32, 80x30, 120x40, 140x45, and the bounded below-minimum screen.
348 +- A detached tmux viewport at exact 59x32 showed empty-to-sorted summary growth, visible 20k tail, grouped legend, elapsed timer, zero scrollback, and clean Escape exit.
349 +- PTY capture showed one initial clear, differential cursor-addressed updates, one alternate-screen entry, and one restoration.
350 +- Git state remained clean because the first experiment lived outside the repository.
352 +The promoted experiment is retained as executable design evidence and must remain self-testing.
354 +##
Implementation tasks 356 +###
1. Package and settings 358 +- [x] Create `extensions/decay/package.json` with only required Pi peers, TypeBox, Vitest, and pi-test-harness.
359 +- [x] Add the mandatory real-runtime harness load test.
360 +- [x] Parse merged `decay.model` settings with project precedence.
361 +- [x] Add `"decay": { "model": "openai-codex/gpt-5.6-luna" }` to the real global Pi settings without disturbing existing dirty work.
363 +###
2. Pure domain model 365 +- [x] Define source chunks, classifier records, memory atoms, persisted details, run progress, and terminal outcomes.
366 +- [x] Implement deterministic chunking and split-prefix tagging.
367 +- [x] Implement strict TypeBox validation and full chunk reconciliation.
368 +- [x] Implement prior-state merge, protected kinds, recency scoring, recurrence scoring, and proportional budget allocation.
369 +- [x] Implement deterministic file-list merge and appendix rendering.
371 +###
3. Classifier stream 373 +- [x] Resolve configured or current model and owning provider.
374 +- [x] Resolve auth through `ModelRegistry`.
375 +- [x] Define the single constrained `record_chunk` tool.
376 +- [x] Consume streamed tool calls without executing them through Pi's agent loop.
377 +- [x] Canonicalize valid finalized calls into private temporary JSONL.
378 +- [x] Tail JSONL into progress with coalesced-event and final-drain handling.
379 +- [x] Combine classifier usage and reject incomplete coverage.
383 +- [x] Build the fixed strategy prompt and separate one-run instruction section.
384 +- [x] Feed only locally merged, ranked, and budgeted atoms.
385 +- [x] Reject tool calls, empty output, errors, and aborts.
386 +- [x] Append file operations deterministically.
387 +- [x] Return summary, retained boundary, input tokens, combined usage, and structured details.
391 +- [x] Port the defrag motion vocabulary into a passive Pi widget component.
392 +- [x] Keep the widget fixed at eight normal lines or four short-terminal lines.
393 +- [x] Drive one cell transfer per accepted classifier record.
394 +- [x] Render indeterminate merge without fake percentage.
395 +- [x] Group legend items by proximity and alignment.
396 +- [x] Keep the 20k retained region visually distinct from moving history.
397 +- [x] Preserve Pi editor focus, steering submission, and native Escape cancellation.
398 +- [x] Support required widths without truncation, flicker, or chat re-scroll.
399 +- [x] Emit one bounded success notification.
401 +###
6. Integration and fallback 403 +- [x] Register `session_before_compact` and `session_compact` handlers.
404 +- [x] Handle failure inside the hook because Pi 0.84.2 exposes no `session_compact_failed` event.
405 +- [x] Delegate every non-abort Decay failure to default compaction exactly once.
406 +- [x] Persist one bounded, sanitized, agent-invisible diagnostic entry before fallback.
407 +- [x] Preserve manual, threshold, and overflow semantics even though the widget does not label the cause.
408 +- [x] Preserve Pi's `firstKeptEntryId`, `tokensBefore`, usage accounting, session tree, and built-in result rendering.
409 +- [x] Remove temporary JSONL and timers on every terminal path.
413 +- [x] Unit-test settings precedence and model resolution.
414 +- [x] Unit-test chunk boundaries, split turns, classifier schema, strict-tool metadata, duplicates, missing records, and out-of-order records.
415 +- [x] Unit-test partial stream arguments, finalized tool calls, text noise, provider errors, cancellation, JSONL permissions, tailing, and cleanup.
416 +- [x] Unit-test prior Decay details, first-run non-Decay summaries, protected atoms, supersession, recurrence, scoring, and file appendices.
417 +- [x] Unit-test classifier-to-merge phase transitions and combined usage.
418 +- [x] Render every required terminal size and assert line count, visible width, grouping, stable retained tail, source vacancies, sorted summary, and bounded frame updates.
419 +- [x] Exercise the real extension hook with controlled fake streaming and completion providers through pi-test-harness.
420 +- [x] Exercise success, malformed classification fallback, summarizer fallback, event abort, threshold, manual, overflow, split-turn, repeated compaction, passive TUI, and headless mode.
421 +- [x] Run the promoted MJS self-test.
422 +- [x] Run `mise run build -- decay`.
423 +- [x] Run `mise run test`.
424 +- [x] Run `mise run ci`.
426 +##
Validation evidence 428 +- `mise run ci` passes typecheck, static checks, lint, 1,919 tests, 49 fuzz tests, and every extension E2E task through Debian PRoot on Android.
429 +- Browser E2E passes in Chromium and Firefox; one Firefox assertion required its configured retry.
430 +- The final `mise run test` passes 1,919 tests across 167 files, with one unrelated test skipped.
431 +- `mise run test -- extensions/decay/__tests__`: seven files and 48 Decay tests passed after replacing the modal Escape test with passive-widget focus coverage.
432 +- A real tmux Pi 0.84.2 steering E2E kept the eight-line widget visible, accepted `retain STEERING-SENTINEL after compaction` through the focused editor, and displayed Pi's native queued-steering status while Decay entered merge.
433 +- A real tmux Pi 0.84.2 run used Luna to compact 99,474 tokens across 24 classifier chunks.
434 +- The persisted compaction had `fromHook: true`, Luna model details, a 20,000-token retained tail, three recurring atoms, maximum recurrence 24, and no fallback diagnostic.
435 +- The E2E exposed model-owned source provenance as brittle in the active development session; provenance is now assigned locally and the recurrence-heavy Luna rerun passed.
436 +- `mise run build -- decay`: passed after the passive-widget redesign.
437 +- `mise run lint`: passed with only the existing Biome schema-version notice.
438 +- The MJS experiment self-test passed.
439 +- The configured Luna setting parses as valid JSON and resolves to the expected string.
443 +The parent dotfiles `mise run check` cannot start on Android because mise's `cargo-binstall` backend requests a nonexistent `cargo-binstall-aarch64-android.zip` asset.
444 +No workaround was added.
448 +Decay is done when every listed behavior is covered through the real extension path, every required responsive size is rendered and checked, default fallback is proven, the real Luna setting is applied without losing unrelated changes, temporary plaintext is always removed, and `mise run ci` passes.