notesoup

Your agent's memory gets wiped when the context fills. notesoup makes that survivable: the agent writes itself a checkpoint before the wipe, wakes up in a fresh window, and digs up whatever it still needs from the old conversation. For you it's mostly invisible — an occasional notification, /fresh-window to force a fresh window, /notesoup to toggle.

The architecture — durable context windows, model-authored notes, searchable history — is the one OpenAI prototyped in Codex's context_management experiment and switched off ten days later, because it was welded to their backend. notesoup is the same architecture running entirely on your machine, built only on Pi's public extension APIs. No backend, no subscription gate, no server that can 404 at the worst possible moment. It can't be switched off from far away, because there is no far away.

Renamed from pi-context

The old name is retired: @astrosheep/pi-context is deprecated, and the package is now notesoup. The settings key renamed from pi-context to notesoup, and the Claude Code Mod's MCP tool prefix renamed from mcp__pi-context__ to mcp__notesoup__ (reinstall the mod). Old notes data is unaffected.

Why not just compaction?

• Reset ≠ summary. Compaction is lossy compression you sit and wait for — and the next one summarizes the summary of the summary. A notesoup reset summarizes nothing: the window closes in O(1), because whatever mattered was already written to notes beforehand. Fast because there's nothing to compute; safe because the raw history never leaves disk.
• Notes are files you can open. Plain Markdown in ~/.agents/notes, in named homes (@project, @human, @self, @model, plus per-session). Readable, editable, greppable, git-able. Not an encrypted blob — and not a secret the model is instructed to keep from you. (Yes, that was a real instruction. No, we didn't port it.)
• History never forgets. Every closed window — messages, tool calls, tool output — stays fully searchable through the history_* tools. Notes are the agent's lossy index; history is the lossless record underneath. This is the half the original experiment never shipped.

Install

pi install npm:notesoup

Or load it for a single invocation without installing:

pi -e npm:notesoup

What you get

• Durable context windows. /fresh-window (alias /empty) clears and stops; /fresh-window Continue reviewing the implementation clears and continues. The model can also request a window itself with empty_brain, and a budget close-out fires automatically before the window runs out. Abort and ordinary errors never count as completion; the raw conversation stays in the session, just out of the next context.
• A boot block at every window head. Static once-per-window content (cache-stable) with the window identity, the recent-notes index, and a short protocol teaching the model how to recover: notes for its own bookkeeping, history tools for everything before the reset.
• get_context_remaining — how much room the brain has left before the hard-reserve wipe, including the warning runway.
• Eight history/notes tools, flattened from the original Codex actions:

• Migration: history_search is gone; pass query to history_list.

• Migration (0.40.0): parameters renamed: order → from, before/after → before_seq/after_seq, limit_chars → max_chars, wastebasket → crumpled, pattern → glob (the standalone library's options included), and notes_update's change_kind value file → moved. Old names are refused.

• Runtime toggle — /notesoup off stops new automatic resets; /notesoup on re-enables them; bare /notesoup reports the state.

Configuration

The reminder threshold is Pi's compaction reserve plus a margin, configured under the top-level notesoup key in ~/.pi/agent/settings.json or <cwd>/.pi/settings.json (project values win per key):

{
  "compaction": { "reserveTokens": 16384 },
  "notesoup": { "reminderMarginTokens": 24576 }
}

The dreamer model is configured under the same key; --dreamer <model pattern> on the dream CLI wins, then a non-empty notesoup.dreamer string, then the automatic model:

{
  "notesoup": { "reminderMarginTokens": 24576, "dreamer": "anthropic/claude-sonnet-4-5" }
}

Documentation

• Architecture and reset lifecycle — how windows, checkpoints, markers and branches actually work
• Tool results — receipts, paging, and error shapes
• Standalone notes library — use the notes store from Node, no Pi required
• DeepSeek Harness — adapter and profile patch for dsh 0.2.1-alpha.2
• Claude Code Mod — early-access notes and persisted-session history tools for Claude Code
• Skills, dream, and the notes doctor — /skill:memory, /skill:dream, dream doctor, the dream lock

Development

npm test            # build from a clean dist, then run the suite
npm run typecheck
git diff --check
node scripts/check-notes-package.mjs  # optional built /notes CRUD smoke; no install
npx tsx scripts/boot-smoke.mts [cwd]  # optional live boot render against the real notes homes

The repository splits host-neutral code from host plugins:

Each plugin owns its host's words — Pi's pre-reset hints and last_word nudge live in plugins/pi/text.ts, Claude's reset and missing-history prose in plugins/claude/src/text.ts — while the shared boot, protocol and warning bodies stay in src/boot/text.ts and src/budget/text.ts.

The harness runs against the real installed Pi SessionManager/SettingsManager in temporary directories with fake credentials — no model or network calls, and the real ~/.pi is never touched. See CONTRIBUTING.md for ownership and verification rules.

License

MIT