Module memory_delivery_handlers 

The endpoints Claude Code’s SessionStart hook calls to deliver an agent’s memory (docs/specs/SPEC_GLOBAL_MEMORY_DELIVERY_2026_09_27.md §7 P2). The composition and the part rules are backend::memory_delivery.

• POST /api/v1/agent/memory/session-start/part — one part. Each of the HOOK_PARTS hook commands asks for its own part number. They run in parallel, so the first request for a (block, session, reason) composes the delivery and caches it, and every other part comes from that same composition.
• POST /api/v1/agent/memory/session-start/ack — a hook wrote its part to Claude. Once every part is acknowledged the delivery is complete: the pane gets one persisted agentmux_memory_injected frame naming each entry and its size (owner decision D11). A part fetched but never acknowledged (the hook crashed or timed out) leaves the delivery incomplete, and no notice claims otherwise.

The agent comes from the request’s credential (X-Agent-Token → Caller::Agent): its Personal Memory is that agent’s. Without a token only Global Memory is delivered.

Structs

AckRequest 🔒

Delivery 🔒

DeliveryKey 🔒

DeliveryState 🔒

Deliveries and fallback claims, behind one lock so “who claimed this event first” is decided atomically.

EntrySize 🔒

One item of a delivery as the notice shows it: one card row (SPEC_CONTEXT_DELIVERY_2026_09_30 §3.1, §3.4). label and source are what older builds read; the rest is per-item detail. Sizes are those of what was delivered, so an item cut by the part cap reports its slice.

FallbackDelivery 🔒

A re-delivery srv composed for the frontend’s fallback (CD2b).

LaunchDirs 🔒

Where a session’s CLI looked for its startup files.

PartRequest 🔒

PartResponse 🔒

StartupDetail 🔒

What a startup_file item adds (SPEC_LAUNCH_CONTEXT_WORKSPACE_RULE_AND_ STARTUP_FILES_2026_09_30.md §4.1, backend::startup_files).

Enums

FallbackClaim 🔒

What the fallback’s claim found.

Constants

BOUNDARY_ORIGINS_MAX 🔒

How many compaction boundaries’ origins are remembered. Boundary uuids are unique across blocks.

CLAIM_WINDOW_MS 🔒

How long a claim on one event (a session start, a compaction) holds: the hook and the frontend’s fallback for the same event arrive within seconds of each other, and one block has no two such events that close. Not for a fallback that waited behind a turn: a dated claim (DeliveryState::claim_event) covers that.

DELIVERY_TTL_MS 🔒

How long a composed delivery stays cached for its remaining parts and acknowledgements. The hooks of one session start run within seconds.

EVENT_SLACK_MS 🔒

A fresh session’s agentmux_session_outcome frame can be written just after the respawn it reports (retry_after_resume_failure), so a hook delivery composed up to this long before the frame is still that session’s.

FALLBACK_TTL_MS 🔒

How long a composed fallback delivery waits for its hidden message. The frontend sends it right after composing, unless the pane turned busy.

PENDING_POLL 🔒

PENDING_WAIT 🔒

How long the fallback waits for a hook delivery still in flight, and how often it looks. A hook that never finishes must not leave the agent with no memory, so after this the fallback delivers instead.

Statics

STATE 🔒

Functions

acknowledge 🔒

Marks part written. True exactly once: when this makes every part written and no notice has gone out yet.

claim_fallback 🔒

Whether the frontend’s hidden-reinjection fallback should deliver this event (true) or stand down because the SessionStart hook delivered it (false). Waits out a hook delivery still in flight for up to PENDING_WAIT, then lets the fallback deliver, so a hook that died part-way never leaves the agent without its memory. With a boundary_uuid, only the block whose CLI compacted can deliver. With event_at_ms (a fresh session’s time), the hook’s delivery for that session counts however late the claim comes.

compose_delivery 🔒

Reads the memory and composes the delivery. None when there is nothing to deliver. A new session’s delivery also lists the startup files the CLI loaded from launch (startup_items), ahead of the memory items.

compose_fallback_delivery 🔒

Composes the fallback’s hidden message from the same memory the hook delivers (global_entries, personal_entries), and the card that will stand for it. None when there is no memory.

delivery_items 🔒

The notice’s items, in delivery order, sized by what the parts carried.

fallback_frame 🔒

The card for a fallback re-delivery: the hook notice’s shape, under the delivery’s own id. fallback: true tells replay that the hidden message right after it is this delivery’s echo, not a second one.

global_entries 🔒

Global Memory as the startup file carries it — its sections, Operator Config first (globalmemory:sections, P1).

global_memory_in_startup_files 🔒

Whether the CLI already got the current Global Memory from a startup file: one AgentMux wrote that holds every current section, byte for byte. A foreign or stale file with some old section doesn’t count, or the hook would drop current entries the agent never saw (Codex on #4131).

handle_session_start_ack 🔒

POST /api/v1/agent/memory/session-start/ack

handle_session_start_part 🔒

POST /api/v1/agent/memory/session-start/part

in_startup_file_item 🔒

A Global Memory entry that reached the agent through its startup file: listed in the card, sized 0 (the file’s own row counts it).

notice_frame 🔒

The persisted notice (D11): which memory was delivered, and each entry’s size. id is stable for the delivery, so a live frame and a replay of the same line render once.

part_response 🔒

personal_entries 🔒

The agent’s Personal Memory files from its latest spawn’s memory folder, by name, without the MEMORY.md index (the CLI’s own table of contents).

personal_entries_in 🔒

reason_for_fallback 🔒

The event a frontend reinjection reason stands for: a compaction, or a fresh session (a spawn without --resume, whose hook source is startup). None for anything else.

record_compaction_boundary 🔒

Records that block_id’s CLI wrote the compaction boundary uuid. Called from its stdout reader, before the line reaches any pane.

register_memory_delivery_handlers 🔒

Registers memorydelivery:claim_fallback — the frontend’s hidden memory reinjection asks it right before it would fire — and memorydelivery:compose, which composes what it sends.

send_partless_notice 🔒

A delivery with nothing for the hook to carry (its Global Memory is in the startup file, and there’s no Personal Memory) still has a card: written on the first part request, exactly once, since no part will be acknowledged.

startup_card_written_since 🔒

Whether block_id’s new-session card went out for a delivery composed after since_ms: what the continued-session note waits for (backend::continued_note).

startup_files 🔒

The files the CLI read by itself at session start.

startup_items_of 🔒

state_lock 🔒

take_fallback_frame 🔒

The card of the fallback delivery delivery_id, taken once, when its hidden message reaches srv. None for an unknown or expired id, or one composed for another block.