Capture and memory lifecycle
The capture and memory lifecycle turns coding-agent activity into project-scoped memory that engineers can search and receive in later work. It accepts hook events, transcript activity, direct memory notes, and related media. It keeps the host session responsive while local or remote workers normalize, retain, and index accepted data.
Capture paths
The system accepts activity through host hooks and transcript processing. Each host is mapped to one shared input shape before project, session, privacy, and activity rules run.
CLI hook capture
The CLI hook path handles events that a coding environment sends directly. Platform adapters preserve the host's session, project, prompt, tool, result, transcript, and agent identity in a common contract. The adapter set includes Gemini and Codex and keeps host-specific MCP names, shell actions, failed tool results, and transcript paths distinct enough for later filtering and recall.
Codex requires a valid session and working directory. Its adapter accepts only known hook events and can add the files affected by a pre-tool action to the shared tool input. It also preserves bounded agent identity and session-source data so context recovery and subagent activity remain tied to the right thread.
Cursor can recover a transcript from its workspace and conversation identity when the host does not send a path. Gemini requires a valid session and maps its tool names into the shared vocabulary. Windsurf keeps the MCP server in the tool identity so the system can block its own memory calls without blocking unrelated tools.
The hook boundary is non-blocking. A durable local spool or a bounded live handoff lets the host continue while the worker receives the event. Invalid input, missing dependencies, and unexpected capture errors return a host-valid no-op instead of blocking the agent. Claude Code can also restore the tail of a large persisted Bash result, so the observer receives final errors or summaries without exceeding the existing field bound. See CLI hook event ingestion.
Explicit memory writes use the direct memory path rather than becoming a second ordinary tool observation. File edits use the observation path and therefore remain part of the same searchable activity history.
References: src/…/hook-command.ts• L73-95 src/…/hook-command.ts• L97-199 src/…/index.ts• L12-26 src/…/claude-code.ts• L67-111 src/…/claude-code-persisted-output.ts• L8-67 src/…/codex.ts• L68-115 src/…/cursor.ts• L23-74 src/…/gemini.ts• L5-61 src/…/windsurf.ts• L4-79
Transcript capture
The transcript path reads local JSONL records for environments that do not expose every event through hooks. A watcher sends new records to a processor, which maps them to session starts, prompts, tool activity, file edits, observations, summaries, and closeout events. See Transcript observation processing.
The hook and transcript paths converge before retention. Both use the same project and session boundaries, so an event source changes the way activity is found but not the memory model.
References: src/…/watcher.ts• L14-83 src/…/processor.ts• L40-102 src/…/processor.ts• L243-272
Media retention
Media attachments extend an accepted observation with stable references to related images. Capture accepts bounded inline data or a trusted project file. Private-tagged media is removed from the capture path before its pixels are read, stored, uploaded, or sent to the observer.
The local store keeps converted viewer and model copies. It identifies replayed input from its event and source identity, publishes both copies as one ready asset, and checks their size and checksum when read. A failed or abandoned conversion becomes a retryable cleanup state. A second device can hold an unresolved replica until verified converted bytes arrive. Cloud upload and second-device resolution run beside text retention, so an image outage leaves the text observation searchable. See Media artifact lifecycle.
References: src/…/capture.ts• L198-237 src/…/capture.ts• L239-332 src/…/converter.ts• L198-303 src/…/store.ts• L29-45 src/…/store.ts• L62-124 src/…/store.ts• L138-219 src/…/store.ts• L222-267 src/…/cloud.ts• L285-341
Observation acceptance
An observation is a project-scoped record of useful agent activity. Capture does not guarantee retention. The system first checks that the event belongs to a tracked project and that its source, tool, content, and agent state are allowed.
The acceptance boundary applies the same safeguards to server and local routes:
- Missing tool data is ignored.
- Recursive memory tools do not create new observations.
- Excluded projects and configured tools are skipped.
- Configured subagent activity can be skipped before worker, server, or provider work.
- Explicit memory writes stay separate from ordinary observation generation.
- Large media fields are bounded before dispatch.
Accepted activity uses the selected runtime. The server records an event directly. A local route writes a durable spool entry before it nudges the worker. A recoverable server failure can use the worker route for eligible events. A non-recoverable failure stays non-blocking but does not claim that the event was saved. See Remote worker capture.
The hook command also keeps the host contract valid when capture is disabled or input is rejected. It emits the platform's no-op response and exits without denying the tool, changing its arguments, or turning a capture fault into a blocked session.
References: src/…/observation.ts• L30-49 src/…/observation.ts• L52-100 src/…/observation.ts• L103-149 src/…/hook-command.ts• L109-134 src/…/hook-command.ts• L146-199 src/…/spool-hook-event.ts• L23-82
Session and turn boundaries
Session identity links prompts, tool activity, summaries, media, and project scope. Platform source remains part of that identity so similar external session IDs from different environments do not mix.
Prompt capture is anchored at the host's user-submit event. A submitted prompt takes precedence over fields that can also carry tool results. An explicit empty submitted prompt means that the event is not a user turn. A missing field follows host-specific rules. Continuation and internal protocol events are rejected so helper work does not become a false prompt. See CLI hook event ingestion.
At prompt start, the selected runtime creates or initializes the project session. For a sufficiently long prompt, it can add bounded semantic context from related observations. A failed context lookup does not block the prompt. Hosts without a dedicated prompt event can use a pre-invocation event for the first prompt and later calls for file context.
Summary handling closes a turn with the last assistant message and session metadata. It can also capture opted-in advisor calls and project deliverables. Deliverables are person-facing files declared by the agent or inferred from safe writes outside the source tree. Local capture copies safe files into the project bucket and spools their records. See Media artifact lifecycle for media files and Historical session and owner-prompt import for older activity.
Session-end and subagent-stop are separate local closeout signals. They ignore missing or untracked identities, then spool completion without waiting for the worker. Fresh and forked subagents receive different context treatment so a fork does not receive a duplicate timeline.
References: src/…/claude-code.ts• L56-108 src/…/antigravity-cli.ts• L128-181 src/…/session-init.ts• L139-225 src/…/session-init.ts• L234-340 src/…/summarize.ts• L107-180 src/…/summarize.ts• L185-270 src/…/deliverables-capture.ts• L23-46 src/…/deliverables-capture.ts• L249-338 src/…/index.ts• L141-178
Compaction recovery
Compaction recovery restores memory context after a host replaces a thread's history. A compaction hook marks the thread. The next context-capable event supplies the timeline once, while the event's observation is recorded first.
This diagram illustrates how compaction marks a thread and how the next eligible event restores its memory timeline.
flowchart LR
A[Thread compaction] --> B[Mark context pending]
B --> C{Next eligible event}
C -->|Root start| D[Context handler]
C -->|Subagent tool event| D
C -->|Fresh subagent start| D
D --> E[Return timeline once]
Kimi clears its one-shot marker only at compaction. Codex uses a post-compaction marker because subagent threads do not receive the root start event. The context handler clears the Codex marker when it returns the re-injected timeline. See Automatic context clearing.
References: src/…/index.ts• L105-137 src/…/codex-compaction-gate.ts• L1-38 src/…/codex.ts• L5-22 src/…/context.ts• L311-333 src/…/context.ts• L445-451 src/…/summarize.ts• L138-145 src/…/subagent-context.ts• L49-63
Memory retention
Accepted activity becomes durable memory after processing. The local worker keeps a short-lived handoff before an observer turns raw activity into structured observations and summaries. Direct memory writes use the same project-scoped store without an LLM call. See Direct memory ingestion and reinforcement.
The same direct path can import already distilled local memory. Supported markdown memory files become observations without another model pass. The import stays inside the allowed Claude Code project tree, skips the link-only MEMORY.md index, and uses content deduplication so repeated runs do not create duplicate knowledge. It ignores symlinked notes and oversized files. It reads sibling transcript records until it can resolve the original checkout, even when a record is larger than one read chunk. It uses a best-effort project key when no sibling transcript resolves the original checkout. The CLI can scan one memory directory or all project directories with a no-write dry run before storage. See Historical session and owner-prompt import.
The retained record keeps project, session, source, searchable text, and related media references. A spool entry or worker handoff is not searchable memory. Searchable memory exists only after the retention path stores the observation and updates its search index.
References: src/…/file-watcher.ts• L17-22 src/…/file-watcher.ts• L49-89 src/…/cli.ts• L23-102 src/…/ingest.ts• L17-23 src/…/ingest.ts• L296-345 src/…/ingest.ts• L364-420 src/…/ingest.ts• L421-484 src/…/ingest.ts• L517-583 src/…/ingest.ts• L624-753 src/…/save-memory.ts• L9-23 src/…/save-memory.ts• L25-76
Project-local activity views
Retained observations can become a bounded generated activity section in project CLAUDE.md files. The view groups recent observations by day and related file, replaces only its tagged block, and leaves authored content intact. Cleanup removes generated blocks without removing unrelated content.
References: src/…/claude-md-commands.ts• L203-233 src/…/claude-md-commands.ts• L255-332 src/…/claude-md-commands.ts• L430-465 src/…/claude-md-commands.ts• L500-584
Search and context delivery
Search turns retained memory into context for later coding work. Session-start handlers request a bounded project context and return it through the host's model context channel. The selected runtime, cache, and worker fallback determine where the read comes from.
The context request normally uses the current checkout. A local worker can include other tracked projects when configured. Platform-source filtering keeps context separate by host unless a setting requests all sources. Excluded projects are suppressed on the read path as well as the write path. Output limits keep memory, notices, and team information inside the host's delivery budget. A worker outage can use an eligible cache; a server read failure does not substitute stale local rows.
The server runtime reads the shared server directly, while the worker runtime can use a precomputed local context cache or a live worker request. This keeps reads aligned with the runtime that accepted writes. Codex receives the timeline through its model-context field rather than a duplicate terminal message, which protects the host hook output limit.
File reads can receive a compact history of prior observations. The file path is checked in absolute, project-relative, and home-relative forms. A durable local gate injects a file timeline once per session and file, then allows it again after a newer observation. Large parseable whole-file reads can be directed to structural or targeted reads, while uncertain checks fail open. Native memory search takes precedence over file history and returns bounded observation IDs rather than full records. See Native memory bridge.
User-message delivery can show the current context as a host-visible banner. Claude Code can place the repeated timeline portion in a session-start card while keeping notices and the closing link in the hook message, which avoids repeated hook labels in mirrored views. Kimi combines session initialization with context delivery because its host does not append SessionStart output. Antigravity uses pre-invocation inspection to choose prompt capture or file context. The context handler fits notices, team briefs, and memory into the host field limit without cutting a rendered timeline entry. See Automatic context clearing.
References: src/…/context.ts• L242-270 src/…/context.ts• L311-345 src/…/context.ts• L445-529 src/…/context.ts• L547-585 src/…/context.ts• L608-672 src/…/file-context.ts• L372-487 src/…/file-context.ts• L511-638 src/…/memory-search.ts• L138-183 src/…/user-message.ts• L16-59 src/…/index.ts• L38-101
Change checklist
When these files or sections are changed, remember to consider these:
- Keep every platform adapter aligned with the normalized hook contract. New host fields must still preserve project, session, prompt, tool, result, and media identity.
- Keep Codex event names, session validation, file-path extraction, and output formatting aligned with the host hook contract.
- Keep host tool identities and MCP server identities aligned with recursive-memory filtering. A new host spelling must not turn a memory lookup into a stored observation.
- Keep failed tool responses distinct from absent and empty submitted prompts. These states affect both failure records and turn anchoring.
- Keep server, worker, live handoff, and durable spool routing aligned. A failed route must not claim persistence.
- Keep Claude Code's persisted-output recovery inside its trusted project results path and within the observer field budget. A read failure must preserve the original bounded result.
- Keep project, source, privacy, recursive-memory, and subagent filters ahead of every observation and media entry point.
- Keep media replay identity, source checks, variant checksums, and cleanup states aligned. A replay must reuse an attachment, while changed bytes at the same path must not reuse old media.
- Keep private media out of local storage, cloud upload, and observer requests.
- Keep session and platform identity consistent across observations, summaries, direct writes, media, subagents, deliverables, and context reads.
- Keep watched memory files inside configured roots and preserve their project mapping. A changed file must create a new searchable revision.
- Keep imported memory limits, index exclusion, symlink handling, and content deduplication aligned with the direct observation store.
- Keep direct-memory replay deduplication scoped by both project and normalized platform source. A note from one coding environment must not suppress the same note from another environment.
- Keep generated CLAUDE.md blocks bounded and tagged. Folder matching must not overwrite authored content.
- Keep native memory lookup ahead of file history. A native result must not cause a second context response.
- Keep compaction markers one-time and attached to the hook that can return context. Recovery must not block the observation that triggers it.
- Keep fresh and forked subagent behavior distinct. A fork must not receive duplicate context.
- Keep context output within host limits. An empty or failed read must not consume a one-shot injection marker.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A host sends an invalid project path or session identity | Activity cannot be linked to project memory. | Adapters validate identity and path before normalization completes. |
| A host omits a required session or sends an unsafe transcript identity | The hook cannot safely find or group activity. | The adapter rejects the input or derives only a validated local transcript path. |
| A failed tool event has no normal result | The stored activity can lose its failure or interruption state. | Adapters convert host failure fields to the shared result shape. |
| A follow-up model call is treated as a new prompt | Memory gains false user turns and later observations shift. | Adapters preserve submitted-prompt presence and host turn signals. |
| A memory MCP call uses a host-specific tool spelling | The system can record its own search as new activity. | Adapters normalize known MCP server names before the recursion gate. |
| A project or tool is excluded | Activity is not retained or returned as context. | Shared filters run before worker, server, provider, or context work. |
| A server or worker route fails | The host continues, but the event may not be saved. | Hooks return a no-op and only claim persistence after an accepted handoff. |
| A remote spool upload lacks a token or exact receipt | Events remain local and are retried later. | The outbox is kept until the remote worker accepts the matching receipt. |
| A memory file is outside its configured root or changes during a read | Unsafe or partial text is not imported. | The watcher checks location, file identity, size, and content stability. |
| An imported memory file is symlinked, oversized, empty, or has no usable project match | The note is skipped or may be assigned to a best-effort project key. | Ingest stays inside the projects root, refuses symlinks and large files, skips empty bodies, and reports unresolved project mapping. |
| A direct memory write is replayed after checkpoint loss | The same note could be stored twice. | A project-scoped source fingerprint is checked under the write lock. |
| A direct memory note is replayed from a different coding environment | A valid note can be incorrectly treated as an existing replay. | Replay fingerprints are matched by project and normalized platform source. |
| Claude Code stores only the head of a large Bash result in the hook payload | The observer can miss the final error or test summary. | The adapter reads the trusted persisted result and restores its tail within the existing bound. |
| An image is private, invalid, too large, or unavailable | Text memory remains searchable without the image. | Capture records a bounded media status and isolates media failure from observation storage. |
| A media conversion stops or its files fail checksum validation | The attachment stays unavailable and temporary files can remain. | Conversion leases, atomic publication, checksums, and bounded cleanup reconcile the asset. |
| Cloud media upload or replica download fails | The image remains pending while local text and references remain usable. | Durable media queues retry transient failures with backoff and verify checksums. |
| Codex compaction replaces thread history | The prior timeline disappears from the thread. | A pending marker causes one re-injection on the next eligible event. |
| File history is stale, unavailable, or slow | No timeline is added, but the host read continues. | The lookup uses a short budget and fails open. |
| A full-file read cannot use smart tools | The host could be blocked without a usable replacement. | Unsupported files, uncertain checks, and unavailable parsers allow the read. |
| Context plus notices exceed a host field limit | The host can discard the whole context response. | The handler reserves space and omits or fits whole rendered sections before delivery. |
Key files
| File | Why to read it |
|---|---|
| src/…/hook-command.ts | Shows the shared hook boundary, output contract, and graceful failure behavior. |
| src/…/hook-entry.ts | Shows the lightweight hook process used for frequent events. |
| src/…/run-hook-subcommand.ts | Shows the common hook subcommand used by hook and worker entry points. |
| src/…/types.ts | Defines the normalized input and host output contracts. |
| src/…/index.ts | Shows how supported coding environments select a shared adapter. |
| src/…/codex.ts | Shows Codex event validation, file-context normalization, session identity, and output formatting. |
| src/…/gemini.ts | Shows Gemini session, tool, MCP, and output normalization. |
| src/…/cursor.ts | Shows Cursor transcript recovery and failed tool response mapping. |
| src/…/windsurf.ts | Shows Windsurf action and MCP identity mapping. |
| src/…/claude-code.ts | Shows how common Claude-compatible payloads become shared hook input. |
| src/…/claude-code-persisted-output.ts | Shows how large Claude Code tool results retain their final lines without expanding the hook field. |
| src/…/antigravity-cli.ts | Shows how a host without a prompt-submit hook separates turns and file context. |
| src/…/observation.ts | Shows the shared acceptance boundary and event routing. |
| src/…/session-init.ts | Shows prompt anchoring, session start, and prompt-time context. |
| src/…/summarize.ts | Shows turn closeout, advisor capture, deliverables, and summary routing. |
| src/…/deliverables-capture.ts | Shows how safe person-facing files become project deliverables. |
| src/…/spool-hook-event.ts | Shows durable handoff, live delivery, worker nudging, and remote upload. |
| src/…/context.ts | Shows how retained memory becomes bounded host context across worker and server runtimes. |
| src/…/file-context.ts | Shows file-history lookup, read gating, and context delivery. |
| src/…/memory-search.ts | Shows native memory search supplementation. |
| src/…/cli.ts | Shows single-source, all-project, and dry-run entry points for native memory import. |
| src/…/save-memory.ts | Shows direct memory persistence and replay deduplication. |
| src/…/file-watcher.ts | Shows configured local markdown memory import. |
| src/…/ingest.ts | Shows safe scanning and mechanical import of already distilled memory files. |
| src/…/capture.ts | Shows the boundary between observations and retained media. |
| src/…/store.ts | Shows media states, replay identity, variants, replica resolution, and cleanup. |
| src/…/inference.ts | Shows bounded image delivery to the observer. |
| src/…/cloud.ts | Shows optional cloud upload, replica resolution, and retry behavior. |
| src/…/converter.ts | Shows the conversion contract for viewer and model variants. |