Huginn/docs/research/2026-10-31-persistent-mind-session-prior-art.md

Persistent Mind session: our Body today, and prior art

Ruling: eureka-body:ruling:mind-self-is-a-persistent-session (Operator, 2026-10-31), joined by eureka-body:ruling:persona-is-append-only-session (Operator, 2026-10-31).

mind-self-is-a-persistent-session: "My hope was that the Self would behave much like my session with you does. You communicate with me about the stuff I asked you to work on, I tell you what's needed, your context persists until clear or compaction, a decision which in Eureka should be based on data"

persona-is-append-only-session: "The personas should also be such a persistent append only session that occasionally refreshes, otherwise we're wasting cache"

Facts only, with evidence pointers. No conclusion or recommendation is drawn. Huginn read at main c7cd9ee (clone, autocrlf false). Web sources accessed 2026-10-31. Marks: [P] primary (vendor docs or repo source), [S] secondary, [N] not verified in this pass. File:line refs are into Huginn main unless a repo is named.

Earlier research this pass builds on and does not repeat: gamecult-ops/docs/research/persistent-self-context-lifecycle.md (5c7dfc8; cited below as LIFECYCLE with its section numbers) and docs/research/2026-10-31-persona-memory-and-voice-prior-art.md (Huginn branch eureka-body/persona-memory-voice-note, bfdf4db).

---

Part A. Our Body today

A1. Persona turn (crates/mind-body/src/persona.rs)

How a turn is built and called

• One mind-persona@<instance> start takes up to MAX_TURNS_PER_START = 4 turns (persona.rs:61, loop at :577-590). It adopts the Persona run the heartbeat opened; no run held, no turns (:576, "only the heartbeat opens Persona turns", header :6-8).
• Each turn makes one tool-less connector call whose output is constrained to the PersonaReply schema (:12-17, :282-296 TurnRequest, :239-280 reply_schema). Reply fields: say[] (room enum, text), start_self_run (null or brief/repo/campaign, brief <= 1000 chars). The reply is decoded, never scanned (:749-760).
• TurnRequest carries: caller, request_id (<run label>-t<turn>, :659), max_cost_micro_usd (what remains of the run cap), instructions, input, output_schema_json (:282-296). It has no session handle or reasoning-state field. The transport builds ProviderRequest with input = [InputItem::UserText { text }] and output_schema_json = Some(..) (connector.rs:72-74): one user text item per call.
• Gates per turn: brake/envelope read before the call and again before each send (:615-619, :684-688); spend readout must have a row for her caller or the run holds (:634-645); window turn or used >= budget ends the start (:647-650).
• After the call: each say is sent with request id <batch>-<index> (idempotent repeat, :682-698); start_self_run is admitted as a follow-up and opens a Self run (:703-715, :763-797); trace is recorded; deliveries are acked through the batch max seq (:717-721).

Tools. None in the turn (tool-less). The claude-connector argv always passes --tools "", --strict-mcp-config, --setting-sources "", --disable-slash-commands, --permission-prompts none, --system-prompt-file (ModelConnector crates/claude-connector/src/launch.rs:112-137). Rulings that change this are in force but not implemented in this code: persona-turns-read-only-tools (Superseded in part by persona-git-personal-sandbox: turns run git inside her bubblewrap sandbox, writes beyond it stay in Self runs), persona-unit-token-reach-bounded (mind-persona@<i> may borrow the token under bounds: whole turn in bwrap, tools confined, Persona-sized reservation, lease bound to the turn's main process before any Persona lease row is configured), cli-over-mcp-agent-surface.

State that carries across turns. Within one start, only locals: after_seq, answered, failure, self_run, start (:567-571). Across starts: nothing in the process. What persists is in the mind and Bifrost: runs and follow-ups (mind), the pending queue and ack position (Bifrost), the Pulse/trace records. The conversation itself is never carried: every call is a fresh claude -p with no handle (see A5). The connector's own comment: a session is "a cache of the caller's transcript; the transcript is the truth" (ModelConnector .../handle.rs:1-4).

How a batch of deliveries is chosen. organs.chat.pending(after_seq) then next_batch (:726-736): sort by seq; take the oldest prefix that shares a conversation, either all public-room deliveries together or one DM room alone; truncate at the first delivery that switches is_direct or (for DMs) room. Ack through the batch's max seq. A wake with no deliveries is allowed for turn 0 (:625-628).

Per-turn content, in the order it is assembled (this answers the cache-layout question; placement is exact):

#	Content	Where it goes	Source / line	Changes when
1	Doctrine files text (MIND_PERSONA_DOCTRINE, <= 96 KiB)	instructions (system prompt file), first	read_doctrine :391-405, re-read every call; :655 format!("{doctrine}{persona}\n\n{campaigns}")	the files are edited
2	Persona state JSON, pretty-printed, prefixed "You are the persona whose state follows"	instructions, after doctrine	HuginnPersona::instructions :379-387, render_instructions :431-434	persona_put
3	Campaigns in force (slug: title list)	instructions, last	campaigns_in_force :407-418, render_campaigns :420-429, :654-655	a campaign opens/closes
4	"Rooms you may speak in: ..."	input (the one user message), line 1	render_input :948	config
5	Static explanatory paragraphs on message framing/roles	input	:949-952	code
6	Burn line (spend readout of her caller row, heat, live Mind-run count)	input	burn_line :873, built :652	every turn (ledger moves)
7	"Your latest runs:" 5 lines (RECENT_RUNS = 5, label, turn kind, how it ended)	input	recent_runs :835-854, :72	any run starts or ends
8	"No new messages. This is a scheduled wake..."	input, only when no deliveries	:958-960	wake turns only
9	Per delivery: its context lines (as earlier), then the message line (room, sender, role, name, to_you, to, text)	input, last	:962-971, message_line :936, addressees :924	every turn

So the system prompt (rows 1-3) is stable across turns while those files/state/campaigns are unchanged; the user message begins with stable lines (4-5) followed immediately by per-turn lines (6, 7) and then the deliveries (9). Nothing is appended to a prior turn's content because each turn is a separate call with no history. The reply schema's room enum (reply_rooms :738-747) and campaign enum (:239-280) are part of --json-schema (not the prompt) and vary with the batch and campaigns in force.

The Bifrost delivery's context is up to 20 lines / 16 KiB read back from Matrix per delivery (A4), so consecutive turns in a busy room re-send overlapping room history inside input.

A2. Self runs (crates/mind-body/src/self_run.rs)

• Process. One claude child per run, spawned by ClaudeSpawner in the mind-self@<instance> unit, with a fresh CLAUDE_CONFIG_DIR copy per child seeded from MIND_SELF_CONFIG_SEED (:104-105, :628-700). Credential = lease descriptor (CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR), not env (:80-82, header :19-27).
• Args (claude_args, :165-186): -p --input-format stream-json --output-format stream-json --verbose --session-id <uuid> --max-budget-usd <run budget> --max-turns 500 --permission-mode bypassPermissions --permission-prompts none --setting-sources user. The doc comment (:155-164): "no resume, continue or fork, no model and no settings of its own belong to this actuator".
• session_id (:151-153): Uuid::new_v5(&SESSION_NAMESPACE, run.id.0.as_bytes()), namespace Uuid::NAMESPACE_OID (:96); "derived, never stored". The run id is new per run, so each run names a new session.
• Start message (:103-108): "Use the eureka skill. You are Self for the instance <slug>; your run is <run id>. Admit as faculty SelfFaculty, agent mind-self-run." plus task_section (:117-...): per claim, the claimed follow-up's item text verbatim, or a pointer "read it with huginn view" for a cut spec (c7cd9ee message: "the start message carries every claim's task").
• Input shape. The start is written as one stream-json user line {"type":"user","message":{"role":"user","content":text}} (drive :575-576); the same line shape carries the flush (FLUSH_MESSAGE :148).
• MAX_TURNS = 500 (:76), "a backstop claude enforces; the ceiling is reached first".
• Context accounting. read_usage (:204-218) takes each main-thread assistant message's input_tokens + cache_read_input_tokens + cache_creation_input_tokens as the request's prefix; subagent requests are ignored. CEILING_TOKENS = 300_000 asks for the flush (:64); FLUSH_HEADROOM_TOKENS = 60_000, FLUSH_GRACE_S = 900, ESCALATE_AFTER_S = 120, EXIT_DRAIN_S = 2 (:67-73). All timing decisions are one pure function, decide (self_run/decide.rs; ruling self-run-decider).
• How a run ends. decide closes stdin at the first result unless a flush is outstanding (decide.rs:123 WriteFlush, :133 CloseStdin); the child exits; an overrun flush is interrupted, then SIGTERM, SIGKILL (header :1-14). carry always resolves her run Recorded exactly once (:489-503, close_if_open :451-464) with the last result as the reason, or "claude gave no result". settle reports per-model usage to the lease (:526-536).
• Result excerpt. Reason text is cut to REASON_EXCERPT_LIMIT = 800 bytes (:542); the journal gets RESULT_TEXT_LIMIT = 4096 (:540), via describe_result (:546-563). The stream is otherwise discarded; no transcript is kept (the runtime directory and fresh config dir go with the unit, :672-680).
• Policy in force that this implements: self-lifecycle-flush-rehydrate (2026-10-20): no summarizing compaction; a run flushes to the mind and ends; "at wake: a cold cache means fresh rehydration; a warm cache with the previous run's thread open may resume it"; ski-rental rental rule; "each run records its prefix size, rehydration size and cache state so the constants are measured". Of these, the ceiling and flush are in code; resume, the rental rule and the recorded sizes are not in self_run.rs (the only occurrences of "resume" are the doc comment at :155-164).
• Probe evidence for the wire: crates/mind-body/src/self_run/claude-2.1.268-stream-json-probe.jsonl shows a result event with usage, modelUsage, num_turns, session_id, terminal_reason, queued_turn_count, total_cost_usd; and ...-assistant-usage-records.jsonl records cache_creation_input_tokens, cache_read_input_tokens, ephemeral_5m_input_tokens, ephemeral_1h_input_tokens.

A3. launch.rs and heartbeat.rs: what decides when a Mind acts

• launch.rs is "the one way her organs open a run and start its unit" (launch.rs:1-). open_and_launch (:321): reads in-force runs of the request's turn; a live one answers Busy, a dead one is closed Recorded; checks claims, repetition breaker, admits the run, then starts the unit. Units: mind-persona@<instance>.service and mind-self@<instance>.service (:113-125). "A Persona turn's run opens with no claims." START_GRACE_S = 120 (:35). At most one live Self run per instance (ruling one-live-self-run). Nothing in launch.rs knows of sessions.
• heartbeat.rs on main (financial): each Persona holds initiative in dollars of the swarm's run cap T; it regains at rate / sum(shares) * share * urgency per hour, only when idle, capped at T; a turn burns it to T - spend; a full-initiative idle Persona may take a turn; at most k run at once, earliest-to-fill first; a classifier model call rates urgency (heartbeat.rs:1-22, poll :908-..., CLASSIFIER_MAX_COST_MICRO_USD = 20_000 :62). Operator tag/name fills initiative outright. The heartbeat never acks; the Persona turn drains.
• Branch eureka-body/heartbeat-joint-lever (merge-base 21fb9b2, 19 commits ahead of main, 60 files, +2217/-4142): replaces the dollar initiative with a tempo. Header (heartbeat.rs:1-22 on the branch): the Minds share one heartbeat and jointly hold the lever; tempo is tempo::tally of every Mind's newest vote (a Pulse in her own mind; tempo.rs:23, lower median, default beat tempo.rs:13); when a beat falls exactly one Persona takes a turn, chosen by tempo::pick over idle, released Minds by how long each has waited, bent by self-declared urgency, a member addressing her; score (waited / beat) x 10^(LOG_BOUND_ORDERS x urgency / 1000) (tempo.rs:65-68). Two launches happen off the beat: the operator tagging/naming her (once per message) and her own Self run having ended since her last turn. "Nothing is metered here: no meter and no model call." New kind Pulse (schemas/cultnet/epiphany.pipeline.pulse.v2.schema.json). Rulings: shared-heartbeat-joint-lever, self-declared-urgency-etiquette, operator-mention-fills-initiative. Not merged.
• What starts a Self run today: only a Persona turn's start_self_run reply (persona.rs:703-715), claimed as a follow-up (ruling self-run-brief-claimed-follow-up); the heartbeat branch also launches a Persona turn when her Self run ended. There is no path by which a member's message reaches a Self run directly (ruling members-direct-self-runs exists in the mind; not read in this pass).

A4. Bifrost Matrix mouth (Bifrost main tools/persona-matrix-mouth.mjs, 506 lines)

• Ear. One /sync loop per Persona; every message in her configured rooms and her DMs becomes a delivery tuple with seq, roomAlias, roomId, eventId, sender, context, mentions (m.mentions.user_ids) and whether the room is a DM (:2-9, :240-243). First sync's history is context, not mail (:213, :52).
• Position and ack. The /sync next_batch is persisted only when an ack covers it; a restart before the ack redelivers (:7-9, :261-274). Sequence numbers persist across restarts (:257). Unanswered mail is not outrun: at maxPending the sync position stays (:209, :303).
• Delivery to the Mind. Reading wakes nothing; the heartbeat (and the Persona turn) polls with a non-consuming chat_pending_request (:8-9, pendingAfter :277-279, pageOf :356-370, reply capped by limits.replyBytes); the Persona acks what it read (ack :272-275).
• Context. "Matrix is the record": a delivery's context is read from the homeserver per delivery (messages before it, room or thread), at most CONTEXT_LINES = 20 lines, CONTEXT_BYTES = 16 KiB, FETCH_LIMIT = 100 events per fetch; a failed fetch gives empty context and a log line (:13-17, :35-38, :164-204).
• Reply. send({requestId, persona, roomAlias, text}) PUTs m.room.message using the request id as the Matrix transaction id, so a repeat is the same event (:281-296). One CultNet RUDP endpoint on loopback serves all Personas (:372-); the Persona's Matrix token is held only by the mouth (ruling persona-matrix-account-interim).

A5. claude-connector (GameCult/ModelConnector, head c1802d8)

• Two paths. (1) The transport path serves TurnRequests (Persona turns): the connector spawns one claude per execute (tests one_spawn_per_execute, backend/tests.rs:1623), argv in launch.rs:112-137 (-p --output-format stream-json --verbose --input-format stream-json --model ... --system-prompt-file ... --tools "" ..., --json-schema when the request has a schema). (2) The lease path lends the subscription token to a Self run's own process (lease.rs).
• Resume exists in the transport path. ClaudeCodeHandle::Ended { session_id, instance, prefix_sha256 } is returned inside ReasoningState; the tag is an HMAC (connector handle secret) over caller, instructions, model, session, instance and every transcript item before the handle (handle.rs:12-30, Binding :48-58). The next call is planned Plan::Resume (argv --resume <session_id> --fork-session, launch.rs:133-138; "a resume always forks", :107-110) or Plan::Seed (fresh session seeded from the caller's transcript) (handle.rs:137-145).
• Schema turns hand out no handle. "A schema turn leaves the CLI's StructuredOutput tool exchange in its session, and a later turn without the schema runs with no tools: it must not resume that session" (backend.rs:269-272). The handle is minted only when output_schema_json.is_none() (:273-292). Persona turns always send a schema (persona.rs:663), so today no Persona turn can produce or consume a handle. Tools in a request fail before spawn (PlanError::Tools, handle.rs:123-132; test tools_or_final_tool_result_fail_before_spawn backend/tests.rs:1309).
• Child environment is exactly PATH, HOME, CLAUDE_CONFIG_DIR, CLAUDE_CODE_MAX_OUTPUT_TOKENS, CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR (launch.rs:44-53): no CLAUDE_CODE_PROMPT_CACHE_TTL is set, so TTL is the CLI default.
• Lease path and a long-lived process. lease.rs:1-19: the connector is the only token holder and the owner of Self-run admission; a Self run asks over a unix socket (peer uid and systemd unit invocation decide who may ask); the reply is one pipe fd with the token plus plan usage windows. "The lease lasts while the holder keeps the socket open: it ends when the holder closes it, when its unit invocation ends, or when its expiry passes." "The connector spawns nothing here: the Self run's claude stays in the Self run's own unit." The lease request carries expires_at_unix_ms (self_run.rs:507); the connector bounds it with --lease-max-ms (daemon.rs:100-102), which must be >= the unit's RuntimeMaxSec (self_run.rs:510-512, MIND_SELF_RUN_CAP_S). Billing: ruling self-run-lease-billing-and-binding (reserved, billed at true per-model cost on settle, bound to one unit invocation). So a lease supports a long-lived process bounded by the unit invocation and lease_max_ms; the lease protocol itself holds no session notion. Whether a claude can be resumed under a new lease: the CLI side is in Part B1; the connector stores no Self session.

A6. Rules on the table that assume the current split

• eureka-body:cut_spec:cut-persona-memory-write.r1 (InForce, branch eureka-body/persona-memory-write, base c8749c5, depends on heartbeat-joint-lever). Adds memory kind epiphany.pipeline.memory.v2 in her own mind; PersonaReply gains a required remember[] (<= 8; text <= 1000 B, about from batch sender ids + operator ids, salience); organ derives learned_in, direct, sources from the batch; admit_turn_documents replaces admit_pulse (memories + Pulse in one admission, after the says); new recall.rs selects what memory enters each turn (relevant via query_near over memory/follow_up/ruling top 8; about the batch's senders, limit 6; newest 4; cap 16 items / 16 KiB) and render_input gains a "What you remember" section after runs and before messages. Stated premises: "A Persona turn is a tool-less call constrained to one output schema (TurnRequest), so it cannot run a CLI; the reply is the only act a turn has"; forbidden_writers includes "a recall cache across turns"; derived_state: "the recall section is derived per turn and never stored"; negative check: chat.pending|ContextLine zero hits in recall.rs. Operator scenario: DM writes a memory, restart persona unit (context gone), ask in public room, she knows it from memory.
• Persona voice plan. Spec says the voice cut "rewrites render_instructions" (file_changes entry at persona.rs:436); the design is in the persona-memory-and-voice map, not yet written (ruling persona-voice-outside-minds: "how each turn's context carries the Persona strongly enough to hold it is the persona-memory-and-voice map's to design"). Note bfdf4db research note is its prior art.
• Rulings (text read this pass):
  • persona-memory-written-not-transcript (2026-10-31): each turn writes what is relevant to her persistent memory; "cross-room or older transcript in the prompt is the transcript standing in for memory"; room context in a turn is conversation context only (ruling chat-context-replies-see-the-full-exchange still holds, per its text).
  • persona-voice-outside-minds (2026-10-31): Persona voice everywhere but #minds; coordination chatter stays in #minds.
  • room-registers (2026-10-31): #minds clipped coordination only; #swarm Minds and humans, Persona voice; #burn open to all, Persona voice; coordination aimed at #swarm by persona states moves to #minds.
  • persona-unit-token-reach-bounded (2026-10-31): see A1.
  • persona-turns-read-only-tools (2026-10-31, Superseded in part by persona-git-personal-sandbox): the turn "becomes a bounded tool-using loop with an allowlist and per-turn turn and spend caps"; its tools run as her own user.
  • persona-git-personal-sandbox (2026-10-31): each Mind has a persistent personal sandbox directory; whole turn under bubblewrap (bwrap-whole-turn), credentials and state hidden, rest read-only, network kept for huginn and API; pushing and admitting stay in Self runs.
  • persona-reply-typed-by-schema, persona-turn-drains-deliveries, self-run-credential-lease, self-runs-through-connector: titles only read this pass.
• Both new rulings (mind-self-is-a-persistent-session, persona-is-append-only-session) say the refresh/clear decision "follows data, not a fixed rule" and that Persona turns today "rebuild the whole context per call".

---

Part B. Prior art

B1. Claude Code and the CLI (current docs, accessed 2026-10-31)

Session flags [P] https://code.claude.com/docs/en/cli-reference:

• --session-id <uuid>: "Use a specific session ID for the conversation (must be a valid UUID)". --resume/-r <id|name|transcript .jsonl path>; --continue/-c most recent in cwd (skips -p/SDK sessions unless claude -p --continue); --fork-session: "When resuming, create a new session ID instead of reusing the original". --no-session-persistence (print only); --name/-n.
• -p --input-format stream-json --output-format stream-json; --replay-user-messages re-emits stdin user messages for acknowledgment; --include-partial-messages.
• --max-turns: "With --input-format stream-json, a message still queued when the limit ends a turn stays queued and starts a new turn with its own limit".
• --max-budget-usd (print only, client-side estimate; spend can pass the cap; "When you return to a conversation with --continue or --resume, totals [restored from earlier runs]", so a resumed cap counts the whole conversation) [P] cli-reference row, agent-sdk/cost-tracking.
• --system-prompt, --system-prompt-file replace the default prompt; --append-system-prompt[-file] append; --system-prompt-snapshot off rebuilds the prompt every request instead of reusing the one recorded on the conversation's first request; --exclude-dynamic-system-prompt-sections moves per-user context (e.g. auto-memory path) from the system prompt into the first user message "for prompt-cache reuse across users and machines" (ignored with --system-prompt[-file]); --autocompact <auto|tokens> (v2.1.221+).

Long-lived print-mode process [P] https://code.claude.com/docs/en/agent-sdk/streaming-vs-single-mode: streaming input mode "allows the agent to operate as a long lived process that takes in user input, handles interruptions"; "Queued messages: send multiple messages that process sequentially, with ability to interrupt"; "Context persistence: maintain conversation context across multiple turns naturally". The CLI emits one result event per turn; the probe in our repo shows queued_turn_count on it (self_run/claude-2.1.268-stream-json-probe.jsonl). system/init carries a capabilities array (e.g. interrupt_receipt_v1, interrupt_cancel_queued_v1) [P] https://code.claude.com/docs/en/headless. SIGTERM mid-turn leaves the turn unfinished with no result; SIGINT or SDK interrupt() ends it (headless, "Stop a run with SIGTERM"). Our actuator already runs claude as a stream-json process and closes stdin at the first result (A2); the CLI itself does not require that.

Resume [P] https://code.claude.com/docs/en/sessions, .../prompt-caching: sessions are JSONL under ~/.claude/projects/<cwd-encoded>/<id>.jsonl (override CLAUDE_CONFIG_DIR, CLAUDE_CODE_PROJECT_DIR_NAME v2.1.234+), 30-day retention (cleanupPeriodDays); claude -p --resume <id> "prompt" appends to the same session id; --resume searches current project then every other project on the machine (v2.1.223+); resume restores history, model, permission mode (not under -p, which starts in the mode a fresh -p would; bypassPermissions is never restored), not --mcp-config/--settings/--plugin-dir/--add-dir. Resume "sends the whole conversation again, and the request reads from the cache whatever part of its prefix is unchanged and still within the cache lifetime"; by default a resumed conversation keeps the system prompt it started with. "If you resume the same session in two terminals without forking, messages from both interleave into one transcript." A running background session resumed by --resume is attached instead of loaded (v2.1.285+); with --max-turns/--max-budget-usd/output flags the command refuses (exit 1). CLAUDE_CODE_TRANSCRIPT_LOCAL_GC limits a -p session file's growth; CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1 continues an interrupted turn on resume.

Compaction and clear [P] how-claude-code-works, prompt-caching, context-window:

• Auto-compaction: "Claude Code manages context automatically as you approach the limit. It compacts the conversation into a summary." Default window = the model's limit except Sonnet 4.6/Opus 4.6 without extended context at 200K; 1M-native models (Fable, Sonnet 5+, Haiku 5.5, Opus 4.7+) about 967K; settable 100K to 1M via /autocompact, --autocompact, autoCompactWindow, CLAUDE_CODE_AUTO_COMPACT_WINDOW (LIFECYCLE 2b, line 113). If a single large output refills context after each summary, it stops after a few attempts with a "thrashing" error.
• /compact [focus] and "Compact Instructions" in CLAUDE.md steer the summary; compaction "by design" invalidates the conversation layer; system prompt layer can stay cached; the summarization request reuses the warm prefix plus an instruction ("costs a fraction"); after a gap beyond TTL it reprocesses uncached ("/compact costs the most when you resume an old session"); the post-compaction turn writes cache for only the summary.
• Idle compaction (v2.1.290+): on the one-hour TTL, "Claude Code can compact it shortly before the cache expires"; idleCompaction: false turns it off.
• /clear starts an empty context (operator-only command; previous session kept and resumable). In -p mode, /model, /effort, /config key=value, /output-style, /reload-plugins work when typed as the prompt; terminal-only commands do not (headless). Whether /compact and /clear are accepted as a stream-json user message in -p is [N] (not stated on the fetched pages).
• PreCompact hook: [N], not fetched this pass (https://code.claude.com/docs/en/hooks). A SessionEnd hook exists (headless SIGTERM section).

Usage and context fields in the stream [P] prompt-caching, headless, local probe: every assistant message's usage has input_tokens, cache_creation_input_tokens, cache_read_input_tokens (our read_usage sums them into the prefix, A2); result has usage, modelUsage (cumulative per model), total_cost_usd, num_turns, session_id, terminal_reason, queued_turn_count; usage.cache_creation.ephemeral_1h_input_tokens / ephemeral_5m_input_tokens report TTL of writes; /usage shows Prompt cache (main) (hit ratio, misses, warm/cold, likely cause of last miss; v2.1.251+/2.1.260+); the status line exposes a prompt_cache object and current_usage; system/api_retry events exist.

Prompt cache in Claude Code [P] https://code.claude.com/docs/en/prompt-caching:

• Request order is "content that rarely changes first": system prompt (core instructions, tool definitions), then project context (CLAUDE.md, auto memory, unscoped rules), then the conversation. "A change to the system prompt invalidates everything." Plan mode, skills, output-style changes, permission-mode changes, file-change notices and CLAUDE.md edits are appended as conversation messages / ignored until restart, so the prefix stays intact. A file-change notice block is appended mid-conversation and marked for caching.
• Invalidators: model switch (per-model cache), effort level on most models (not Opus 5.5/Sonnet 5.5/Haiku 5.5/Fable 5.1 with key or subscription), fast mode toggle, MCP/tool-definition set change when tools are loaded upfront (deferred tool search keeps the first request's tool list for the whole conversation), compaction, accumulated images (batch removal), Claude Code upgrade.
• TTL: main-conversation bucket, which explicitly includes "non-interactive -p runs, and Agent SDK turns", gets 1 hour only on a Claude subscription within plan usage; 5 minutes with usage credits, API key or cloud provider. "Everything else" (subagents, workflows, forks, compaction, titles) 5 minutes. Controls: CLAUDE_CODE_PROMPT_CACHE_TTL / promptCacheTtl, CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL, ENABLE_PROMPT_CACHING_1H, FORCE_PROMPT_CACHING_5M (v2.1.242+). Verify with claude -p ... --output-format json and usage.cache_creation.
• Cache scope: "effectively scoped to one machine and directory": the system prompt embeds auto-memory paths and the conversation opens with working directory, platform, shell, OS. Parallel sessions in the same directory build matching prefixes and can read each other's cache; sequential sessions share a prefix only if the startup git-status snapshot matches. Fork: "inherits the parent's system prompt, tools, and conversation history exactly, so its first request reads the parent's cache"; a fresh subagent does not.
• How the CLI places breakpoints: the page says only that the cache is organized by that ordering and that it marks the mid-conversation context block "for caching"; the exact breakpoint positions in a resumed or long-lived session are not documented on the fetched pages [N]. The related post https://claude.com/blog/lessons-from-building-claude-code-prompt-caching-is-everything is named by the page and was not fetched.
• A gateway that strips cache_control makes the whole conversation bill uncached every turn (same page); a 400 naming cache_control makes Claude Code move the marker to the last conversation message.

Anthropic API mechanics [P] https://platform.claude.com/docs/en/build-with-claude/prompt-caching (first 100,000 of 165,895 characters read):

• Cache hierarchy tools -> system -> messages; a hit requires an exact match of everything up to and including the block marked cache_control; "Any change at one level invalidates that level and all later levels." The page's invalidation table (✘ = invalidated): tool-definition change invalidates tools, system and messages; web search/citations toggle invalidates system and messages; tool_choice and added/removed images invalidate messages only; thinking configuration and output_config.effort are model-specific for tools/system and invalidate messages. (Read from the fetch summary; the ✓/✘ legend was inferred from the "Any change at one level" sentence.)
• Breakpoints: automatic caching (one top-level cache_control, placed on the last cacheable block and moved forward as the conversation grows) or explicit on blocks, up to 4, automatic uses one slot. Lookback: the system checks the breakpoint and walks back up to 20 blocks for entries earlier requests wrote; writes happen only at breakpoints; a breakpoint on content that changes every request never hits.
• TTL: 5 minutes default, refreshed free on each hit, measured from the start of the request; optional 1 hour ("ttl":"1h"); longer-TTL entries must precede shorter ones. Multipliers on base input: 5-minute write 1.25x, 1-hour write 2x, read 0.1x; exceptions: Fable 5.1 and Mythos 5.1 read 0.025x; Opus 5.5 and Sonnet 5.5 read 0.05x. Minimum cacheable prompt 512 tokens for Opus 5.5, Opus 5, Sonnet 5.5, Fable 5, Mythos 5, Haiku 5.5 (1,024 for Sonnet 5; 4,096 for Opus 4.5/4.6/Haiku 4.5); shorter prompts are processed uncached without error. Usage: input_tokens (after last breakpoint), cache_creation_input_tokens, cache_read_input_tokens; total = sum. Not read this pass: pages beyond character 100,000 (cache storage/sharing section, workspace isolation).
• LIFECYCLE 2a/2b cite the same numbers and the per-use read statement from the earlier pass (lines 91-113).

B2. Claude Agent SDK session model [P] https://code.claude.com/docs/en/agent-sdk/sessions

• A session is the accumulated history written to disk automatically. Options: continue (most recent in cwd), resume (id), fork_session/forkSession (new id with copy of history; "the original stays unchanged"; forking branches history, not the filesystem). Session id is on every result message (session_id); TypeScript also on system/init.
• Multi-turn in one process: Python ClaudeSDKClient (each client.query() continues the same session; connection held), TypeScript streaming input via an async generator or continue: true per call; streaming input mode is "the preferred way" (.../streaming-vs-single-mode). TypeScript V2 createSession() preview removed in 0.3.142.
• Persistence: persistSession: false (TS) or CLAUDE_CODE_SKIP_PROMPT_HISTORY; cross-host resume via sessionStore adapter mirroring transcripts, or moving the .jsonl, or "don't rely on session resume": pass the results into a fresh session's prompt ("often more robust than shipping transcript files around"). Session files are local to the machine; lookup key derives from cwd. Helpers: listSessions, getSessionMessages, getSessionInfo, renameSession, tagSession.
• Limits end with error_max_turns / error_max_budget_usd; resume with a higher limit; a single-shot query() raises after yielding the error result.

B3. Letta / MemGPT

• MemGPT paper [P] https://arxiv.org/abs/2310.08560 (via LIFECYCLE 3a, line 159): "virtual context management", tiered memory like an OS hierarchy, interrupts for control flow. The specific memory-pressure warning and flush percentages are [N] here (not re-fetched; the Letta page https://docs.letta.com/guides/agents/architectures/memgpt returned only navigation).
• Letta [P] https://docs.letta.com/concepts/conversations (fetched): one agent has many conversations; all share the agent's identity and long-term memory (MemFS); each conversation holds its own message history for its thread; /fork branches a conversation; "As it approaches the model's context limit, compaction happens automatically": older messages are summarized and recent ones kept, the full message history remains and the agent can use conversation search to recover earlier context; the summary may omit exact wording or provenance. The page says nothing on concurrent or serialized message handling per agent.
• Letta memory page [P] (via LIFECYCLE 3a): memory is MemFS (git-backed), background "dreaming" subagents run after N completed steps or when the window is compacted; heartbeats removed in letta_v1_agent (2025-10-14). Sleep-time compute [P] https://arxiv.org/abs/2504.13171: ~5x less test-time compute, up to +13%/+18% accuracy, 2.5x lower cost per query amortized.

B4. OpenHands, SWE-agent, Devin, others

• OpenHands [P] https://openhands.dev/blog/openhands-context-condensensation-for-more-efficient-ai-agents (fetched): LLM-based summarizing condenser runs only once context reaches a size; recent exchanges stay intact; older history becomes a summary of goals, progress, remaining work; "because condensation fires only at the threshold, rebuilding the cached prompt cost is spread across multiple turns"; per-turn cost settles at under half of baseline ("up to 2x"); solve rate 54% vs 53% (SWE-bench Verified subset); baseline cost grows quadratically, condensed linearly; the agent sometimes needs an extra turn to condense. Config (LIFECYCLE 3a): max_size / keep_first (docs 120/4, source 240/2, "docs and code disagree").
• JetBrains "The Complexity Trap" [P] https://arxiv.org/abs/2508.21433: observation masking roughly halves cost and matches or beats LLM summarization on SWE-agent/SWE-bench Verified; hybrid cuts a further 7%/11% (LIFECYCLE 3a).
• SWE-agent: only a cache_control history processor (last_n_messages: 2) seen on the config page (LIFECYCLE 3a, thin). Devin [S]: sessions split into focused sessions; Knowledge persists across sessions; /handoff (LIFECYCLE 3a). Cline [S]: Auto Compact at ~80% in-task plus a new_task handoff at a user threshold (example 50%). Aider [P]: --max-chat-history-tokens soft limit then summarization; prompt order system prompt, read-only files, repo map, editable files "for caching"; optional 5-minute keep-warm pings, default off.
• Anthropic engineering [P] (LIFECYCLE 3a): context rot "a performance gradient, not a hard cliff"; compaction for back-and-forth, note-taking for milestones, sub-agents for parallel exploration; harness post: context reset vs compaction chosen per model generation (Sonnet 4.5 needed resets for "context anxiety"; Opus 4.5 largely removed it).

B5. Concurrency: one agent session serving several conversations

• Letta: one agent, many conversations, shared long-term memory, per-conversation history (above); serialization not stated.
• Claude Code in Slack (legacy version, retired for Claude Tag workspaces as of 2026-10-05) [P] https://code.claude.com/docs/en/slack: an @mention creates a new Claude Code cloud session; context is gathered from the thread (or recent channel messages) at mention time; it works in channels, "does not work in direct messages"; progress is posted to the thread; follow-ups continue in the web session. Claude Tag (the replacement) was not read [N].
• Agent SDK streaming input: queued messages "process sequentially, with ability to interrupt" (one session, one queue); --max-turns text says a message still queued when the limit ends a turn stays queued and starts a new turn. Two processes on one session interleave one transcript (sessions); concurrent resume of a running background session attaches rather than forks.
• Our Persona already serializes by construction: next_batch takes one DM room alone or all public rooms together per turn (persona.rs:726-736), at most one live Persona run per instance (launch.rs Busy), and the heartbeat joint-lever branch fires one Persona per beat.
• LIFECYCLE does not cover room/DM multiplexing; the persona-memory-and-voice note (bfdf4db) treats memory, not session multiplexing.

B6. Data-driven compaction / refresh triggers

All from LIFECYCLE (accessed 2026-10-20) unless marked; no source found there applying a formula that combines TTL, rewrite price, idle time and summary size to a compact-or-restart decision (LIFECYCLE 2f, line 142; "ski-rental" only generic theory, line 143).

• Token-fill thresholds in tools: Claude Code auto-compact near the window, 100K-1M settable (above); Anthropic context editing clear_tool_uses trigger 100,000 input tokens (default) with clear_at_least "to make sure clearing is worth breaking the prompt cache"; compaction API trigger 150,000 default, 50,000 minimum (LIFECYCLE 4a); OpenHands max_size; Cline ~80% / new_task ~50% [S]; Aider soft token limit.
• Cache-state triggers: Claude Code idle compaction before a 1 h TTL expires; model-switch confirmation only while the cache is warm; /usage separates "expected rebuilds" (compaction, tool-result clearing) from misses (LIFECYCLE 4a, 2b). Eureka's own self-lifecycle-flush-rehydrate ruling: ceiling ~300k (measured), ski-rental rental rule restarts "once the read cost accumulated above the rehydration size since the last rehydration reaches the cost of one rebuild", at most about twice the hindsight optimum; record prefix size, rehydration size, cache state per run.
• Cost of misses, measured in our fleet (tool-calling-cut.md:28-42 via LIFECYCLE 1d): subagent calls since 09-29: gaps < 60 s 25,232 calls / 56M write tokens; 60-300 s 2,336 / 5M; 300-3600 s 1,241 calls / 292M write (avg 235k); > 1 h 10 / 2.5M; "79% of all subagent cache writes come from the 4% of calls that follow an idle gap of more than 5 minutes". Append-only cost model reads ~ N*70k + 0.9k*N^2; "splitting it in two at the midpoint cuts them by about 40%". Per 10 minutes of waiting, foreground polling costs about 2.2 cache reads (about 0.2 context units) against 1.25 for one rewrite (LIFECYCLE 2f line 139). The operator's note ("after the first turn it's all cached tokens") agrees with the pricing page: read 0.05x on Sonnet 5.5 and Opus 5.5, 0.1x others, write 1.25x (5 min) / 2x (1 h).
• Task-boundary triggers: Eureka rulings: end at "a task or phase boundary", per-model quality ceiling, or the rental rule (self-lifecycle-flush-rehydrate); Anthropic: compaction vs note-taking vs sub-agents by task shape; Devin/Cline: handoff to a fresh session at thresholds. No source found detecting task boundaries from the stream itself (LIFECYCLE 4a, lines 202-203).
• Quality-degradation evidence: Lost in the Middle (arXiv 2307.03172), NoLiMa (2502.05167: 11 of 13 models below 50% of baseline at 32K), LLMs Get Lost in Multi-Turn Conversation (2505.06120: 39% average drop, "when LLMs take a wrong turn ... they get lost and do not recover") (LIFECYCLE 3b). Compaction failure modes [S] tianpan.co/blog/2026-04-19-compaction-traps-long-running-agents: erased failed-tool records -> retry loops, dropped completion records -> redone work, "constraint amnesia".
• Uncertainty carried: page-read limits: the API caching page was read to character 100,000 of 165,895 this pass; LIFECYCLE read 100,000 of 160,171 (2a).

B7. One session or two per Mind (Persona and Self)

Facts only.

• In our Body today they are two different processes/units with different owners of the credential path: Persona turns through the connector transport (mind-persona@, connector spawns claude, no tools, schema), Self through the lease (mind-self@, the unit's own claude) (A1, A5, launch.rs:113-125). Their system prompts differ (Persona: doctrine+persona+campaigns via --system-prompt-file; Self: default prompt, --setting-sources user with the seeded config and the eureka skill, start message names the skill) (persona.rs:655, self_run.rs:165-186, :103-108). They are different models/settings only as configured: not checked.
• In the CLI, a session is one conversation id with one history and one system prompt fixed at its first request (resumed conversations keep the original system prompt, prompt-caching). Two sessions with different system prompts, tools or directories share no cache (cache scoped to machine + directory + model + speed + prefix, prompt-caching "Cache scope"). Same-directory parallel sessions with matching prefixes can read each other's cache. A fork shares the parent's cache on its first request. A subagent (separate system prompt) starts its own cache; its calls append only a call and result to the parent, and it gets the 5-minute TTL bucket even on subscription.
• In the Agent SDK/CLI, one process can serve multiple user messages sequentially in one session (streaming input), and one session can be resumed or forked; there is no documented multi-session multiplexing inside one process on the pages read.
• Cost per fresh session start: the whole prefix (system + project context + first messages) is a cache write at 1.25x (5 min) or 2x (1 h) of base input; later requests read at 0.05x/0.1x; ledger examples: Opus 5.5 base $4/MTok, read $0.20, 5-minute write $5, 1-hour write $8; Sonnet 4.6 base $3, write $3.75/$6, read $0.30 (LIFECYCLE 2a). Unmeasured here: our actual Persona turn cache-read ratio (the connector child sets no TTL variable, launch.rs:44-53; no stats were pulled this pass).
• Letta and Slack examples (B3, B5): one agent identity with several conversations/sessions sharing long-term memory; Slack legacy: one session per request.

---

Not found or not verified in this pass

• Exact CLI breakpoint positions in resumed or stream-json sessions (B1).
• Whether /compact or /clear can be sent as a stream-json user message under -p (B1); PreCompact hook contract (B1).
• MemGPT's numeric pressure/flush thresholds; Letta's per-agent concurrency semantics (B3).
• Behaviour of --session-id <existing id> with an existing transcript (the CLI reference states only "must be a valid UUID").
• Our deployed Persona/Self cache-hit statistics; the actual mind-persona unit file and RuntimeMaxSec; the claude CLI version in production (connector tests pin 2.1.312 at backend/tests.rs:78; the probe files are 2.1.268).
• Text of rulings persona-reply-typed-by-schema, persona-turn-drains-deliveries, members-direct-self-runs, chat-context-replies-see-the-full-exchange, self-run-credential-lease (titles/ids only).
• Claude Tag (Slack replacement) session model.