Upgrade notebook semantics to durable subject-oriented grounding

Author: ofriw

README.md

@@ -5,7 +5,7 @@
 [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 ![Status](https://img.shields.io/badge/status-active-brightgreen)
 
-**A Pi extension that gives the LLM tools to manage its own context.** `spawn`, `ledger`, and `handoff` let the agent actively isolate work, persist reusable knowledge, and restart clean — without platform compaction or manual copy-paste.
+**A Pi extension that gives the LLM tools to manage its own context.** `spawn`, `notebook`, and `handoff` let the agent actively isolate work, persist reusable knowledge, and restart clean — without platform compaction or manual copy-paste.
 
 ---
 
@@ -40,7 +40,7 @@ Then disable pi's built-in compaction so handoff stays in control:
 }
 ```
 
-That's it. Your agent now has `spawn`, `ledger_add`, `ledger_get`, `ledger_list`, and `handoff`. The status bar shows context usage and ledger count.
+That's it. Your agent now has `spawn`, `notebook_write`, `notebook_read`, `notebook_index`, and `handoff`. The status bar shows context usage and notebook count.
 
 ---
 
@@ -49,10 +49,10 @@ That's it. Your agent now has `spawn`, `ledger_add`, `ledger_get`, `ledger_list`
 | Feature | What it looks like |
 |---------|-------------------|
 | **Context usage %** | `ctx 65%` in status bar — green < 30%, yellow < 50%, orange < 70%, red ≥ 70% |
-| **Ledger count** | 📒 `3` when entries exist, hidden when empty |
+| **Notebook count** | 📒 `3` when pages exist, dim `📒 0` when empty |
 | **`/handoff` command** | Instant pivot — agent drafts brief, compacts context, resumes |
-| **`/ledger` command** | Overlay showing all entries with previews |
-| **Auto-rehydration** | Ledger entries survive session restarts |
+| **`/notebook` command** | Overlay showing all notebook pages with previews |
+| **Auto-rehydration** | Notebook pages survive session restarts |
 | **Spawn transparency** | Watch child agents work in real time in the TUI |
 | **Token cost visibility** | Each spawn reports input/output tokens, cache hits, and cost |
 | **No polling** | Writes serialized via a process-local lock — no race conditions |
@@ -86,17 +86,17 @@ You: "Add OAuth to the backend"
   spawn("audit current auth code")
          │
          ▼
-  ledger_add("oauth-decisions", "Flow: PKCE. Scope: read+write.")
+  notebook_write("oauth-decisions", "Flow: PKCE. Scope: read+write.")
          │
          ├── spawn("implement token endpoint")
          └── spawn("write tests")
          │
          ▼
   handoff("Wire OAuth routes into the middleware stack.
-           Ledger 'oauth-decisions' holds the constraints.")
+           Notebook page 'oauth-decisions' holds the constraints.")
 ```
 
-The agent decided to spawn research children, save reusable findings to the ledger, delegate implementation subtasks, and handoff when context got noisy. **You said one sentence.**
+The agent decided to spawn research children, save reusable findings to the notebook, delegate implementation subtasks, and handoff when context got noisy. **You said one sentence.**
 
 ---
 
@@ -106,15 +106,15 @@ The agent decided to spawn research children, save reusable findings to the ledg
 
 Delegate messy work to an isolated child agent with clean context. The child inherits the parent's model and tools, works independently, and returns only the condensed result. Siblings run in parallel; the parent stays focused on orchestration. Children cannot spawn grandchildren (explosive branch prevention).
 
-### Ledger — Continuity Across Cuts
+### Notebook — Continuity Across Cuts
 
-A sparse continuity cache the agent curates while working. After discovering something reusable — a fact, constraint, decision, or expensive finding — it saves a named entry. Later contexts fetch entries on demand instead of re-deriving the work. The ledger persists across handoffs, context resets, and session restarts.
+A sparse pocket notebook the agent curates while working. After discovering something reusable — a fact, constraint, decision, or expensive finding — it writes a named page. Later contexts read pages on demand instead of re-deriving the work. The notebook persists across handoffs, context resets, and session restarts.
 
 ### Handoff — Deliberate Compaction
 
-When context degrades or the job changes, the agent saves reusable state to the ledger, writes a focused brief preserving what's still missing, and restarts clean. The new context starts with the brief front-and-center, all ledger entries accessible, and zero noise.
+When context degrades or the job changes, the agent saves reusable state to the notebook, writes a focused brief preserving what's still missing, and restarts clean. The new context starts with the brief front-and-center, all notebook pages accessible, and zero noise.
 
-**Rule of thumb:** The ledger holds reusable learned knowledge. Handoff carries the remaining situational context.
+**Rule of thumb:** The notebook holds reusable learned knowledge. Handoff carries the remaining situational context.
 
 ---
 
@@ -139,7 +139,7 @@ A single summary blob mixes durable knowledge with transient situational context
 | Operation | Primitive | What It Prevents |
 |-----------|-----------|-----------------|
 | **Isolate** | Spawn | Context pollution from noisy subtasks |
-| **Persist** | Ledger | Knowledge loss across resets and pivots |
+| **Persist** | Notebook | Knowledge loss across resets and pivots |
 | **Compact** | Handoff | Degradation from overstuffed context |
 
 ---
@@ -150,10 +150,10 @@ A single summary blob mixes durable knowledge with transient situational context
 |---|---|---|---|---|
 | **Compaction** | Runtime decides | User decides | Manual wipe + copy-paste | **Agent decides** |
 | **Subagents** | Pre-defined or manual trigger | None | None | **Agent spawns dynamically** |
-| **Persistent memory** | Background-generated (if at all) | None | None — gone on reset | **Ledger — agent-curated reusable continuity** |
+| **Persistent memory** | Background-generated (if at all) | None | None — gone on reset | **Notebook — agent-curated reusable continuity** |
 | **Context awareness** | Token count only | Token count only | None | **Primacy-zone heuristic (~30%)** |
-| **Cross-session continuity** | Rare (opt-in, background) | Manual copy-paste | Manual copy-paste | **Ledger persists across restarts** |
-| **Structured handoff** | No | No | No | **Yes — resets context while carrying forward non-ledger state explicitly** |
+| **Cross-session continuity** | Rare (opt-in, background) | Manual copy-paste | Manual copy-paste | **Notebook persists across restarts** |
+| **Structured handoff** | No | No | No | **Yes — resets context while carrying forward non-notebook state explicitly** |
 
 ---
 
@@ -166,18 +166,18 @@ The extension hooks into pi's lifecycle:
 
 | Hook | What it does |
 |------|-------------|
-| `before_agent_start` | Injects context management primer + live ledger listing into system prompt |
+| `before_agent_start` | Injects context management primer + live notebook index into system prompt |
 | `context` | Injects advisory watchdog reminders when context > 30% |
-| `session_start` | Rehydrates ledger from persisted entries; resets on `/new` |
-| `turn_end` | Updates TUI indicators (context %, ledger count) |
+| `session_start` | Rehydrates notebook pages from persisted entries; resets on `/new` |
+| `turn_end` | Updates TUI indicators (context %, notebook count) |
 | `agent_end` | Records last context usage percent |
 | `session_before_compact` | Consumes pending handoff task and sets it as compaction summary |
 
 All state lives in a single `AgenticodingState` instance:
 
 ```typescript
 interface AgenticodingState {
-  ledger: Map<string, string>
+  notebookPages: Map<string, string>
   epoch: number
   lastContextPercent: number | null
   pendingHandoff: { task, source } | null
@@ -193,7 +193,7 @@ interface AgenticodingState {
 <details>
 <summary><strong>Deep dive → ARCHITECTURE.md</strong></summary>
 
-See [ARCHITECTURE.md](ARCHITECTURE.md) for full module breakdown, tool schemas, lifecycle wiring, spawn child-session lifecycle, and ledger rehydration algorithm.
+See [ARCHITECTURE.md](ARCHITECTURE.md) for full module breakdown, tool schemas, lifecycle wiring, spawn child-session lifecycle, and notebook rehydration algorithm.
 
 </details>
 

handoff/command.ts

@@ -37,7 +37,7 @@ export function registerHandoffCommand(pi: ExtensionAPI, state: AgenticodingStat
 			}
 
 			pi.sendUserMessage(
-				`Handoff direction: ${direction}\n\nPrepare a real handoff in the current session and current context. Before calling the handoff tool, capture any reusable state in the ledger if needed. Then complete the picture in a concise but sufficiently detailed handoff brief and call the handoff tool in this turn. Preserve the important knowledge that is still only present in the current context so the next clean context can start well without re-deriving it. Use any structure that makes the next work unambiguous. Include findings, current state, unresolved questions, failed paths worth avoiding, next steps, refs, constraints, and spawn ideas when useful. Reference ledger entries by name when relevant.`,
+				`Handoff direction: ${direction}\n\nPrepare a handoff in the current session. First, save any durable reusable knowledge to the notebook: findings worth keeping, constraints discovered, decisions made, or other grounding future contexts will need. Then draft a concise but sufficiently detailed handoff brief capturing only the remaining situational context: current state, blockers, unresolved questions, failed paths worth avoiding, and next steps. The next context will read the notebook on demand, so do not duplicate notebook content in the brief. Use any structure that makes the next work unambiguous. Reference notebook pages by name when relevant.`,
 				ctx.isIdle() ? undefined : { deliverAs: "followUp" },
 			);
 		},

system-prompt.ts

@@ -2,7 +2,7 @@
  * Context management system prompt primer.
  *
  * Injected via before_agent_start into the system prompt.
- * Teaches the LLM about spawn, ledger, and handoff primitives.
+ * Teaches the LLM about spawn, notebook, and handoff primitives.
  */
 
 export const CONTEXT_PRIMER = `
@@ -24,36 +24,54 @@ Delegate isolated work to child agents. They are trusted extensions of you,
 with their own context and the same authority. You receive only condensed
 results. Parent context stays at orchestration level. Siblings run in parallel.
 
-### Ledger — sparse continuity cache
-Continuously maintain the ledger while you work. After meaningful reads,
-research, analysis, decisions, or milestones, either update/refine a ledger
-entry now or consciously skip because nothing reusable was learned. Prefer
-refining existing entries over creating many tiny ones. The current ledger
-listing is available above. Reference entries by name; fetch via ledger_get on
-demand. Never pre-load bodies.
+### Notebook — durable cross-context grounding
+Treat the notebook as durable grounding for future contexts. Each page covers
+one subject, thread, or subsystem. Prefer refining a few living pages organized
+by subject rather than workflow phase. Store only reusable knowledge worth
+carrying across resets: verified facts, architecture learned, decisions and
+rationale, constraints, expensive discoveries, and durable open questions.
 
-### Handoff — complete the picture, then continue cleanly
+Treat notebook_index as the notebook index. Scan it at task start, after handoff,
+before replanning, or when stuck. Use notebook_read to open only relevant pages.
+Use them to ground a fresh context, avoid repeated work, and resume a subject
+quickly. Verify stale notes before relying on them. Avoid raw transcripts, logs,
+or large tool output. Reference pages by name; fetch on demand; never pre-load
+bodies.
+
+### Active notebook topic — current semantic frame
+The active notebook topic names the current high-level frame for this session.
+If the current work still fits that topic, prefer spawn for isolated noisy
+subtasks so the parent stays focused. If the work no longer fits that topic,
+prefer handoff over dragging stale context forward. After handoff, assign a
+fresh topic again in the next context.
+
+### Handoff — distilled next task
 When the job changes, or when context is noisy past the ~30% heuristic, use
 handoff to finish extracting what matters from the current context before the
-cut. Save reusable state to the ledger when useful, then draft a handoff brief
-that preserves the important knowledge still missing from the ledger.
-Handoff compacts the active session around that brief so the next turn starts
-in a clean context with the right picture already in view. Full history remains
-in the session file for the user.
+cut. Save durable reusable knowledge to the notebook first, then draft a
+handoff brief that carries only the situational context still missing: current
+state, blockers, unresolved questions, failed paths worth avoiding, and next
+steps. Handoff compacts the active session around that brief so the next turn
+starts in a clean context with the right direction already in view. Full history
+remains in the session file for the user.
 
-Use any structure that keeps the next work unambiguous. Include the current
-state, important findings, unresolved questions, failed paths worth avoiding,
-next steps, refs, constraints, and spawn ideas when useful. The handoff should
-help the next context start well without re-deriving what you already learned.
+The next context should use the notebook for grounding and the handoff brief
+for direction. Reference notebook pages by name; do not duplicate their content
+in the brief. The handoff should help the next context start well without
+re-deriving what you already learned.
 
 ### Rules
-- Maintain the ledger as a constant working process; do not wait for handoff
-- Cache reusable state in the ledger; handoff should also capture the missing context that has not been recorded yet
-- Prefer refining existing entries over creating many tiny ones
-- After meaningful work, either update/refine the ledger or intentionally skip
-- Reference ledger entries by name when useful; fetch bodies on demand
+- Maintain the notebook deliberately; update it when you learn durable knowledge worth carrying across contexts
+- One page = one subject, thread, or subsystem
+- Prefer subject pages over workflow-phase pages
+- Use notebook_index as the index before starting, resuming, or replanning
+- Use notebook_read to open only relevant pages
+- Keep pages compact; avoid raw dumps, repeated tool output, scratch reasoning, and local task state
+- Use compact sections such as Facts / Architecture / Decisions / Constraints / Open questions when helpful
+- Separate facts, guesses, and decisions when useful
 - Use spawn to delegate isolated subtasks when it helps; parent orchestrates and merges results
+- Treat the active notebook topic as the current semantic frame: same topic → spawn bias, different topic → handoff bias
 - Call handoff at job boundaries: research→execution, planning→execution
-- Past ~30%, consider handoff when the phase is done or context noise is hurting focus
-- After handoff, ledger_get entries as needed — not all at once
+- Use handoff to pass the distilled next task and immediate starting state
+- After handoff, fetch only the pages you need and assign a fresh topic again
 `.trim();