@narumitw/pi-context-management 0.0.0

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Narumi
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,148 @@
1
+ # 🧠 pi-context-management — Summary-Free Context Rollover for Pi
2
+
3
+ [![npm](https://img.shields.io/npm/v/@narumitw/pi-context-management)](https://www.npmjs.com/package/@narumitw/pi-context-management) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
4
+
5
+ Add opt-in, summary-free context rollover, bounded history recall, and branch-local notes to Pi.
6
+ The extension keeps Pi's append-only session while presenting a smaller current window to the model.
7
+
8
+ > **Experimental:** Context rollover intentionally omits an automatic summary and can lose working detail if the model does not save or recall it correctly. The feature is disabled by default. Keep backups of important sessions and notes.
9
+
10
+ ## ✨ Features
11
+
12
+ - Starts a fresh model-visible context window without generating a conversation summary.
13
+ - Preserves Pi's append-only session and compaction boundaries.
14
+ - Exposes four bounded `context_management_*` tools for rollover, capacity, recall, and notes.
15
+ - Recalls older plaintext branch history without copying it into separate extension state.
16
+ - Stores versioned notes and window lineage on the active branch so forks diverge naturally.
17
+ - Fails closed when persisted fingerprints do not match or fingerprint traversal exceeds its limits.
18
+ - Provides `/context-management` for status, help, and immediate settings changes.
19
+
20
+ ## 📦 Install
21
+
22
+ Install persistently from npm:
23
+
24
+ ```bash
25
+ pi install npm:@narumitw/pi-context-management
26
+ ```
27
+
28
+ Try the published package without installing:
29
+
30
+ ```bash
31
+ pi -e npm:@narumitw/pi-context-management
32
+ ```
33
+
34
+ Try a local checkout from the repository root:
35
+
36
+ ```bash
37
+ pi -e ./packages/pi-context-management
38
+ ```
39
+
40
+ The package loads its TypeScript source directly and does not require a build step.
41
+ Do not load a global npm installation and the local workspace at the same time.
42
+ Pi extensions run with your user permissions; review third-party extension source before installing it.
43
+
44
+ ## 🚀 Quick start
45
+
46
+ 1. Install or load the extension.
47
+ 2. Run `/context-management`, open **Settings**, and turn on **Experimental context management**.
48
+ 3. Ask the model to preserve durable decisions with `context_management_update_notes` before it calls `context_management_start_new_context`.
49
+
50
+ The four tools become active as one unit after enablement.
51
+ Disable other extension-owned compaction routes while using this strategy because multiple `session_before_compact` handlers can conflict.
52
+
53
+ ## 🧭 How it works
54
+
55
+ ```mermaid
56
+ flowchart LR
57
+ A[Current context window] --> B[Pi compaction boundary]
58
+ B --> C[Summary-free window marker]
59
+ C --> D[Fresh model-visible window]
60
+ A -. bounded recall .-> D
61
+ N[Branch-local notes] -. bounded recall .-> D
62
+ ```
63
+
64
+ At compaction, the extension stores window lineage and fingerprints for Pi's retained suffix.
65
+ Its `context` hook hides that exact old suffix only when every expected fingerprint matches.
66
+ Older plaintext messages and notes remain available through the recall tool.
67
+ See the [context management guide](docs/context-management.md) for rollover, storage, recovery, limits, and privacy details.
68
+
69
+ ## 💬 Commands
70
+
71
+ Run `/context-management` without arguments to inspect status, enable or disable the feature, and open help.
72
+ TUI changes are saved and applied immediately; closing the menu does not undo a completed save.
73
+ RPC reports the settings path, while print and JSON modes reject the command.
74
+
75
+ ## 🛠️ Tools
76
+
77
+ The extension registers these tools but keeps them inactive until enabled:
78
+
79
+ | Tool | Purpose |
80
+ | --- | --- |
81
+ | `context_management_start_new_context` | Schedule one summary-free rollover after the current run settles. |
82
+ | `context_management_get_context_remaining` | Read Pi's current context usage estimate. |
83
+ | `context_management_recall_context` | List, read, or search bounded branch history and notes. |
84
+ | `context_management_update_notes` | Write or append one bounded branch-local note. |
85
+
86
+ The tools activate or deactivate together.
87
+ If an exact tool name is unavailable or belongs to another extension, activation fails without replacing that tool and Pi-native compaction remains available.
88
+
89
+ ## ⚙️ Settings
90
+
91
+ The extension has one optional, global-only settings file:
92
+
93
+ ```text
94
+ <getAgentDir()>/pi-context-management.json
95
+ ```
96
+
97
+ The normal path is `~/.pi/agent/pi-context-management.json`.
98
+ There is no environment-variable or project-level override.
99
+
100
+ ```json
101
+ {
102
+ "enabled": true
103
+ }
104
+ ```
105
+
106
+ `enabled` defaults to `false`.
107
+ Direct file edits apply on the next `session_start`, including `/reload`, resume, or fork; menu changes apply immediately.
108
+ Missing settings do not create a file.
109
+ Malformed, invalid, oversized, or symlinked files remain unchanged and use the safe disabled default until repaired and reloaded.
110
+ Menu saves preserve unknown fields, serialize within the Pi process, and publish through a same-directory atomic rename with private temporary-file permissions.
111
+
112
+ ## 🔒 Security and privacy
113
+
114
+ Pi session files store notes and context metadata as plaintext with the rest of the local session.
115
+ Anyone who can read the session can read those notes.
116
+ The recall tool sends selected history or notes to the active model provider as a tool result; it does not detect or redact secrets already present in messages or notes.
117
+
118
+ Tool output, branch scans, settings, notes, and persisted metadata are bounded.
119
+ Terminal controls are stripped from rendered or model-visible extension output.
120
+ The extension does not read provider credentials or request headers and makes no network request of its own.
121
+
122
+ ## 🚧 Limitations
123
+
124
+ - Pi chooses compaction thresholds and the retained suffix, so usable capacity can differ from the model-facing estimate.
125
+ - Summary-free rollover depends on the model preserving and recalling important information correctly.
126
+ - Continuation starts in a later model turn rather than resuming atomically inside the interrupted turn.
127
+ - Other extensions that also handle `session_before_compact` can conflict; disable their compaction route while this extension is enabled.
128
+ - Malformed, unsupported, or unrelated persisted entries are ignored rather than migrated or rewritten.
129
+
130
+ ## 🗂️ Package layout
131
+
132
+ ```text
133
+ packages/pi-context-management/
134
+ ├── src/ # Authoritative extension, tools, state, settings, and UI
135
+ │ └── index.ts # Thin Pi entrypoint
136
+ ├── docs/ # Detailed operating guide
137
+ └── test/ # Lifecycle, persistence, loader, and real-runtime coverage
138
+ ```
139
+
140
+ The published entrypoint is `src/index.ts` and the package has no generated runtime.
141
+
142
+ ## 🔎 Keywords
143
+
144
+ Pi extension, context management, context window, summary-free compaction, memory, notes, history recall.
145
+
146
+ ## 📄 License
147
+
148
+ [MIT](LICENSE)
@@ -0,0 +1,257 @@
1
+ # Experimental context management
2
+
3
+ > **Experimental:** This feature changes model-visible context and can lose working detail when the
4
+ > model does not save or recall it correctly. It is disabled by default. Keep backups of important
5
+ > sessions and notes.
6
+
7
+ Experimental context management is a Pi-native, summary-free rollover strategy.
8
+ Pi keeps the append-only session, while the extension starts a smaller model-visible context window
9
+ and lets the model retrieve older plaintext history or branch-local notes with tools.
10
+
11
+ ## Enable the experiment
12
+
13
+ Edit the global settings file shown by `/context-management`, normally
14
+ `~/.pi/agent/pi-context-management.json`:
15
+
16
+ ```json
17
+ {
18
+ "enabled": true
19
+ }
20
+ ```
21
+
22
+ You can also turn on **Experimental context management** in `/context-management` → **Settings**. Direct
23
+ file edits apply on the next `session_start`, including `/reload`, resume, or fork. Menu changes apply
24
+ immediately. Pi shows a warning once per active session.
25
+
26
+ The default is `false`. When enabled, the extension handles Pi compaction with summary-free local
27
+ rollover. Disable other extension-owned compaction routes while using it because multiple
28
+ `session_before_compact` handlers can conflict. This extension does not inspect or coordinate with
29
+ other extensions.
30
+
31
+ ```mermaid
32
+ flowchart TD
33
+ A[Pi requests compaction] --> B{Context management enabled?}
34
+ B -- Yes --> C[Summary-free local rollover]
35
+ B -- No --> D[Pi native summary or another independently configured hook]
36
+ ```
37
+
38
+ ## Tools
39
+
40
+ All four tools are active only while the experiment is enabled. Their `context_management_` namespace
41
+ avoids generic registration collisions. Their definitions intentionally omit system-prompt snippets
42
+ and guidelines; one hidden, versioned context contract provides stable model guidance. If another
43
+ extension owns any exact tool name, activation fails as a unit, keeps the other extension's tool
44
+ active, warns the user, and leaves Pi-native compaction in control.
45
+
46
+ ### `context_management_start_new_context`
47
+
48
+ Request one fresh context window after the current agent run settles:
49
+
50
+ ```json
51
+ {
52
+ "reason": "The current window is almost full"
53
+ }
54
+ ```
55
+
56
+ The tool schedules one rollover and asks Pi to stop after the tool batch. Sibling tool calls may still
57
+ finish before the agent becomes idle. Pi stops only when every result in a mixed batch requests
58
+ termination. If another model turn runs first, the extension still compacts after settlement. A
59
+ successful post-request turn suppresses the duplicate hidden next turn; a turn ending in an error or
60
+ output-length cutoff remains eligible for one. If Pi already starts automatic compaction, that
61
+ compaction consumes the request; otherwise the extension calls `ctx.compact()` at `agent_settled`.
62
+ The scheduled tool result persists the request and target-window identifiers. On session restart or
63
+ reload, the extension resumes an unresolved request, completes a persisted compaction's missing
64
+ continuation once, and does not repeat work after its continuation, cancellation, or successful-turn suppression marker is present.
65
+
66
+ Successful compaction moves to the new window and sends a hidden next-turn message asking the model
67
+ to continue. Failed compaction keeps the old context, reports one warning, and sends a hidden failure
68
+ continuation. Losing any context tool before compaction also fails the pending rollover and falls back
69
+ to Pi-native compaction; losing a tool after completion preserves the success continuation but reports
70
+ that local recall is unavailable. Either next turn is suppressed when a successful post-request turn
71
+ already continued the work. Continuation starts in a later model turn rather than resuming atomically
72
+ inside the interrupted turn. Save important information with `context_management_update_notes` before
73
+ requesting a new context.
74
+
75
+ ### `context_management_get_context_remaining`
76
+
77
+ Inspect the active model's current Pi context estimate without changing state:
78
+
79
+ ```json
80
+ {}
81
+ ```
82
+
83
+ The result contains the current window ID, context-window size, used tokens, remaining tokens, and
84
+ remaining percentage when Pi has an estimate. Token values can be `null` immediately after
85
+ compaction and before the next provider response.
86
+
87
+ ### `context_management_recall_context`
88
+
89
+ List, read, or search the active branch's plaintext history or notes:
90
+
91
+ ```json
92
+ {
93
+ "source": "history",
94
+ "action": "search",
95
+ "query": "authentication decision"
96
+ }
97
+ ```
98
+
99
+ ```json
100
+ {
101
+ "source": "notes",
102
+ "action": "read",
103
+ "id": "project-decisions"
104
+ }
105
+ ```
106
+
107
+ Accepted sources are `history` and `notes`. Accepted actions are `list`, `read`, and `search`.
108
+ `read` requires `id`; `search` requires `query`. Pass a returned `cursor` to continue a bounded list,
109
+ search, or long read.
110
+
111
+ The tool is read-only. It can return model-visible user, assistant, custom-message, and tool-result
112
+ content from the active branch, but it excludes extension custom entries and unrelated extension
113
+ state. It does not detect or redact credentials, request headers, or other secrets present in
114
+ model-visible messages or notes.
115
+
116
+ ### `context_management_update_notes`
117
+
118
+ Write or append one branch-local note:
119
+
120
+ ```json
121
+ {
122
+ "action": "write",
123
+ "note": "project-decisions",
124
+ "content": "Use OAuth with PKCE."
125
+ }
126
+ ```
127
+
128
+ ```json
129
+ {
130
+ "action": "append",
131
+ "note": "project-decisions",
132
+ "content": " Refresh tokens remain server-side."
133
+ }
134
+ ```
135
+
136
+ `write` replaces the selected note. `append` adds the supplied content exactly, without inserting a
137
+ separator. The tool does not read notes; use `context_management_recall_context` for that.
138
+
139
+ ## Rollover and storage
140
+
141
+ ```mermaid
142
+ flowchart TD
143
+ A[Window A reaches a Pi compaction boundary] --> B[Create Window B UUID]
144
+ B --> C[Persist a small marker and retained-prefix fingerprints]
145
+ C --> D[Pi keeps its structurally valid suffix]
146
+ D --> E{Marker and fingerprints match exactly?}
147
+ E -- Yes --> F[Hide the old retained prefix from provider context]
148
+ E -- No --> G[Fail closed and keep Pi context unchanged]
149
+ F --> H[Window B plus later messages]
150
+ H --> I[Use context_management_recall_context for older plaintext data]
151
+ ```
152
+
153
+ The extension preserves Pi's prepared `firstKeptEntryId`, so the session remains structurally valid.
154
+ Its `context` hook removes only the exact retained-message prefix recorded in the latest supported
155
+ experimental compaction details. A mismatch leaves Pi's context unchanged rather than risking data
156
+ loss.
157
+
158
+ The model-visible compaction marker contains no conversation summary. It identifies the first,
159
+ previous, and current window and reminds the model to use the context tools. Enabling, disabling, and
160
+ each rollover create intentional prompt-prefix epochs; ordinary turns within an epoch retain the same
161
+ ordered tool definitions and existing message prefix.
162
+
163
+ ```mermaid
164
+ flowchart LR
165
+ subgraph Session[Pi append-only active branch]
166
+ A[Window A messages]
167
+ B[Window B marker]
168
+ C[Window B messages]
169
+ D[Note mutations]
170
+ end
171
+
172
+ subgraph Provider[Current provider context]
173
+ B2[Window B marker]
174
+ C2[Window B messages]
175
+ end
176
+
177
+ B --> B2
178
+ C --> C2
179
+ A -. context_management_recall_context .-> C2
180
+ D -. context_management_recall_context .-> C2
181
+ ```
182
+
183
+ Window lineage is stored in versioned custom state and compaction details. Notes are stored as
184
+ versioned append-only mutations and rebuilt from the active branch, so a fork inherits its ancestor's
185
+ notes and then diverges naturally. The extension does not copy raw conversation history into its own
186
+ state.
187
+
188
+ ## Limits
189
+
190
+ Limits are fixed to keep session growth and tool responses bounded:
191
+
192
+ | Boundary | Limit |
193
+ | --- | ---: |
194
+ | Note name | 128 characters with no terminal controls |
195
+ | One note mutation | 16 KiB UTF-8 |
196
+ | Active notes | 64 names and 256 KiB total |
197
+ | Notes branch replay | 100,000 entry visits and 4,194,304 scan units per request |
198
+ | Recall query | 512 characters |
199
+ | Recall search page | 20 matches |
200
+ | History branch traversal | 100,000 entry visits per request |
201
+ | History compaction attribution | 8,388,608 persisted-detail scan units per request |
202
+ | Context lineage, mode, and rollover recovery | 100,000 combined entry visits and 8,388,608 persisted-detail scan units per operation |
203
+ | History read scan | 4,194,304 scan units per selected item |
204
+ | History search scan | 4,194,304 scan units across indexed characters and visited values per request |
205
+ | Retained-message fingerprints | 512 levels per message, plus 4,194,304 scan units and 8 MiB serialized across one creation or projection operation |
206
+ | Recall response | 32 KiB and 1,000 lines |
207
+
208
+ Long reads and additional list or search matches use cursors. History actions fail explicitly when
209
+ an applicable entry-visit, read-scan, search-scan, or response limit is reached instead of continuing
210
+ unbounded work. Fingerprint-limit failures cancel experimental compaction rather than falling through
211
+ to Pi's summarizer. Malformed or unsupported persisted versions are ignored individually.
212
+
213
+ ## Compatibility transitions
214
+
215
+ Malformed, unsupported, or unrelated persisted entries remain untouched and are ignored. Enabling
216
+ this package starts or resumes only lineages that use its `context_management_*` tools and
217
+ `pi-context-management-*` persisted identifiers.
218
+
219
+ Disabling the experiment at idle appends one deterministic hidden deactivation transition in each
220
+ owning session and then removes the four tools. A non-initiating idle session publishes its durable
221
+ transition before its next input is persisted; a no-input continuation queues the same transition at
222
+ its next context boundary. During an
223
+ active run, the current contract and tools remain available through settlement; the extension then
224
+ publishes deactivation before removing the tools. An accepted but
225
+ unfinished rollover reports a failure continuation at that boundary instead of being discarded, while
226
+ a rollover that already completed retains its success continuation and reports that context tools are
227
+ unavailable. Re-enabling before settlement cancels the pending tool-removal transition and leaves an
228
+ accepted rollover scheduled. This stops future summary-free rollover without deleting entries, so
229
+ existing Pi markers and retained messages remain readable. Re-enable after
230
+ settlement to append a new activation transition and regain local recall tools.
231
+
232
+ Local notes and plaintext history are independent of the selected provider and model. Context usage
233
+ always reflects the currently selected model.
234
+
235
+ ## Privacy and security
236
+
237
+ Pi session files store notes and context metadata as plaintext with the rest of the local session.
238
+ Anyone who can read the session can read those notes. `context_management_recall_context` sends selected
239
+ history or notes to the active model provider as a tool result. Do not store secrets that should not
240
+ reach that provider.
241
+
242
+ Retrieved text is bounded and terminal controls are removed at the result boundary. Provider
243
+ credentials, request headers, and unrelated extension state are not recallable through this package.
244
+ Recall does not detect or redact secrets or headers that users, models, or tools placed in model-visible
245
+ messages or notes.
246
+
247
+ ## Runtime limits
248
+
249
+ Pi remains responsible for thresholds, overflow recovery, `/compact`, session publication, and the
250
+ structurally retained suffix. Pi calculates its pre-turn compaction threshold from internal context
251
+ before the extension's provider-facing filter, so the retained suffix can still reduce the effective
252
+ window budget even when the provider does not receive it. Context-remaining values are estimates and
253
+ can reflect this difference.
254
+
255
+ The extension does not provide an external history service, provider cache lineage, exact
256
+ body-after-prefix token accounting, or same-turn continuation. Treat it as a portable experimental
257
+ workflow built only on Pi's public extension APIs.
package/package.json ADDED
@@ -0,0 +1,57 @@
1
+ {
2
+ "name": "@narumitw/pi-context-management",
3
+ "version": "0.0.0",
4
+ "description": "Experimental summary-free context rollover, recall, and branch-local notes for Pi.",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "private": false,
8
+ "keywords": [
9
+ "pi-package",
10
+ "pi-extension",
11
+ "pi",
12
+ "context-management",
13
+ "context-window",
14
+ "compaction",
15
+ "memory",
16
+ "notes",
17
+ "recall"
18
+ ],
19
+ "files": [
20
+ "src",
21
+ "docs",
22
+ "README.md",
23
+ "LICENSE"
24
+ ],
25
+ "pi": {
26
+ "extensions": [
27
+ "./src/index.ts"
28
+ ]
29
+ },
30
+ "scripts": {
31
+ "check": "biome check . && npm run typecheck",
32
+ "format": "biome check --write .",
33
+ "typecheck": "tsc --noEmit"
34
+ },
35
+ "dependencies": {
36
+ "@narumitw/pi-tui-kit": "^0.59.0"
37
+ },
38
+ "peerDependencies": {
39
+ "@earendil-works/pi-agent-core": "*",
40
+ "@earendil-works/pi-ai": "*",
41
+ "@earendil-works/pi-coding-agent": "*",
42
+ "typebox": "*"
43
+ },
44
+ "devDependencies": {
45
+ "@earendil-works/pi-agent-core": "0.85.1",
46
+ "@earendil-works/pi-ai": "0.85.1",
47
+ "@earendil-works/pi-coding-agent": "0.85.1",
48
+ "@types/node": "26.4.1",
49
+ "typebox": "1.3.30",
50
+ "typescript": "7.0.2"
51
+ },
52
+ "repository": {
53
+ "type": "git",
54
+ "url": "https://github.com/narumiruna/pi-extensions",
55
+ "directory": "packages/pi-context-management"
56
+ }
57
+ }