[jonaslsaa]

With SqliteStore's images option (R2, say), memory keeps its copy of an image outside the database, but Pi Durable still stores every image as base64 in its transcript rows. The database grows with each image, and a message's images must fit one 2 MB row together.

What changes

Each image in a durable chat now lives once, in memory's store; Pi's transcript row holds only its ref, [image <16 hex digits>], the same ref memory already uses. The code is in src/durable/images.ts; optchat.ts only wires the hooks.

• Tool results (afterTool, always on): a model-issued tool's images are put in the store and replaced by their refs. Nested calls are left alone, and so is a result whose text could pass Pi Durable's default bound (50 KB or 2,000 lines) with the refs: Pi bounds a result after the hook by keeping one of its text blocks, which would drop them.
• User messages (offloadImages(input), new, opt-in): Pi Durable has no user-input hook, so the app passes an input through it before submit. If it doesn't, images stay inline as today.
• Requests (beforeRequest): once a request is built, exact ref blocks in its user messages and tool results are swapped back for the images, each read once per request; steps a refresh dropped are never read. A ref counts as an image in the refresh estimate and survives boundedMessage's cap (core messages.ts). Restoring never throws: an unknown ref or a failed read is sent as the text.

A failed put keeps that image inline. Memory's text is byte-identical to before (zoom's own results drop the refs they would add), and zoom still returns the image, also after a restart. The compactor only switches its image labels to ref (one line in src/core/compactor.ts).

Hosts that read Pi's transcript themselves see refs instead of images; docs/durable.md says how to get them (memory.store.image(name)) and how hook order works.

pi-optchat/core now exports ref(name) and refName(text), the one ref format Pi and durable both use, built on core's existing REF pattern, plus loadImage(store, name). The compactor's image labels (#284) use ref too, so there is one ref format.

Closes #282

[Copilot]

🟡 Changes recommended

Unresolved image-handling defects can discard trailing newlines, replace zoom images with text, and repeatedly reload images excluded after refresh.

4 open issues

• Reject ref matches with a trailing newline · New
• Preserve stored image keys when restoring zoom images · New
• Restore images only after selecting messages for the refreshed run · New
• Clarify hook ordering for each lifecycle hook · New

What changed in this PR

This PR reduces Pi Durable transcript storage by keeping images in memory’s image store and recording references in transcript rows, addressing #282.

Changes:

• Offloads tool-result images automatically and adds opt-in offloading for user inputs.
• Restores image references for model requests, with inline or text fallbacks when storage operations fail.
• Shares core reference helpers and adds integration tests and host documentation.

File	Description
test/​durable.test.ts	Tests offloading, restoration, restart behavior, and storage failures.
src/​images.ts	Uses the shared core image-reference formatter.
src/​durable/​optchat.ts	Wires image hooks and exposes offloadImages.
src/​durable/​images.ts	Implements image naming, storage, restoration, and bounds checks.
src/​core/​index.ts	Exports the shared reference helpers.
src/​core/​images.ts	Adds reference formatting and parsing helpers.
docs/​durable.md	Documents transcript references, fallback behavior, and hook ordering.

_{Review effort: Balanced}