Repository navigation
Product Book Notebook
Part of the Product Book. Observable product behaviour at
pi-schematic@36bd569(main, 2026-10-12).
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.
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.
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. The notebook store serializes writes, 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.
notebook_write truncates content 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.
notebook_write rejects a truncated write retaining zero bytes before mutating the page, flag, epoch or session entry. 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.
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. Plain previews, index, and system-prompt/spawn listings carry no clipping marker. 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.
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. notebook_topic_set normalizes a topic by trimming, lowercasing, replacing non-alphanumeric runs with -, trimming edge dashes, and limiting the result to 80 characters; it rejects one that normalizes to empty 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 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 have no clipping badges; the reports and notices described here are result text.
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, pi-schematic reconstructs the visible notebook 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.
Some branch operations carry the notebook forward and others roll it back. /tree moves the current position within one session file, so pi-schematic keeps showing the selected branch's pages. /fork and /clone instead start a new session file, and pi-schematic reconstructs the notebook from that session's active branch: a fork taken from an earlier user message copies the branch only up to that message, so pages written after the fork point are absent and the notebook reverts to its state there, while a clone copies the whole active branch, so every current page carries into the new session. A fork taken before the session's first user message has an empty branch and therefore an empty notebook.
Pages follow the branch; the active topic does not. pi-schematic keeps the topic as in-memory session state rather than a persisted session entry, so navigating the tree never restores a saved per-branch topic: /tree leaves the current topic in place, and a resumed or newly forked session carries no topic from its session history. Only /new and a successful handoff clear the topic deliberately, so the next context starts with a fresh frame.
Page entries use v1 with optional clipped?: boolean metadata. The flag 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. The handoff tool stages requested discards, which become visible only after successful handoff compaction — a transactional step, so a failed handoff does not quietly lose pages. If pi-schematic cannot commit a discard after compaction, it retains all pages and the handoff completion reports a warning.
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.
PB-NOTEBOOK-01 … 49 — 49 atomic behaviour rows
Read line numbers at 36bd569.
Clipping visibility: -14/-15 describe index/plain previews with no clipping marker. Clipping is recorded by a durable flag and surfaced through a read notice and human-only selector badge; custom write/read tool renderers have no clipping badges. Blank-first-line truncation that would retain zero content is rejected.
| 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:54 |
| PB-NOTEBOOK-03 |
notebook_write requires string name and string content parameters. |
notebook/tools.ts:29-41 |
| PB-NOTEBOOK-04 |
notebook_write describes kebab-case names as a preference for stable, subject-oriented identifiers. |
notebook/tools.ts:29-32 |
| 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:78-81; notebook/store.ts:154-165
|
| PB-NOTEBOOK-06 | Notebook writes are serialized, so competing same-name writes take effect in completion order. |
notebook/tools.ts:76-81; 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. |
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 |
| ID | Behaviour | Evidence |
|---|---|---|
| PB-NOTEBOOK-10 |
notebook_read requires a string page name. |
notebook/tools.ts:43-47 |
| 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). |
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:199-210 |
| PB-NOTEBOOK-13 |
notebook_index takes no parameters. |
notebook/tools.ts:49; notebook/tools.ts:235-275
|
| PB-NOTEBOOK-14 |
notebook_index lists pages alphabetically as name plus first-line preview, or shows (empty). |
notebook/tools.ts:259-271; 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:35-41; notebook/store.ts:5-8; notebook/store.ts:116-121
|
| 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. |
notebook/tools.ts:22-24,128-155; 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. | notebook/store.ts:118-165 |
| PB-NOTEBOOK-19 | No page-count cap or accumulated-page-size warning is exposed. |
notebook/store.ts:51-165; index.ts:780-807
|
| 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:650-657 |
| 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:654-663 |
| 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:220-235 |
| PB-NOTEBOOK-31 | The status bar shows 🧭 <topic> when set and dim 🧭 - when no topic is active. |
tui.ts:72-78 |
| 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:54; notebook/store.ts:154-165
|
| 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:159-165 |
| PB-NOTEBOOK-34 | Committing a generation makes the current page set visible; a newer committed generation supersedes earlier ones. |
notebook/store.ts:195-199; notebook/store.ts:222-224
|
| 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:132-140; index.ts:965-974
|
| PB-NOTEBOOK-36 | Reconstruction scans page entries newest-to-oldest and retains only pages in the committed generation. | notebook/rehydration.ts:86-113 |
| 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:176-219; 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 |
| 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:754-779 |
| 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:780-806 |
| 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:665-690 |
| PB-NOTEBOOK-44 | Selecting a page in the /notebook overlay shows at most its first 500 characters, followed by ... when clipped. |
index.ts:698-717 |
| PB-NOTEBOOK-45 | The status bar shows 📒 N pages, or dim 📒 0 when empty so notebook availability remains discoverable. |
tui.ts:49-57 |
| 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. |
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. |
notebook/store.ts:156-165,202-211; 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. |
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. |
notebook/store.ts:55-82; index.ts:691-695
|