Context generation and delivery
Context delivery turns stored observations, session summaries, and open work into focused help for agents and tools. It selects memory within the active project scope, builds a compact view of prior work, formats that view for its audience, and delivers it without blocking the current session when memory is unavailable.
Context delivery model
The system serves two related needs. Startup context gives an agent a compact view of recent work and current open work without a new search. Recall tools let the agent ask for focused history when that view is not enough.
Stored context sources
The system combines two stored record types. Observations record work such as a discovery, decision, bug fix, or change. Session summaries describe what a session investigated, learned, completed, and should do next.
Records are scoped to one project or a project chain. A platform source can further limit results to memory created by a specific agent. The active mode supplies the allowed observation types and concepts. User settings can narrow those lists, but they cannot add IDs that the active mode does not define. When reinforcement is enabled, re-confirmed observations can remain useful even when they are older than the newest records.
References: src/…/types.ts• L2-30 src/…/ContextConfigLoader.ts• L33-87 src/…/ObservationCompiler.ts• L79-98
Observation selection
Selection favors recent records and stays within configured observation and session limits. Observation queries apply both the active type and concept filters. They also include records attached to a merged project so a project chain keeps its shared history. Large project chains are split into bounded reads, then deduplicated and combined before the global newest-record limit is applied. An explicit project scope that resolves to no keys returns no records rather than becoming a house-wide feed. The system orders observations and summaries by time, then joins them into one timeline so an agent can follow work across sessions.
Server runtime reads its session-start rows from the shared store because that is where server-mode writes are recorded. The read asks for the newest scoped rows rather than a search result, then separates observations from session summaries before the normal compiler and renderer process them. This keeps server context on the same selection and delivery path as local context without using stale local rows.
The full request changes the goal from a bounded startup view to a broad project view. Normal delivery stays bounded so the packet fits inside an agent prompt. The server route still applies its maximum row limit, including for full, so a broad request cannot create an unbounded read. A project with no records receives an empty or welcome state instead of invented history. A successful empty server response is authoritative; only an unavailable server produces a read failure.
References: src/…/ObservationCompiler.ts• L43-75 src/…/ObservationCompiler.ts• L79-205 src/…/ObservationCompiler.ts• L233-280 src/…/ContextBuilder.ts• L519-619 src/…/ServerContextRows.ts• L30-105 plugin/…/context-generator.cjs• L13-61
Context compilation
Compilation turns selected records into a readable timeline. Each observation exposes an ID, time, type, and title. Only selected observations add fuller detail. Session summaries appear as timeline items, and a newer summary can add a short status block.
The packet can include the last assistant message from an earlier session. This gives the next session a small bridge to prior conversation without copying the full transcript. An observation ID remains the path to full detail later.
References: src/…/ContextBuilder.ts• L135-186 src/…/ObservationCompiler.ts• L310-375 src/…/ObservationCompiler.ts• L378-419 src/…/PreviouslyRenderer.ts• L7-18 src/…/SummaryRenderer.ts• L7-52 plugin/…/context-generator.cjs• L61-75
Work state context
Work state is the agent's durable view of open to-do lists and other ongoing state. When enabled, startup delivery places this project-scoped view before memory so the agent can continue unfinished work without searching the observation history.
Each list is rebuilt from its writes. The latest value for each field wins, closed tasks stay hidden in the normal startup view, and the most recently written lists appear first. Checkout aliases share a list scope, while lists from adopted source projects remain distinct and receive a project label when needed. Shared My Work lists are managed by the My Work view, so they are not copied into this startup section. Owner goals, personal rules, and personal focus lists are also managed by other My Work views. The section has a 3,000-character limit. When it cannot show every open item, it points the agent to the work-state read tool instead of dropping the fact that more items exist.
The section also states the work-state contract: agents use the work-state write tool as the canonical place for ongoing task and state updates. A completed work product can remain linked to its task so downstream work views can find it.
Work state follows the same checkout scope as startup context and can be read or changed through dedicated tools. The feature can be disabled for hosts that manage their own task state; in that case the startup packet does not instruct the agent to use those tools.
References: src/…/WorkStateRenderer.ts• L16-30 src/…/WorkStateRenderer.ts• L31-49 src/…/WorkStateRenderer.ts• L93-168 src/…/SearchRoutes.ts• L488-517 src/…/work-state.ts• L4-13 src/…/work-state-setting.ts• L1-8
Context formats
The same compiled information has two display forms. Agent format uses compact plain text for model input, including compact timestamps that reduce prompt space. Human format adds labels, color, and token information for terminal output. The meaning stays the same while the display support changes.
The timeline renderer groups entries by day and renders observations in either compact rows or selected full-detail blocks. Human output keeps each observation or summary as a complete entry, then restores the day, file, and first-visible time headings when older entries are removed from a terminal preview. This keeps truncation from splitting a title or narrative into a misleading partial record. The preview uses a shared truncation note so the terminal view and settings view explain the same difference between model context and visible text.
The startup header points to a generated RULES-AND-TOOLS.md file. That file holds the timeline reading guide, the active mode legend, and the runtime-specific path for fetching more detail, so the startup packet does not repeat those rules for every session. The file is regenerated from the active mode and current settings when the pointer is rendered. A failed write is logged, but it does not block delivery of the timeline. Local observation references can lead to direct detail reads. Server-rendered references are short display values because the local detail reader cannot use server IDs, so the agent is directed to search by title instead.
The packet can report the tokens needed to read the selected observations and the work represented by them. Read estimates count the text fields once, including facts already held as JSON text, so server and local rows produce comparable savings values. These values show why an index plus targeted recall can cost less than loading every stored detail.
References: src/…/HeaderRenderer.ts• L1-13 src/…/RulesAndToolsFile.ts• L23-73 src/…/TimelineRenderer.ts• L12-72 src/…/TimelineRenderer.ts• L75-161 src/…/PreviouslyRenderer.ts• L7-18 src/…/AgentFormatter.ts• L12-99 src/…/HumanFormatter.ts• L12-101 src/…/TokenCalculator.ts• L6-66 plugin/…/context-generator.cjs• L62-75 src/…/context-preview-note.ts• L1-22
Delivery paths
Context reaches an agent when prior work can change its next action. Session start provides the main packet. Prompt, file-read, context-file, and MCP paths provide focused or repeated access during active work.
Session-start delivery
At session start, the hook obtains a packet scoped to the current project chain and platform. In server runtime it starts the shared server session and reads the newest rows from the shared store. It does not substitute stale local rows when that read fails. In local worker runtime it records the prompt and can add semantic context when that feature is enabled and the prompt is suitable. Local context reads can also use the dedicated context reader worker, while server runtime continues to use the shared-store path.
The startup packet leads with open work state when that feature is enabled. The work-state section is fitted before memory, so the remaining delivery budget determines how much observation context can follow it. The model-facing block is fitted to the host's normal output limit. A human terminal preview uses the same selected records and configuration, then shortens only its presentation so the model still receives the full fitted context.
The hook skips resumed Claude sessions and excluded projects before it queries memory. It also ignores host continuation messages and internal helper prompts so they do not create false user turns. A platform source normally limits startup memory to the current harness, while an explicit setting can include all sources. If the server, worker, cache, or response type cannot provide usable context, the hook returns a safe empty result so the agent session continues.
References: src/…/context.ts• L35-64 src/…/context.ts• L66-187 src/…/context.ts• L189-287 src/…/ContextBuilder.ts• L461-507 src/…/ContextBuilder.ts• L519-695 src/…/ServerContextRows.ts• L30-105 src/…/session-init.ts• L137-167 src/…/session-init.ts• L203-300 src/…/hook-original-cwd.ts• L11-27
Local context generation
The bundled generator provides the bounded startup view from the local memory database. It selects observations and session summaries for the requested project set, includes merged project records, applies an optional platform filter, and uses broad selection for full mode.
It returns model-ready text or a human display. It can also return counts, timeline depth, token use, and estimated savings. The normal path trims the generated packet to its hook budget. Local context generation may run inline or through the context reader worker, but both paths use the same selection and rendering rules. If the database is unavailable or has no records, it returns an empty or welcome result instead of fabricating context.
References: src/…/ContextBuilder.ts• L544-581 src/…/ContextBuilder.ts• L658-703 src/…/ContextBudget.ts• L75-129 plugin/…/context-generator.cjs• L13-80
Context read execution
The context reader is a local read boundary for context generation and related project-scoped reads and searches. A client sends typed requests for rendering, project read keys, work state, observation presence, project resolution, or keyword search across observations, sessions, and user prompts. It then returns either a result or a read error. A timeout error identifies the read method and separates time spent waiting in the queue from time spent running, which helps explain slow or stuck reads.
The worker opens the local database for read-only work and applies the active mode snapshot before it renders context. Search uses a long-lived read-only search service so multi-word lookup can keep its search state without writing to the main database. Search requests stay off the caller's execution path. A bounded request queue and per-read deadline keep a hung reader from leaving callers waiting forever. When a read exceeds its deadline, the client rejects pending reads, retires the reader, reports the timed-out method and wait stages, and limits worker termination time before a later request can create a replacement.
References: src/…/ContextReadProtocol.ts• L7-54 src/…/ContextReadWorkerClient.ts• L7-18 src/…/ContextReadWorkerClient.ts• L30-57 src/…/ContextReadWorkerClient.ts• L75-255 src/…/context-read-worker.ts• L18-87
Prompt and context-file delivery
An active user prompt can request a fresh packet and show it in a context banner. Some agent integrations also write the packet into a managed context file, such as AGENTS.md, so the agent can read current memory through its normal file context.
Managed files preserve user content and replace only the marked memory block. This makes repeated refreshes safe. Session-end processing refreshes supported context files after new memory is available.
References: src/…/user-message.ts• L13-45 src/…/context-injection.ts• L6-43 src/…/processor.ts• L343-384
Native memory assistance
The memory bridge supplements native memory searches and reads with bounded progressive retrieval. It recognizes supported memory tools and memory files, limits the lookup to configured memory roots and the active project, and sends only curated text to the model. Native results remain primary, so a missing worker or invalid lookup does not block the native operation.
The bridge labels retrieved records as data rather than instructions. This keeps stored memory from becoming an untrusted command source while still giving the agent relevant history during a native memory lookup.
References: src/…/memory-search.ts• L99-129 src/…/memory-search.ts• L135-167
File-read assistance
Before an agent reads a large existing file, the file-context path can add a short timeline of earlier observations about that file. It accepts paths from direct file tools and supported shell or MCP read commands. The path compares absolute and project-relative forms so the same file can match either input. It avoids stale help when the file changed after the newest observation.
For Claude Code main sessions, a full-file read of a large supported source file can be denied when fresh history exists and smart outline tools can replace the broad read. The denial directs the agent to current structure, targeted lines, and selected past observations. Small or targeted reads and unsupported cases continue with the timeline as context. Server runtime skips this worker-only file lookup.
References: src/…/codex-file-context.ts• L87-156 src/…/file-context.ts• L251-313 src/…/file-context.ts• L315-427 src/…/file-context.ts• L431-522
MCP recall delivery
MCP provides read-only recall after startup context is loaded. The local server exposes a guided recall path through search, timeline, selected observation details, and raw tool-use details. It also supports project-scoped filters and platform filters when a caller needs a narrower view.
Recall moves from low-cost context to high-cost detail. Search returns an index with IDs. Timeline places a result in nearby work and limits the requested window to a finite depth. Detail recall then supplies only the selected observations. Raw tool input and output is a last resort when summaries do not answer the question. Search can use semantic retrieval when its index is available, then supplement missing categories or fall back to keyword search. Date-ordered searches merge semantic and keyword matches before they sort and page the result. A custom observation type passed through the general type filter is treated as an observation filter rather than an invalid document category.
Timeline lookup can use a semantic match as its anchor and fall back to keyword search when needed. The returned window interleaves observations, session summaries, and user prompts in time order. Direct timeline requests reject windows above the route's fixed maximum, so one recall call cannot scan unbounded history.
The caller's project and team scope stays at the recall boundary. Mutating tools remain outside this read-only recall flow.
See MCP recall and tooling for the tool contract and recall flow. See Context construction pipeline for how context is assembled, Search and memory retrieval for how stored memory is located, and Deep-search execution for broad search execution.
References: plugin/…/mcp-server.cjs• L223-247 src/…/recall-mcp-server.ts• L25-37 src/…/recall-mcp-server.ts• L39-80 src/…/recall-mcp-server.ts• L99-133 src/…/SearchManager.ts• L418-500 src/…/SearchManager.ts• L502-724 src/…/SearchManager.ts• L860-1057 src/…/SearchManager.ts• L1060-1084 src/…/SearchManager.ts• L1248-1324
Delivery safeguards
Context delivery treats memory as optional assistance. It limits payload size, keeps project and platform scope on each query, and adds observer and sync health notices when capture or cloud sync is failing so an empty result is not mistaken for proof that no work exists. In server runtime, the shared-store read has its own row cap and timeout, while the common renderer fits the selected rows to the model output budget.
The normal model block has a 10,000-character host limit. The fitter renders the block repeatedly and removes whole pieces in a fixed order: full observation detail, the latest session summary block, the prior session's final reply, older session entries, and then older observations. This keeps the header and at least one observation intact whenever the remaining content can fit. A health notice is part of the measured block, so it cannot make a fitted response overflow. If nothing removable can make the block fit, the result reports that it remains over budget rather than cutting content in the middle.
When enabled, work state is placed before memory and has a separate 3,000-character section limit. The shared delivery budget then fits the remaining memory around that section. The terminal preview has its own presentation limit and reserves space for the banner added by the hook; it drops complete human timeline entries and restores needed headings rather than cutting through an entry. It can omit display lines without changing the model selection.
Each boundary uses its own fallback. A failed recall call returns an MCP tool error. A failed startup fetch can use a precomputed worker packet or return no blocking hook output. A failed server context read returns no server rows and never replaces them with stale local rows. A successful empty server read remains empty. Native memory reads and searches continue when the memory bridge cannot answer. File-path extraction and file-history lookup are best-effort. The local generator also returns a safe empty or welcome result when its database cannot provide records. A timed-out local read rejects its queued callers and retires the reader so later delivery can use a fresh one.
References: src/…/ContextBudget.ts• L9-129 src/…/ContextBuilder.ts• L304-350 src/…/ContextBuilder.ts• L461-507 src/…/ContextBuilder.ts• L544-581 src/…/ContextBuilder.ts• L610-695 src/…/ContextReadWorkerClient.ts• L142-253 src/…/ServerContextRows.ts• L30-105 src/…/TimelineRenderer.ts• L75-161 src/…/context.ts• L64-187 src/…/memory-search.ts• L135-167 src/…/recall-mcp-server.ts• L148-157
Change checklist
When these files or sections are changed, remember to consider these:
- Keep startup request parameters aligned across the hook handler, worker context endpoint, server session-start renderer, context cache, and local generator. Project chains, platform filters, full mode, last-message mode, and human format must keep the same meaning.
- Keep active-mode observation and concept IDs aligned with context settings. Settings must narrow the active mode and must not leave a mode switch with filters that match nothing.
- Keep project-chain matching aligned between observations and session summaries. Merged records must remain available wherever a project-scoped context packet is expected.
- Keep observation ranking aligned with delivery limits. Reinforcement ranking must not bypass the configured count or change the meaning of a bounded startup packet.
- Keep agent and human output aligned with the timeline model. IDs, summary items, selected details, complete human entries, and empty states must remain clear in both forms.
- Keep delivery fitting and delivery statistics tied to the same surviving records. A limit change must not make telemetry describe queried records instead of delivered records.
- Keep server post-filtering and slot order aligned with local selection. Excluded observation rows must be removed before the observation limit is applied, while summaries remain separate from observation filters.
- Keep the server row cap and category allowances aligned with the route. Observation and summary limits must fit the route cap without allowing
fullmode to create an unbounded read. - Keep server row mapping aligned with the renderer's local shapes. Server IDs must remain usable as display references, observation kinds must remain their real types, and summary rows must remain summaries.
- Keep search strategy and fallback reporting aligned with result behavior. Semantic search, keyword fallback, filter-only search, category supplementation, and custom observation-type filters must preserve project and platform scope.
- Keep date-ordered search union and pagination aligned. Keyword matches must supplement semantic candidates before the final date sort and page boundary are applied.
- Keep the layered MCP recall order intact. Search and timeline must remain cheap filters before full observations or raw tool I/O.
- Keep timeline and deep-search limits aligned with their routes. Timeline windows must stay bounded, and raw tool search must run only when the normal observation search is empty and its filters are representable.
- Keep the Rules + Tools pointer and file content aligned. The pointer must not refer to a missing file, and the file must reflect the active mode, current settings, and runtime's available recall path.
- Keep work-state scope, exclusions, ordering, and the 3,000-character section limit aligned with SessionStart memory.
- Keep managed context-file markers stable. Refresh paths depend on replacing the same marked block without changing user-authored content.
- Keep native memory root checks and project mapping aligned. A memory file must not retrieve history from a different configured project.
- Keep file path extraction and normalization consistent between host tool input, observation storage, and file-context lookup. A mismatch can silently remove file-read assistance.
- Keep recall limits and scope aligned between local and hosted MCP surfaces. A caller must not cross a project boundary or receive an unexpectedly large prompt.
- Keep platform-specific hook output separate from model context. Repeating a timeline in the wrong channel can make a host reject the whole session-start payload.
- Keep runtime selection aligned with the corpus used by write hooks. A server read must not silently return a different history from the active write path.
- Keep the context read protocol, worker dispatch, and client methods in sync. Every render, project read, work-state read, and search operation needs the same input and result contract at each boundary.
- Keep context-reader timeout reporting aligned with request dispatch. Method names and queue-versus-running timings must describe the read that caused retirement, while pending callers must receive the same failure boundary.
- Keep local worker mode snapshots aligned with rendering. The worker must render with the active mode represented by the request rather than its own stale mode state.
- Keep worker queue and failure behavior fail-open for delivery. Pending local reads must reject on worker error, exit, or timeout so startup can use its normal fallback.
- Keep the worker's read-only search lifetime aligned with search behavior. Search state must not turn a context read into a write to the main database or leave prepared search work tied to a closed connection.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| The server or worker cannot answer a session-start request | The agent starts without fresh memory context | The hook uses a valid cached packet when possible or returns a safe empty result. Server runtime never substitutes stale local rows. |
| A successful server read returns no rows | Old local memory can be shown as if it were current | The empty response is authoritative and renders the empty or welcome state. |
| Server rows lose their kind, ID, or summary meaning during conversion | The timeline can flatten observation types or treat a summary as a normal observation | The row source maps server rows to the local renderer shape and preserves the server ID and real kind. |
| A project chain is read as one unbounded project query | Selection can become slow or lose the newest records across merged project keys | The compiler bounds project-key batches, deduplicates rows, and applies the final newest-record limit after combining them. |
| Semantic search is unavailable or returns no usable category | Recall can lose results instead of using stored keyword matches | The search path falls back to keyword retrieval and supplements categories that semantic search leaves empty. |
| Date-ordered search pages semantic results before keyword matches are merged | Recent or old matches outside the semantic prefix can be omitted from the requested page | The search path unions keyword matches with semantic results, deduplicates IDs, sorts by date, and applies the page boundary last. |
| A custom observation type is treated as a document category | A valid observation filter can select no category and return no results | The search boundary maps non-category type values to the observation-type filter. |
| A timeline request asks for excessive before or after depth | One recall request can scan and render an unbounded part of project history | The route rejects depths above its fixed maximum. |
| Raw tool search is requested with unsupported observation filters or existing observation results | The deep tier can return misleading data or duplicate work already answered by observation search | Deep search runs only for a plain, first-page query after the observation tier is empty. |
| Context exceeds the normal hook budget | The host may reject or truncate the session-start payload | The fitter measures the model block at the host limit and removes whole content units in order. |
| A health notice is added after fitting | The warning can push the packet over the output limit | The fitter measures the health notice as part of every model render. |
| A context reader does not reply before its request deadline | The local read can delay context delivery and hide which read is slow | The client reports the timed-out method with queue and run durations, rejects pending reads, retires the reader, and lets a later read open a replacement. |
| A human timeline preview drops lines without preserving entry boundaries or headings | Terminal output can show partial records or lose the day and file context | Human rendering truncates complete entries and restores the required headings and first visible time. |
| A Rules + Tools file write fails | The startup pointer can lack current reading or recall guidance | The write is atomic and errors are logged while timeline delivery continues. |
| A file is newer than its latest stored observation | File-read context may describe old code | The file path compares modification time with the newest observation and skips stale context. |
| A recall request leaves its team or project scope | The caller could see records outside its permitted memory | The recall backend and scoped client enforce caller scope before returning observations. |
| A caller fetches full details before filtering history | A recall response can consume far more context than needed | The MCP workflow places search and timeline before observation details and raw tool I/O. |
| A cache key omits request scope or working directory | One project or display variant can receive another project's packet | Cache reads use the same project, platform, color, and directory inputs as cache writes. |
| A keyword search depends on a worker connection that fails | Search-based recall is unavailable even though startup delivery may still work | The worker reports the read error and the client rejects the affected request without blocking unrelated native behavior. |
Key files
| File | Why to read it |
|---|---|
| src/…/ContextBuilder.ts | Main context flow from selected records to compiled output, budget fitting, human preview truncation, health notices, delivery stats, and the server shared-store boundary. |
| src/…/ContextBudget.ts | Defines the host output limit, terminal reserve, and whole-content reduction order used to fit model context. |
| src/…/ContextConfigLoader.ts | Context limits, display options, and active-mode-safe type and concept filters. |
| src/…/ObservationCompiler.ts | Project and platform selection, merged-project matching, bounded project-chain selection, observation ranking, prior-session bridging, and timeline assembly. |
| src/…/ServerContextRows.ts | Shared-store session-start reads, server row limits, scope filters, post-filtering, empty-read semantics, and conversion to renderer input. |
| src/…/RulesAndToolsFile.ts | Generates the persistent reading guide and runtime-specific recall instructions linked from startup context. |
| src/…/ContextReadProtocol.ts | Typed contract for local context rendering, project-scoped reads, and keyword searches. |
| src/…/ContextReadWorkerClient.ts | Worker lifecycle, typed local read requests, bounded queue, timeout diagnostics, replacement, and failure handling for context and search reads. |
| src/…/context-read-worker.ts | Read-only local database access, active-mode rendering, project reads, and search dispatch. |
| src/…/WorkStateRenderer.ts | Rebuilds open project work state, excludes lists managed by My Work, orders lists, and fits the startup section. |
| src/…/TimelineRenderer.ts | Groups observations and summaries into agent rows or complete human timeline entries that remain readable after preview trimming. |
| src/…/AgentFormatter.ts | Defines the model-facing timeline, prior-session bridge, detail references, summary items, and empty state. |
| src/…/HumanFormatter.ts | Defines the terminal-facing presentation of the same context. |
| src/…/TokenCalculator.ts | Estimates read and work tokens used in context economics and display. |
| src/…/SearchManager.ts | Coordinates scoped semantic, keyword, timeline, and deep search before formatting recall results. |
| plugin/…/context-generator.cjs | Bundled local selection, formatting, empty-state handling, trimming, and context stats. |
| src/…/context.ts | Session-start scope checks, server and worker runtime selection, cache use, platform output, notices, and fallback behavior. |
| src/…/file-context.ts | File-read context selection, freshness checks, read-gate routing, and timeline output. |
| src/…/context-injection.ts | Managed context-file replacement boundary. |
| plugin/…/mcp-server.cjs | Local MCP recall workflow, layered tool routing, and project-scoped search. |
| src/…/recall-mcp-server.ts | Read-only hosted MCP recall contract and its scope and limit boundary. |