@maheidem/pi-thinking-saver

Exact-content archival for Pi: reduce provider-facing context while preserving retired text for explicit recall. Archived content is not cognitively present until recalled.

Features

• Interactive /ctx panel — one command for every setting, current context pressure, exclusions, and the savings ledger.
• Profile-gated thinking retirement — archives completed-turn reasoning only for validated oMLX/llama.cpp Qwen profiles; unknown combinations preserve thinking.
• Anthropic-safe pacing — retains required thinking/signatures in active tool-use turns and batches retirement of settled turns.
• Soft compact — under configurable context pressure, archives stale tool results and replaces them with deterministic recall pointers.
• Immediate fresh-result sandboxing (experimental, default off) — when explicitly enabled, writes oversized results before first model inspection.
• Exact recall — immutable records include SHA-256 integrity metadata and remain available through ctx_read_sandbox by archive ID.
• Persistent tuning — settings survive reloads and restarts.

The extension performs no network requests. Files are written under ~/.pi/agent/context-saver/.

Installation

pi install npm:@maheidem/pi-thinking-saver

Then start or reload Pi and open the panel:

/ctx

If you previously installed pi-context-saver, remove or disable it first so both extensions do not intercept the same tool results:

pi remove npm:pi-context-saver

TUI controls

The /ctx overlay displays every setting at once.

| Key | Action | | --- | --- | | ↑ / ↓, j / k | Move between settings | | Enter | Toggle, cycle, open, or edit the selected setting | | e | Manage soft-compact tool exclusions | | s | Show the full statistics report | | d | Run diagnostics | | p | Show config and journal paths | | r | Reset the statistics ledger | | Esc, q | Close |

Numeric and size values edit inline, with their current value prefilled. Invalid input stays open with an error; valid changes are saved immediately.

One command, optional scripting

Only /ctx is registered, keeping Pi's slash-command menu uncluttered. The nested forms below are intended for scripts, print/RPC mode, or users who prefer typing. Pi provides argument completion for them.

/ctx                              open the panel
/ctx soft                         focus Soft compact
/ctx thinking                     focus Thinking
/ctx sandbox                      focus Tool sandbox
/ctx sandbox read                 focus the read threshold

/ctx status
/ctx stats
/ctx doctor
/ctx paths
/ctx cleanup                     preview age/quota retention
/ctx cleanup apply confirm       delete eligible inactive archives
/ctx export                      write a local metadata-only diagnostics snapshot
/ctx rollback confirm            restore the validated config.json.bak
/ctx on | off | reset

/ctx soft status
/ctx soft on | off
/ctx soft at <10-95>
/ctx soft keep <0-50>
/ctx soft batch <size>
/ctx soft min <size>
/ctx soft exclude add|remove|list [tool]
/ctx soft journal

/ctx thinking status
/ctx thinking on | off
/ctx thinking keep <0-20>
/ctx thinking batch <size>
/ctx thinking mode auto|offload|pace
/ctx thinking journal

/ctx sandbox general <size>
/ctx sandbox read <size>

Sizes accept bytes, KB, or MB, for example 4096, 64KB, or 1MB.

Defaults

| Setting | Default | | --- | --- | | Extension | enabled | | Soft compact | enabled | | Soft-compact trigger | 70% context usage | | Keep newest tool results | 10 | | Soft-compact batch | 128 KB | | Minimum result size | 8 KB | | Thinking | enabled | | Thinking mode | auto | | Thinking turns kept in pace mode | 1 | | Thinking batch | 128 KB | | Immediate sandboxing | disabled | | General sandbox threshold (when enabled) | 10 KB | | read sandbox threshold (when enabled) | 50 KB | | Retention | 30 days / 2 GiB total quota |

Thinking modes

• auto — pace only for checked-in validated oMLX/llama.cpp Qwen profiles and Anthropic; unknown combinations preserve thinking.
• offload — explicit legacy opt-in that archives thinking before its first replay; this is not an automatic safe default.
• pace — old settled-turn thinking is retired in batches; active tool-use thinking and signatures remain byte-identical.

Soft-compact safety rules

Soft compact never trims:

• the newest tool result;
• the configured newest keep window;
• error results;
• image-bearing results;
• excluded tools; or
• results smaller than min.

A result is retired only when context usage reaches at and a full batch of new reclaimable output has accumulated. The same archived baseline is re-applied byte-identically on later requests.

Storage and recall

~/.pi/agent/context-saver/config.json          persisted settings
~/.pi/agent/context-saver/stats.json           savings ledger
~/.pi/agent/context-saver/thinking-<id>.md     full thinking journal
~/.pi/agent/context-saver/tools-<id>.md        full soft-compact journal
~/.pi/agent/context-saver/sandbox-*.txt        oversized tool output

New archive pointers identify one immutable object by archive ID and SHA-256; legacy path pointers remain readable. ctx_read_sandbox canonicalizes paths, rejects symlink/sibling escapes, verifies structured archives, and caps responses. Exact tool output and reasoning are stored locally in plaintext under this directory with owner-only creation permissions. Retention defaults to 30 days / 1 GiB and protects archives referenced by the active wire epoch; /ctx cleanup previews deletion before the confirmed form applies it. Session shutdown also applies the configured policy. Diagnostics exports contain metadata/config, not archive bodies.

Requirements

• Pi coding agent 0.84.0 or newer
• Node.js 18 or newer
• TUI mode for the interactive panel; print/RPC/JSON modes retain the text and scripting interface

Development

npm install
npm run typecheck
npm test
npm pack --dry-run

The test suite compiles into isolated temporary directories and uses a separate fake HOME per suite, so it cannot modify live Pi configuration or journals.

License

MIT. The heavy-output sandboxing foundation is derived from HyperspaceNG/pi-context-saver, also MIT licensed. Its copyright notice is retained in LICENSE.