@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 +21 -0
- package/README.md +148 -0
- package/docs/context-management.md +257 -0
- package/package.json +57 -0
- package/src/context-management.ts +895 -0
- package/src/context-tools.ts +203 -0
- package/src/context-window.ts +393 -0
- package/src/fingerprint.ts +104 -0
- package/src/index.ts +1 -0
- package/src/notes-state.ts +144 -0
- package/src/pi-context-management.ts +105 -0
- package/src/recall-context.ts +524 -0
- package/src/settings-menu.ts +186 -0
- package/src/settings.ts +175 -0
- package/src/terminal.ts +6 -0
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
|
+
[](https://www.npmjs.com/package/@narumitw/pi-context-management) [](https://pi.dev) [](./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
|
+
}
|