Skip to content

Product Book Notebook

Grzegorz Nowak edited this page Oct 6, 2026 · 11 revisions

Notebook — Short-Lived Shared Memory

Part of the Product Book. Notebook size contract updated to merged 238d5d9 (PR #43), following 48b5241 → 0ac9fd6 (PR #60) → 238d5d9; authored from wiki c3b4c44. Other behaviour retains the 48b5241 baseline; this is not a whole-book rebaseline.

The notebook is pi-schematic's shared, deliberately short-lived memory. It gives the agent a small set of named Markdown pages it can write, read, and list while working, so that decisions and other hard-won knowledge survive deliberate context cuts inside one task. It is not a long-lived memory product: pages belong to the current work stream and disappear with it. The implementation-level docs/notebook.md inventory (NB-* IDs) is on an unmerged branch and predates this contract; its clipping claims need a separate refresh.

1. Pages, topics, and why the notebook is short-lived

A notebook is a set of agent-named pages, where each name maps to one Markdown body. Pages are scoped to the active session branch and work stream rather than providing forever memory. The product doctrine states the split plainly: re-derivable code facts are discardable cache material to be dropped at handoff, while non-recoverable user guidance, learned approaches, design, task scope, and working memory are kept and refreshed. That is the whole point of coupling memory to the task instead of building an archive that rots — a page is working state, not a durable record. When the session ends, /new clears both the pages and the active topic, so the next piece of work starts clean.

2. Writing and refining pages

The agent writes with notebook_write, which requires a string name and a string content. Names are kebab-case by preference, described as stable, subject-oriented identifiers. Writing to a name that already exists replaces its whole body, so a same-name write is a refinement rather than an append or merge — this is how a page is expected to evolve as understanding improves. Writes are serialized, so competing same-name writes take effect in completion order. A successful write reports Saved notebook page "<name>". and includes the current page list, letting the agent confirm what now exists.

Content is still head-truncated at the first of 2,000 lines or 50 KiB (51,200 bytes), keeping the beginning and dropping the tail. Final result and onUpdate text add TRUNCATED by lines|bytes: kept N of M lines (X of Y bytes); tail dropped. Split this page into smaller pages. Their details carry an ephemeral truncation report and clipped boolean; complete writes carry null and false.

A truncated write retaining zero bytes is rejected before page, flag, epoch or session-entry mutation. An oversized first line reports first line exceeds 50 KiB (51200 bytes); a blank first line followed by an oversized line reports the first non-empty line exceeds 50 KiB (51200 bytes), so truncation would retain no content. Both errors name the rejected page and advise shorter lines or smaller pages. An intentionally empty, untruncated write remains valid. No page-count cap or accumulated-size warning is exposed. Write tool and content-parameter descriptions explain caps, head retention, reporting and empty-head rejection; cap wording derives from applied host constants.

3. Reading and listing pages

Reading is symmetric and cheap. notebook_read requires a page name and returns its full stored body between --- <name> --- delimiters. A flagged page appends Notice: This page was clipped at write time; its stored body is incomplete. and sets details.clipped to true; complete pages omit the notice and expose false. The read description documents the notice. Reading a missing page does not throw; it reports Notebook page "<name>" not found. and returns the current page list. notebook_index takes no parameters and lists pages alphabetically as a name plus a first-line preview, or shows (empty). A preview is the page's first line capped at 80 characters; a longer line shows 77 characters followed by .... The index therefore carries names and one line each, never bodies.

Because a preview is a display limit, not a completeness check, clipped and complete pages can still look identical in the index. No marker was added to plain previews, index, or system-prompt/spawn listings. The read notice is deliberately model-visible: only the [truncated] badge is human-only, not all clipping information. A stale or reset child attempting notebook access receives Spawn invalidated by reset. rather than silently reading stale pages.

4. The active topic and what the operator sees

A topic names the current semantic frame — the subject the work stream is about. The agent sets one with notebook_topic_set, which requires a string topic. A topic is normalized by trimming, lowercasing, replacing non-alphanumeric runs with -, trimming edge dashes, and limiting the result to 80 characters; one that normalizes to empty is rejected with Notebook topic cannot be empty. With no active topic, the tool establishes an agent-sourced topic and reports its normalized value. Setting the same normalized topic again is a no-op that reports it is already set.

A topic is not agent-replaceable. notebook_topic_set cannot change an existing topic; it directs the agent to hand off instead, and a human-set topic is authoritative — the tool's rejection explicitly says it cannot override one. The operator's own entry points are the commands. /notebook <topic> sets a human-sourced topic, and when it changes an existing topic the UI warns that this is a likely task boundary and recommends handoff before continuing. /notebook without an argument opens a UI page selector when a UI is available; selecting a page shows at most its first 500 characters, followed by ... when clipped.

The status bar keeps this state visible: 🧭 <topic> when a topic is set, dim 🧭 - when none is, and 📒 N for the page count, or dim 📒 0 when empty so notebook availability stays discoverable. A successful handoff clears the active topic, requiring the next context to establish a fresh semantic frame. The selector now appends a human-only [truncated] suffix to clipped page previews (or [truncated] for an empty preview), distinguishing write-time loss from the 500-character display limit. Custom write/read tool renderers remain unchanged; result-text reports and notices do not imply badges or reports in those renderers.

5. Continuity across branches and handoff pruning

Pages survive handoff and resume within the same work stream because they are stored in session custom entries. Page content is stored durably with its committed generation, so a resume reconstructs the newest committed version rather than an abandoned one. Committing a generation makes the current page set visible, and a newer committed generation supersedes earlier ones. On session start and on session-tree navigation, the visible notebook is reconstructed from the active branch: reconstruction scans page entries newest-to-oldest and retains only pages in the committed generation. Navigating to another branch therefore shows that branch's pages without cross-contamination, and returning to an earlier branch restores its state.

Optional clipped?: boolean metadata extends existing v1 page entries without a version bump, follows reconstruction and discard survivors, clears on complete overwrite, and remains unchanged on rejection. Legacy absent flags mean no recorded clipping, not proven completeness. Retained/submitted quantities are not persisted.

Handoff is also the moment for pruning. The handoff tool accepts optional discardPages page names to remove stale pages, since a page that has drifted is worse than a missing one. Requested discards are staged and become visible only after successful handoff compaction — a transactional step, so a failed handoff does not quietly lose pages. If a discard cannot be committed after compaction, all pages are retained and the handoff completion reports a warning.

6. Delegation and the always-on surfaces

The notebook is shared machinery, not a single-context scratchpad. Every agent start injects an ## Active Notebook Topic section, including either the topic and its source or a no-topic prompt. When pages exist, every agent start also injects ## Active Notebook Pages with page names and first-line previews — not page bodies. Spawned children receive shared notebook_write, notebook_read, and notebook_index access, so pages are visible across parent and child contexts, and a child's findings become part of the same work-stream memory. Bodies are fetched by name on demand, which is why the injected listing carries previews.

Appendix — baseline behaviour rows

PB-NOTEBOOK-01 … 49 — 49 atomic behaviour rows; size-contract update at 238d5d9

Evidence prefixed 238d5d9: cites the merge. Unprefixed citations retain historical 48b5241 anchors for unchanged claims, including KEEP rows -16 and -19. Read line numbers at the stated revision. The linked NB-* inventory above has not been refreshed.

Proposal provenance: the original #42 index-marker idea did not ship. The revised issue already makes -14/-15 KEEP and requests the durable flag, read notice and human-only badge instead. Merged code also rejects blank-first-line zero-content truncation. Selector badges shipped; custom tool-renderer badges did not.

1. Page model and writing

ID Behaviour Evidence
PB-NOTEBOOK-01 A notebook is a set of agent-named pages, each mapping one name to one Markdown body. state.ts:16
PB-NOTEBOOK-02 Pages are scoped to the active session branch and work stream, rather than providing forever memory. docs/architecture.md:52
PB-NOTEBOOK-03 notebook_write requires string name and string content parameters. notebook/tools.ts:19-30
PB-NOTEBOOK-04 notebook_write describes kebab-case names as a preference for stable, subject-oriented identifiers. notebook/tools.ts:19-22
PB-NOTEBOOK-05 Writing an existing page name replaces its whole body, making same-name writes a refinement rather than an append or merge. notebook/tools.ts:67-70; notebook/store.ts:90-98
PB-NOTEBOOK-06 Notebook writes are serialized, so competing same-name writes take effect in completion order. notebook/tools.ts:65-70; notebook/store.ts:24-49
PB-NOTEBOOK-07 A successful write reports Saved notebook page "<name>". and the current page list; clipped writes also report retained amounts and advise splitting. 238d5d9:notebook/tools.ts:124-155
PB-NOTEBOOK-08 The notebook doctrine treats re-derivable code facts as discardable cache material at handoff. system-prompt.ts:30-34
PB-NOTEBOOK-09 The notebook doctrine says to keep and refresh non-recoverable user guidance, learned approaches, design, task scope, and working memory. system-prompt.ts:30-35

2. Reading, indexing, and content limits

ID Behaviour Evidence
PB-NOTEBOOK-10 notebook_read requires a string page name. notebook/tools.ts:32-36
PB-NOTEBOOK-11 Reading an existing page returns its full stored body between --- <name> --- delimiters, plus a notice when clipped at write time (see -48). 238d5d9:notebook/tools.ts:218-233
PB-NOTEBOOK-12 Reading a missing page does not throw; it reports Notebook page "<name>" not found. and returns the current page list. notebook/tools.ts:177-188
PB-NOTEBOOK-13 notebook_index takes no parameters. notebook/tools.ts:38; notebook/tools.ts:209-249
PB-NOTEBOOK-14 notebook_index lists pages alphabetically as name plus first-line preview, or shows (empty). notebook/tools.ts:233-245; notebook/store.ts:51-72
PB-NOTEBOOK-15 A page preview is its first line, capped at 80 characters; longer lines show 77 characters followed by .... notebook/store.ts:51-60
PB-NOTEBOOK-16 notebook_write head-truncates content at the first of 2,000 lines or 50 KiB, retaining the beginning rather than the tail. notebook/tools.ts:25-30; notebook/store.ts:5-8; notebook/store.ts:81-86
PB-NOTEBOOK-17 Clipped writes report limiting dimension, retained/submitted lines and bytes, tail loss and split advice in final/onUpdate text; details contain truncation and clipped. 238d5d9:notebook/tools.ts:22-24,128-155; 238d5d9:notebook/store.ts:141-150
PB-NOTEBOOK-18 Oversized-first-line or blank-first-line truncation retaining zero content is explicitly rejected before mutation; prior body, flag, epoch and entries remain unchanged. Untruncated empty writes remain valid. 238d5d9:notebook/store.ts:118-165
PB-NOTEBOOK-19 No page-count cap or accumulated-page-size warning is exposed. notebook/store.ts:51-98; index.ts:775-802

3. Active topic and /notebook

ID Behaviour Evidence
PB-NOTEBOOK-20 notebook_topic_set requires a string topic parameter. notebook/topic-tool.ts:20-26
PB-NOTEBOOK-21 A topic is normalized by trimming, lowercasing, replacing non-alphanumeric runs with -, trimming edge dashes, and limiting the result to 80 characters. notebook/topic.ts:13-20
PB-NOTEBOOK-22 A topic that normalizes to empty is rejected with Notebook topic cannot be empty. notebook/topic.ts:22-29
PB-NOTEBOOK-23 With no active topic, notebook_topic_set establishes an agent-sourced topic and reports its normalized value. notebook/topic-tool.ts:46-53
PB-NOTEBOOK-24 Setting the same normalized topic again is a no-op that reports it is already set. notebook/topic-tool.ts:38-45
PB-NOTEBOOK-25 notebook_topic_set cannot change an existing topic; it directs the agent to handoff instead. notebook/topic-tool.ts:29-37
PB-NOTEBOOK-26 A human-set topic is authoritative: the agent tool's rejection explicitly says it cannot override it. notebook/topic-tool.ts:29-34
PB-NOTEBOOK-27 /notebook <topic> sets a human-sourced topic. index.ts:648-655
PB-NOTEBOOK-28 When /notebook <topic> changes an existing topic, the UI warns that it is a likely task boundary and recommends handoff before continuing. index.ts:652-661
PB-NOTEBOOK-29 A successful handoff clears the active topic, requiring the next context to establish a fresh semantic frame. handoff/tool.ts:153-166; system-prompt.ts:49-52
PB-NOTEBOOK-30 /new clears both notebook pages and the active topic. state.ts:216-230
PB-NOTEBOOK-31 The status bar shows 🧭 <topic> when set and dim 🧭 - when no topic is active. tui.ts:72-78

4. Continuity, branch reconstruction, and handoff pruning

ID Behaviour Evidence
PB-NOTEBOOK-32 Pages survive handoff and resume within the same work stream because they are stored in session custom entries. docs/architecture.md:52; notebook/store.ts:90-98
PB-NOTEBOOK-33 Page content is stored durably with its committed generation, so a resume reconstructs the newest committed version rather than an abandoned one. notebook/store.ts:93-98
PB-NOTEBOOK-34 Committing a generation makes the current page set visible; a newer committed generation supersedes earlier ones. notebook/store.ts:126-130; notebook/store.ts:147-149
PB-NOTEBOOK-35 On session start and session-tree navigation, the visible notebook is reconstructed from the active branch. notebook/rehydration.ts:1-15; notebook/rehydration.ts:126-134; index.ts:960-969
PB-NOTEBOOK-36 Reconstruction scans page entries newest-to-oldest and retains only pages in the committed generation. notebook/rehydration.ts:84-107
PB-NOTEBOOK-37 Handoff accepts optional discardPages page names to remove stale pages. handoff/tool.ts:302-315
PB-NOTEBOOK-38 Requested page discards are staged and become visible only after successful handoff compaction. notebook/store.ts:107-144; handoff/tool.ts:339-360
PB-NOTEBOOK-39 If a discard cannot be committed after compaction, all pages are retained and the handoff completion reports a warning. handoff/tool.ts:233-246

5. Agent, child, and TUI surfaces

ID Behaviour Evidence
PB-NOTEBOOK-40 Every agent start injects an ## Active Notebook Topic section, including either the topic/source or a no-topic prompt. index.ts:752-774
PB-NOTEBOOK-41 When pages exist, every agent start injects ## Active Notebook Pages with page names and first-line previews, not page bodies. index.ts:775-801
PB-NOTEBOOK-42 Spawned children receive shared notebook_write, notebook_read, and notebook_index access, so pages are visible across parent and child contexts. spawn/index.ts:327-342
PB-NOTEBOOK-43 /notebook without an argument opens a UI page selector when a UI is available. index.ts:663-688
PB-NOTEBOOK-44 Selecting a page in the /notebook overlay shows at most its first 500 characters, followed by ... when clipped. index.ts:696-715
PB-NOTEBOOK-45 The status bar shows 📒 N pages, or dim 📒 0 when empty so notebook availability remains discoverable. tui.ts:49-57

6. Write-size contract additions (PR #43)

ID Behaviour Evidence
PB-NOTEBOOK-46 Write tool and content-parameter descriptions state caps, head retention, reporting and empty-head rejection; cap wording derives from DEFAULT_MAX_LINES / DEFAULT_MAX_BYTES. 238d5d9:notebook/tools.ts:10,17-20,34-39,79-85
PB-NOTEBOOK-47 Optional v1 clipped metadata records latest accepted write clipping, survives reconstruction and discard staging, and clears on complete overwrite; absent legacy flags mean no recorded clipping. Quantities are not persisted. 238d5d9:notebook/store.ts:156-165,202-211; 238d5d9:notebook/rehydration.ts:17-23,104-112
PB-NOTEBOOK-48 A flagged page's read result appends Notice: This page was clipped at write time; its stored body is incomplete. and exposes details.clipped; complete pages omit the notice. The read description explains it. 238d5d9:notebook/tools.ts:163-167,218-233
PB-NOTEBOOK-49 /notebook selector previews append the human-only [truncated] badge for flagged pages; plain previews/index and model listings remain undecorated. Stored bodies are unchanged by the badge. 238d5d9:notebook/store.ts:55-82; 238d5d9:index.ts:689-693

Clone this wiki locally