pi-nunc
In-session rolling context and working memory extension for Pi.
Package details
Install pi-nunc from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-nunc- Package
pi-nunc- Version
0.3.0- Published
- Nov 14, 2026
- Downloads
- 729/mo · 266/wk
- Author
- tefx
- License
- unknown
- Types
- extension
- Size
- 1.8 MB
- Dependencies
- 0 dependencies · 3 peers
Pi manifest JSON
{
"extensions": [
"./dist/src/index.js"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
Nunc
Nunc is a Pi extension designed to keep a single long-running session coherent inside a finite context window.
Scope stays strictly within the active session branch: /new starts with empty memory, and /tree, /fork, and /clone follow the selected branch. Nunc avoids cross-session memory databases, user profiling, or background document indexing—durable project knowledge belongs in code, docs, and commits.
This package is "private": true and is not published to npm.
How It Works
Stock compaction replaces older conversation history with a single flat summary, which often drops exact constraints, parameters, or mid-task state over multiple compactions, and invalidates prompt caches when summaries move. Nunc replaces that summary with incremental working-memory slots (M) and a cache-friendly context layout:
Normal turn: F | R_before | M | R_after
Compaction: F | M | B | K --> updated M + retained K
- Verbatim recent history (
R/K): Recent turns stay verbatim so the model sees exact tool calls, outputs, and immediate context. - Anchored working memory (
M): Information that still matters after older turns age out—goals, constraints, decisions, inputs, and unfinished work—lives in discrete text slots ({ id, text }). During normal turns, unchangedMstays anchored at the history boundary where it was last sent (R_before | M | R_after), keeping the prompt prefix stable for provider caching. - Single-pass incremental maintenance: When Pi triggers compaction (threshold, overflow recovery, or
/compact), Nunc splits active history into retiringBand retainedK, and makes at most one call on the session's current model. The model returns a structured JSON patch (add,update,remove,priority,required, and optionaltoolResultEdits). Allrequireditems are kept together; if validation or capacity fails, Nunc cancels the compaction so Pi preserves the existing session state unchanged. - Tool-result cleanup & overflow calibration: Completed business-tool outputs that have already been distilled into
M(or duplicated inK) can be compacted or summarized in place while keeping raw originals in the session JSONL. If a provider undercounts tokens or rejects a maintenance request for context overflow, Nunc records branch-bound calibration so the next attempt automatically trims large tool bodies or fails fast without repeating the same rejected call.
Tools and TUI
Interactive TUI & Commands
/nuncorF7: Opens the Nunc overlay in TUI mode (Slotstab to search, preview, edit, or delete memory slots;Contexttab to inspect the liveF / M / Rlayout, token budgets, and last maintenance record). In non-TUI modes,/nuncprints the full text report./nunc details: Prints the text report (slot occupancy, budgets, last main/maintenance status, and recent diagnostics) without calling a model.- Footer indicator: Shows slot count and memory-target occupancy (
🧠 8·42%,🧠 0when empty,🧠 ↻8during maintenance/save,🧠 !8on warnings,🧠 ×on invalid config).
Optional Model Tools (--nunc-memory-tools)
By default, Nunc manages M only during compaction without changing the model's toolset. When enabled via --nunc-memory-tools or Pi settings ({"nunc": {"memoryTools": true}}), Nunc exposes two tools to the model:
nunc_memory_read: Reads current slots, revision, and budget; also supports read-only keyword search (query) and entry lookup (entryIds,originals) over retired messages and cleaned tool outputs on the current session branch.nunc_memory_patch: Atomically adds, updates, or removes memory slots (and optionaltoolResultEdits) during a turn using compare-and-swap (expectedRevision).
Requirements
| Dependency | Version |
|---|---|
| Node | Stable ^26.7.0 (.node-version: 26) |
| npm | Stable ^11.19.0 |
Pi / @earendil-works/pi-ai / @earendil-works/pi-tui |
Runtime: stable ^1.0.3; devDependencies pinned to 1.4.0 |
Runtime constraints:
- Persistent sessions only (
--no-sessionis rejected). - Native images only (
images.blockImagesmust remainfalse). - Single custom compaction owner (do not run another compaction extension alongside Nunc).
Quick Start
git clone https://github.com/tefx/pi-nunc.git
cd pi-nunc
npm ci --ignore-scripts --no-audit --no-fund
npm run build
node node_modules/@earendil-works/pi-coding-agent/dist/cli.js \
--offline --no-extensions -e dist/src/index.js
With a custom config file or model memory tools enabled:
node node_modules/@earendil-works/pi-coding-agent/dist/cli.js \
--offline --no-extensions -e dist/src/index.js \
--nunc-config ./nunc.json --nunc-memory-tools
package.json registers "pi": { "extensions": ["./dist/src/index.js"] }, so the repo directory can also be loaded as a local Pi package after npm run build.
Configuration
Pi settings.json
In ~/.pi/agent/settings.json or a trusted project .pi/settings.json:
{
"nunc": {
"memoryTools": false,
"toolResultCleanup": true
}
}
--nunc-config JSON
All fields are optional. policyFile resolves relative to the config file's directory.
| Field | Default | Purpose |
|---|---|---|
policyFile |
unset | Supplemental UTF-8 Markdown maintenance preferences appended to policies/default.md. |
memory.fraction |
0.1 |
Planning reserve fraction of available context ([0, 1)). |
memory.targetTokens |
8192 |
Soft organizing target for M. |
memory.maxTokens |
unset | Optional advisory ceiling on the maintenance organizing target. |
memory.hardMaxTokens |
unset | Optional hard cap on saved M (when unset, required slots may exceed the soft target). |
rolling.keepRecentFraction |
0.5 |
Target fraction of post-M context kept as verbatim K ((0, 1)). |
extraction.toolResults |
"auto" |
"auto" (head/tail reduction only when needed to fit input limits) or "full". |
extraction.headTailChars |
200 |
Head and tail character count kept when reducing large tool results. |
extraction.outputTokens |
"auto" |
"auto" (scales from an 8192 floor up to model output capability) or positive integer. |
budget.safetyTokens |
1024 |
Safety margin subtracted from input limits. |
budget.growthTokens |
1024 |
Post-compaction growth room reserved for upcoming turns. |
budget.extraMainInputTokens |
0 |
Extra input token allowance for main requests. |
budget.extraExtractionInputTokens |
0 |
Extra input token allowance for maintenance requests. |
budget.inputLimit |
unset | Optional explicit input token ceiling. |
budget.imageTokens |
unset | Optional per-image token estimate override (defaults to Pi's heuristic). |
Example nunc.json (overriding rolling.keepRecentFraction from 0.5 to 0.67):
{
"policyFile": "./preferences.md",
"memory": { "fraction": 0.1, "maxTokens": 2000, "hardMaxTokens": 8192 },
"rolling": { "keepRecentFraction": 0.67 },
"extraction": { "toolResults": "auto", "headTailChars": 200 },
"budget": { "safetyTokens": 1024, "growthTokens": 1024 }
}
Development
npm ci and npm run build compile the extension. Running the full check suite (scripts/check.mjs all) additionally requires Node/npm satisfying ^26.7.0 / ^11.19.0, local comparison baseline checkouts, POSIX PTYs, and /usr/bin/python3. Older, cross-major, malformed and prerelease versions are rejected. Checks report the actual observed Node/npm versions; live preflight records the observed Node version in its receipt and SHA-256 binding, invalidating earlier receipts after a runtime change. See docs/DEVELOPMENT.md and docs/LIVE.md.
The scoped-task comparison uses the immutable main-history commit for .scratch/prechange (separate from .scratch/baseline-70dacad):
git worktree add --detach .scratch/prechange 1d4fc4a210b64f71871ab3f5c10093215a25990c
(cd .scratch/prechange && npm ci --ignore-scripts --no-audit --no-fund && npm run build)
Documentation
Detailed specifications live in docs/:
- Project constitution: scope, ownership, and limits
- Core design
- Stable memory placement and retention
- Extraction protocol and required items
- Pi extension loading, commands, and persistence
- Maintenance engine
- Capacity ownership and calibration
- Slots/Context UI
- Active memory and model tools
- Working-memory guidance refinements
- Tool-result cleanup
- Native OpenAI routing and billing