Introducing a new way to review your PRs.

Read the announcement

thedotmack / claude-mem

Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More

View on GitHub

47 documents · Updated Nov 20, 2026

docs / transcript-observation-processing

Transcript and observation processing

Transcript processing turns live agent session files into structured capture events. It keeps enough session state to connect messages and tool results, sends useful tool activity to the observer, and stores the observer's observations and session summary as durable memory that later search and context flows can use.

Processing model

The transcript path has two linked stages. A configurable watcher reads new JSONL records or supported compressed transcript frames and maps provider-specific shapes to common session actions. The worker then queues those actions, asks an observation agent to extract durable knowledge, and commits the result to local memory. The active observer feeds one unanswered prompt at a time so a large queue does not fill a model conversation before the provider can answer it.

flowchart LR
    A[Agent transcript JSONL or zstd frames] --> B[Transcript watcher]
    B --> C[Schema match and field mapping]
    C --> D[Session state]
    D --> E[Observation and summary requests]
    E --> F[Worker queue]
    F --> G[Observation agent]
    G --> H[Parsed observations and summary]
    H --> I[Durable memory records]
    I --> J[Search and context delivery]

The same capture boundary supports native hook events. This page focuses on transcript-originated records; hook-specific intake and provider adapters are described in CLI hook event ingestion, the wider lifecycle is described in Capture and memory lifecycle, durable reinforcement is described in Memory ingest and reinforcement, and the native memory path is described in Native memory bridge. Remote worker capture, history and prompt import, media artifact lifecycle, and automatic context clearing cover related capture and context paths.

Transcript watching

The transcript watcher follows configured files as they grow instead of repeatedly reading complete histories. It can watch one file, a directory of JSONL or .jsonl.zstd files, or a glob. It starts a file tailer for each match and watches the surrounding path so new session files become eligible without restarting the process (src/…/watcher.ts• L529-609, src/…/watcher.ts• L863-905).

Watch configuration

Each watch names a source, points to transcript files, and selects a schema. A schema describes how source records identify events and where the common fields come from. The sample Codex configuration maps session metadata, user and assistant turns, tool calls, tool results, command completion, and session completion into the processing actions (transcript-watch.example.json• L2-112).

The loader validates the complete configuration before the watcher starts. It checks the watch list, schema names, event actions, field rules, match rules, path types, context settings, and subagent settings. This turns malformed configuration into a clear load error instead of a run-time failure that could checkpoint past an event (src/…/config.ts• L114-265).

The configuration also supplies session and project fallbacks. A watch may define a workspace or project when the transcript does not. A context option can refresh an AGENTS.md file at session start or end, so an agent can receive current memory without querying the memory service itself (src/…/types.ts• L40-72).

Native hook-backed Codex watches are removed by default because top-level sessions already arrive through hooks. An opt-in subagent mode narrows such a watch to rollout records that native hooks do not capture. A full transcript opt-in keeps the watch unchanged, while the subagent observation skip setting disables that extra capture (src/…/config.ts• L19-38, src/…/config.ts• L40-97).

References: src/…/types.ts• L40-72 src/…/config.ts• L19-38 src/…/config.ts• L40-97 src/…/config.ts• L114-265 transcript-watch.example.json• L2-112

File tailing

The file tailer records a byte offset and reads only data added since the last read. In JSONL mode it keeps an unfinished final line until the next write, which avoids parsing a JSON record while the agent still writes it. If a file is replaced or becomes shorter, the tailer checks the bytes before the checkpoint and resets only when those bytes no longer belong to the saved file (src/…/watcher.ts• L221-223, src/…/watcher.ts• L321-384).

Zstandard transcripts use independent compressed frames. The watcher scans frame headers, decodes complete frames in order, and leaves a torn trailing frame for a later write. A frame can end in the middle of a JSONL record, so the unfinished text and any incomplete UTF-8 bytes travel with the frame checkpoint. A failed turn retries from its line without resending earlier lines from that frame (src/…/watcher.ts• L442-526, src/…/zstd-frames.ts• L20-68).

New watches can start at the current end of a file. A transcript that appears after startup is read from its start when its own timestamp shows that the session began after the watcher, so the opening prompt is not lost. Older or restored history starts at the end instead of replaying old activity (src/…/watcher.ts• L948-983, src/…/watcher.ts• L1092-1103).

The watcher bounds each read pass and yields to the event loop during large backfills. This lets live hook capture and the worker API continue while old transcript data enters the pipeline (src/…/watcher.ts• L51-76, src/…/watcher.ts• L311-319, src/…/watcher.ts• L396-439).

References: src/…/watcher.ts• L223-273 src/…/watcher.ts• L321-384 src/…/watcher.ts• L396-439 src/…/watcher.ts• L442-526 src/…/watcher.ts• L948-983 src/…/watcher.ts• L1092-1103 src/…/zstd-frames.ts• L20-68 src/…/zstd-frames.ts• L146-168

Watch state

Watch state is a durable record of file checkpoints and the context needed to resume a session. It stores offsets plus file identity and a fingerprint of the bytes before each checkpoint. A replacement keeps the checkpoint only when those bytes still match, which avoids both replay after a harmless rename and data loss when a path is reused for a new transcript (src/…/state.ts• L6-16, src/…/watcher.ts• L156-210, src/…/watcher.ts• L985-1015).

The state can also preserve unresolved tool calls, the last working directory, and compressed-frame continuation data. This lets a restart pair a later result with its earlier call even when the call was before the saved offset. Large tool inputs are reduced to the tool name, and state writes use an atomic private file because the saved input can contain secrets (src/…/state.ts• L17-49, src/…/state.ts• L101-145).

Missing or invalid state starts a fresh watch rather than a hard failure. A missing transcript gets a short grace period before its saved tool calls are retired, so a temporary rename does not lose pairing context. A replaced transcript loses the old file's working directory and pending calls (src/…/state.ts• L56-99, src/…/watcher.ts• L727-792).

The state tracks file paths rather than session IDs. Session identity is resolved from each record when possible, or from a UUID in the file path when the source supplies no ID (src/…/watcher.ts• L948-951, src/…/watcher.ts• L1163-1166).

References: src/…/state.ts• L6-49 src/…/state.ts• L51-99 src/…/state.ts• L101-145 src/…/watcher.ts• L156-210 src/…/watcher.ts• L727-792 src/…/watcher.ts• L985-1015

Event normalization

Schema matching turns provider-specific JSON records into a small set of shared actions. A match rule can inspect a nested field and apply equality, set, presence, text, or regular-expression checks. Field rules can read nested values, use watch or session context, and fall back across several candidate paths (src/…/field-utils.ts• L32-98, src/…/field-utils.ts• L116-170).

The processor groups state by watch name and session ID. Context records establish the working directory and project. User and assistant messages update the most recent turn. Tool calls and results are paired by tool ID when the source splits them across records. The processor then turns a completed pair into one observation request. This common state is what lets different transcript formats feed the same worker path (src/…/processor.ts• L15-23, src/…/processor.ts• L104-159, src/…/processor.ts• L184-241).

sequenceDiagram
    participant T as Transcript record
    participant P as Event processor
    participant S as Session state
    participant W as Worker
    T->>P: Match record and resolve fields
    P->>S: Update session, cwd, project, or last turn
    P->>S: Hold tool call until result when needed
    P->>W: Send observation for resolved tool activity
    T->>P: Session end
    P->>W: Queue session summary

A malformed JSONL line is logged and skipped at the watcher boundary. A record that parses but cannot be accepted by the worker is different: the watcher keeps its checkpoint at that record and retries it, so a temporary intake or spool failure does not silently lose the event. The processor also tolerates fields that look like JSON but are not valid JSON and keeps the original text in that case (src/…/watcher.ts• L1125-1161, src/…/processor.ts• L275-287).

References: src/…/field-utils.ts• L32-98 src/…/field-utils.ts• L116-170 src/…/processor.ts• L15-23 src/…/processor.ts• L104-159 src/…/processor.ts• L184-241 src/…/processor.ts• L275-287 src/…/watcher.ts• L1125-1161

Observation capture

An observation is a durable knowledge item derived from a tool action and its result. The processor sends the common session ID, working directory, platform, tool name, input, result, and optional tool-use ID to the worker. The worker resolves the local session, derives the project, removes memory control tags, applies project and tool filters, checks prompt privacy, and places the event on the observation queue (src/…/processor.ts• L243-260, src/…/shared.ts• L45-83, src/…/shared.ts• L86-141).

The bundled session store also keeps a durable index of accepted tool activity. It updates a tool-use record when the same content session reports more information, and it can link that record to the observation created from it. This preserves a useful source trail without making the raw tool log the main memory record (plugin/…/SessionStore.js• L10-86).

The queue separates capture from model work. It can suppress duplicate observation messages and starts the observer when work is available. The HTTP route returns a queued or skipped result, so transcript processing does not need to wait for the observation model to finish (src/…/SessionManager.ts• L161-191, src/…/SessionRoutes.ts• L331-368).

Privacy and project filters are deliberate drop points. A private prompt prevents its observations and summary from entering memory. Excluded projects and configured tools are skipped before model generation. These rules protect the memory boundary while allowing the transcript watcher to remain broadly configured (src/…/shared.ts• L64-112, src/…/SessionRoutes.ts• L379-405).

Captured turns can also carry media from the source event. The worker records whether each event was stored or skipped, then links retained media to the resulting observation when the turn has an observation. If the model did not receive the image, the link remains capture-only and uninspected. A link failure does not remove the memory record (src/…/ResponseProcessor.ts• L391-435, src/…/ResponseProcessor.ts• L504-575, src/…/ResponseProcessor.ts• L1144-1161).

References: src/…/processor.ts• L243-260 src/…/shared.ts• L45-83 src/…/shared.ts• L86-141 src/…/SessionManager.ts• L161-215 src/…/SessionRoutes.ts• L331-405 plugin/…/SessionStore.js• L10-86

Observation generation

The observer converts queued tool activity into compact knowledge fields rather than retaining a raw tool log as the primary memory record. It produces an observation type, title, subtitle, facts, narrative, concepts, and files read or changed. It can also produce a session summary with the request, investigation, learning, completion, next steps, and notes (src/…/parser.ts• L15-39).

The worker sends observation and summary prompts through the active model provider. Observation work uses the queued tool event. Summary work uses the session prompt, the latest assistant message, and the established memory session. Summary generation can use a separate summary model tier when configured (src/…/OpenAICompatibleProvider.ts• L196-248, src/…/OpenAICompatibleProvider.ts• L250-304).

Generation continuity

Observer generation keeps the model conversation separate from durable memory. When the conversation reaches its size limit or the provider refuses a prompt as too long, the worker returns the claimed batch to pending, retires the conversation, and starts a fresh generation with context built from the session's stored observations. It does not trim turns from the old conversation or treat the retired conversation as lost memory (src/…/recycle-conversation.ts• L23-64, src/…/recycle-conversation.ts• L95-144).

The provider also waits for each prompt to finish before it pulls more queued work. If a response stalls, the worker fences late frames, returns the claimed batch to pending, and retries after a delay only a bounded number of times. An answered work turn clears the stall and overflow counts; repeated overflow pauses the observer for a cooldown instead of repeating a request that cannot fit (src/…/response-pacer.ts• L45-128, src/…/ClaudeProvider.ts• L762-842, src/…/ClaudeProvider.ts• L884-909, src/…/SessionRoutes.ts• L535-579).

References: src/…/recycle-conversation.ts• L23-64 src/…/recycle-conversation.ts• L68-144 src/…/response-pacer.ts• L19-128 src/…/ClaudeProvider.ts• L762-842 src/…/ClaudeProvider.ts• L884-909 src/…/SessionRoutes.ts• L535-579

Structured output

The response parser accepts the agent's structured output and rejects empty or unusable blocks. It supports multiple observations in one response and a summary in a separate response. It cleans concepts so later concept matching remains consistent (src/…/parser.ts• L41-85, src/…/parser.ts• L87-186).

Summary storage has a separate progress check. Text in investigated, learned, completed, or notes makes a summary eligible, including a sparse notes-only summary. A response with only a request or future steps is treated as answered but has no progress record to save, so the worker confirms its batch without storing or retrying it. The <skip_summary /> sentinel also confirms the batch without creating a summary (src/…/summary-content.ts• L3-11, src/…/ResponseProcessor.ts• L982-995, src/…/ResponseProcessor.ts• L1013-1035).

If the observer uses non-canonical observation tags, the worker can salvage the parsed rows, replace the reply in the conversation with canonical XML, and remind the next prompt of the schema. Repeated schema drift ends the generation so the next one starts from a clean conversation (src/…/ResponseProcessor.ts• L580-627).

The response path separates provider failure from an answered turn. Quota, authentication, rate-limit, and transport replies return the claimed work to pending. A non-XML answer to queued work receives one fresh retry, while a repeated unusable answer is routed to a fallback when possible or is settled without memory. Complete blocks from a response cut off at the output limit are stored, but the unfinished tail is not treated as complete (src/…/ResponseProcessor.ts• L731-877, src/…/ResponseProcessor.ts• L899-976, src/…/ResponseProcessor.ts• L1010-1023).

References: src/…/parser.ts• L15-39 src/…/parser.ts• L41-85 src/…/parser.ts• L87-186 src/…/OpenAICompatibleProvider.ts• L196-248 src/…/OpenAICompatibleProvider.ts• L250-304 src/…/summary-content.ts• L3-11 src/…/ResponseProcessor.ts• L736-757 src/…/ResponseProcessor.ts• L982-1035 src/…/ResponseProcessor.ts• L580-627

Session identity and state

The capture session is identified by the provider source together with the content session ID used by that provider. This keeps equal external IDs from different agent environments in separate local sessions (src/…/SessionStore.ts• L193-228, src/…/SessionStore.ts• L2379-2438). The memory session is the observer's conversation identity used to associate generated records. The worker creates or finds the capture session from the content session ID, then waits for the provider to establish the memory session before it stores generated results (src/…/shared.ts• L86-101, src/…/SessionManager.ts• L80-121, src/…/ResponseProcessor.ts• L1020-1066).

The durable session record also keeps observed model and billing metadata when that information is available. This gives later session views and sync flows a session-level record of the provider context without changing the identity used to link observations and summaries (plugin/…/SessionStore.js• L738-752, plugin/…/SessionStore.js• L795-805).

This distinction prevents a worker restart from resuming a lost model context by accident. A new in-memory worker session starts without a memory session ID. The provider captures a fresh ID and verifies it in the session store before later observation or summary work can use it (src/…/SessionManager.ts• L88-115, src/…/ClaudeProvider.ts• L303-325).

The transcript processor has a shorter-lived state as well. It holds the current directory, project, latest messages, and unresolved tool calls until the source emits enough information to process them. The watcher persists the directory and unresolved calls needed to restore that state after a restart. The worker adds generation state for the active conversation, including overflow and response-stall debt, so it can distinguish a recoverable restart from a provider that should pause. On session end the transcript processor clears pending tool state, queues the summary, refreshes configured agent context, and removes the session from its active map (src/…/processor.ts• L117-155, src/…/processor.ts• L311-389, src/…/watcher.ts• L727-745, src/…/recycle-conversation.ts• L68-126, src/…/response-pacer.ts• L19-43).

References: src/…/SessionStore.ts• L193-228 src/…/SessionStore.ts• L2379-2438 plugin/…/SessionStore.js• L44-86 plugin/…/SessionStore.js• L295-330 plugin/…/SessionStore.js• L738-752 plugin/…/SessionStore.js• L795-805 src/…/shared.ts• L86-101 src/…/SessionManager.ts• L80-121 src/…/ClaudeProvider.ts• L303-325 src/…/ResponseProcessor.ts• L1020-1066 src/…/processor.ts• L117-155 src/…/processor.ts• L311-389 src/…/watcher.ts• L727-745

Durable memory handoff

The handoff occurs after the observer returns valid structured output and the worker has a verified memory session ID. The response processor removes observations without a storable title, derives file evidence from successful claimed tool calls, adds optional source-line anchors, merges the evidence into observations and summaries, stores the result, and confirms the queued messages before downstream side effects (src/…/ResponseProcessor.ts• L1020-1057, src/…/ResponseProcessor.ts• L1073-1189, src/…/ResponseProcessor.ts• L124-141). When a turn carries media, its event result and observation links are committed with the local memory write. This keeps the source receipt and the memory record aligned even when later sync work fails (src/…/ResponseProcessor.ts• L1144-1161, src/…/ResponseProcessor.ts• L1199-1204).

Observation storage is idempotent within a memory session. A content hash prevents the same observation from creating a second row. Summaries are stored as separate records with the same session and project links. Summary file evidence combines generated summary fields with the files captured from observations, and the store can roll up file evidence from its observations. The local data model keeps the session, observation, summary, and source tool relationships available for later recall (src/…/ResponseProcessor.ts• L1388-1449, src/…/SessionStore.ts• L2621-2705, plugin/…/SessionStore.js• L848-863).

Storage is the completion point for the captured batch. After local storage and message confirmation, the worker sends observations and summaries to vector search when available, notifies cloud sync, and broadcasts updates to the local viewer. It also updates optional project context from the files in the stored observations. Vector, cloud, media-link, or context-update failures do not undo the local memory write. This makes local durability the first completion point and search or remote projection a downstream enhancement (src/…/ResponseProcessor.ts• L1186-1191, src/…/ResponseProcessor.ts• L1480-1614, src/…/ResponseProcessor.ts• L1617-1683).

flowchart TD
    A[Valid observer response] --> B{Memory session ID ready?}
    B -- No --> C[Return claimed work to pending]
    B -- Yes --> D[Store observations and summary]
    D --> E[Confirm queued messages]
    D --> F[Vector search sync]
    D --> G[Cloud sync notification]
    D --> H[Viewer update]
    D --> I[Future context and recall]

References: src/…/ResponseProcessor.ts• L982-1035 src/…/ResponseProcessor.ts• L1045-1057 src/…/ResponseProcessor.ts• L1073-1189 src/…/ResponseProcessor.ts• L1388-1449 src/…/ResponseProcessor.ts• L1480-1579 src/…/ResponseProcessor.ts• L1604-1669 src/…/SessionStore.ts• L2589-2705 plugin/…/SessionStore.js• L848-863 plugin/…/files.js• L10 src/…/schema.ts• L85-117

Context refresh

Transcript processing can refresh agent-facing project context after a session starts or ends. The processor checks for a ready worker, asks for current context, writes it to the configured AGENTS.md path, and limits that path to the project directory or the product data directory. The shipped watcher bounds cold-worker startup and treats this refresh as best effort, so an unavailable worker does not hold up transcript cleanup (src/…/processor.ts• L343-389, plugin/…/transcript-watcher.cjs• L28-37).

The canonical native Codex watch suppresses this transcript-side context update when the same source already has native hook support. Subagent-only capture keeps that suppression while allowing rollout transcripts to be observed, and explicit full ingestion restores the ordinary transcript behavior. This avoids competing context writes while preserving the chosen capture scope (src/…/config.ts• L19-38, src/…/config.ts• L66-97).

References: src/…/processor.ts• L131-133 src/…/processor.ts• L343-389 plugin/…/transcript-watcher.cjs• L28-37 src/…/config.ts• L19-38 src/…/config.ts• L66-97

Change checklist

When these files or sections are changed, remember to consider these:

  • A transcript schema action and its resolved field names must still match the processor's shared action contract. A renamed field can silently drop session IDs, tool pairing, or project context.
  • Configuration validation must accept every event action and field form that the watcher and processor support. A validator that is stricter than the runtime can reject valid provider watches; a validator that is weaker can checkpoint past unusable records.
  • Changes to observation or summary queue payloads must remain aligned across the transcript processor, HTTP validation, ingestObservation, and the worker message buffer.
  • Changes to summary progress fields must preserve the distinction between a valid summary with progress and an answered summary that contains only a request or future steps. The latter must settle without creating memory or retrying the same batch.
  • Changes to capture session lookup must preserve the provider-source and content-session identity pair. Reusing a content ID across providers can mix prompts, observations, or summaries.
  • Changes to memory-session capture must preserve the rule that generated output waits for a verified memory session ID.
  • Changes to observation or summary storage must preserve the local transaction, duplicate handling, source tool links, and the IDs passed to vector search, cloud sync, and viewer broadcasts.
  • Changes to summary file evidence must keep generated file lists compatible with observation file-list rollup and downstream sync consumers. Failed tool calls must not become file evidence.
  • Changes to media event results or observation-media links must preserve the stored, skipped, and capture-only outcomes. Linkage failure must remain non-fatal after the memory rows are durable.
  • Changes to optional line-anchor capture must preserve its opt-in scope and best-effort contract. A source-read or anchor error must not retry or block a stored batch.
  • Changes to watch offsets, file identity checks, checkpoint fingerprints, or startAtEnd must preserve restart behavior and the choice between replaying history and processing only live appends.
  • Changes to compressed transcript handling must preserve frame-boundary checkpoints, partial UTF-8 and JSONL prefixes, torn-frame retry, and line-level retry within a frame.
  • Changes to persisted pending tools or working directories must preserve cross-file tool pairing and must not write unbounded or world-readable tool input into state.
  • Changes to transcript root discovery must preserve the literal-prefix boundary. A missing root should not become a broad watch of an unrelated ancestor.
  • Changes to the canonical Codex watch must be checked against native hook capture, subagent scope, and the duplicate AGENTS.md suppression rule.
  • Changes to bundled watcher startup must preserve the bounded, best-effort context refresh so a cold worker does not delay transcript session cleanup.
  • Changes to session-level observed model or billing metadata must preserve the bundled store's read and write contract for session views and sync consumers.
  • Changes to the durable tool-use index must preserve its content-session and tool-use identity, update behavior, and link to the resulting observation.
  • Changes to provider message feeding must preserve the one-unanswered-prompt gate. Pulling more queued work before a response can make the conversation exceed its budget before any work is stored.
  • Changes to overflow or response-stall recovery must preserve the order of abort, claim release, and restart. A late provider response must not be stored again after its batch returns to pending.
  • Changes to generation restart limits or cooldowns must preserve the distinction between a recoverable conversation restart and a session that needs to wait for a later captured event.

Important failure modes

TriggerConsequenceGuard
Transcript file is written with a partial final JSON lineThe current record cannot be parsed yetKeep the unfinished line and process it after a later append (src/…/watcher.ts• L396-439)
A compressed transcript ends in a torn frameThe latest frame cannot be decoded safelyKeep the checkpoint before the frame and retry after the file grows (src/…/watcher.ts• L442-480, src/…/zstd-frames.ts• L49-60)
Runtime has no Zstandard decoderCompressed transcripts are not watchedSkip them with one clear warning instead of failing the whole watcher (src/…/watcher.ts• L937-945, src/…/zstd-frames.ts• L15-18)
Watch configuration has an invalid shape or unknown actionThe watcher cannot map records safelyReject the configuration before starting and report the field location (src/…/config.ts• L127-265)
Watch state is missing or invalidThe watcher starts with no offsets and may replay file historyUse startAtEnd for live-only watches and keep the state file durable (src/…/state.ts• L56-99, src/…/watcher.ts• L948-983)
A path is reused for a different transcriptOld checkpoints or tool calls can attach to new contentCompare checkpoint bytes and clear the old file context when they differ (src/…/watcher.ts• L985-1015)
A transcript is temporarily renamed awaySaved tool calls can be retired before the file returnsKeep them during the missing-file grace period (src/…/watcher.ts• L756-785)
Two providers reuse the same content session IDRecords can attach to the wrong capture sessionStore and resolve sessions by normalized platform source plus content session ID (src/…/SessionStore.ts• L193-228, plugin/…/SessionStore.js• L816-836)
A tool result has no tool name and no matching pending callNo observation is created for that resultPair by tool ID and drop unresolved results with a diagnostic (src/…/processor.ts• L213-241)
Observer output has no valid observation or summary structureClaimed work is not storedReject invalid output and return queued messages to pending (src/…/parser.ts• L66-84, src/…/ResponseProcessor.ts• L745-757)
Observer returns quota, authentication, rate-limit, or transport failure proseThe provider did not complete the batch, but confirming it would lose captured workClassify the reply before adding it to conversation history and return the batch to pending (src/…/ResponseProcessor.ts• L731-877)
Observer returns non-XML output for queued work twiceThe same batch can loop forever or be dropped without a clear outcomeRetry once in a fresh generation, then use a fallback or settle the batch with a recorded failure (src/…/ResponseProcessor.ts• L899-976)
Observer response reaches the output limit or ends with an open observation blockComplete rows may be useful, but the final observation is incompleteStore complete blocks and log that the unfinished tail was lost (src/…/ResponseProcessor.ts• L1010-1023)
A summary contains only a request or future stepsThe answered batch produces no summary recordCheck for progress text in investigated, learned, completed, or notes, then confirm without storage (src/…/summary-content.ts• L3-11, src/…/ResponseProcessor.ts• L982-995)
A successful tool call uses an unsupported input shapeFile evidence is incomplete even when the observation is storedKeep adapter tool names and accepted path forms aligned with evidence extraction (src/…/ResponseProcessor.ts• L58-104, src/…/ResponseProcessor.ts• L178-237)
A denied, failed, or timed-out tool call includes pathsA failed action could be recorded as a read or editIgnore file paths when the tool response marks an error (src/…/ResponseProcessor.ts• L64-79, src/…/ResponseProcessor.ts• L107-114)
An observer output contains an observation without a storable titleThe row is dropped and later output can misalign with stored IDsFilter untitled observations before storage (src/…/ResponseProcessor.ts• L1073-1109)
Provider memory session ID is not availableGenerated observations and summaries cannot be linked safelyDefer storage until the ID is captured and verified (src/…/ResponseProcessor.ts• L1020-1035)
Project or prompt privacy policy excludes the eventThe capture is skipped and no memory record is queuedApply project, tool, and privacy checks before queueing (src/…/shared.ts• L64-112)
Vector or cloud sync fails after local storageSearch or remote copies can lag while local memory remains availableStore locally first and handle downstream sync as non-blocking work (src/…/ResponseProcessor.ts• L1519-1547, src/…/ResponseProcessor.ts• L1622-1647)
Observation-media linkage fails after a captured turn is storedThe memory row remains durable, but media may remain only at event level and uninspectedUse a savepoint for links and keep the observation and event result in the outer transaction (src/…/ResponseProcessor.ts• L497-575, src/…/ResponseProcessor.ts• L1144-1161)
Summary file evidence is absent from both the summary and its observationsLater session views lose the file trailMerge claimed-message evidence into the summary and keep observation file-list rollup aligned (src/…/ResponseProcessor.ts• L1045-1057, src/…/ResponseProcessor.ts• L1413-1449, plugin/…/SessionStore.js• L848-863)
Bundled tool-use storage receives a missing identity fieldThe source tool record is not retained or cannot be linkedRequire content session, tool-use, and tool name values before upsert (plugin/…/SessionStore.js• L10-57)
Bundled session storage cannot read or retain observed session metadataSession views or sync payloads can lose model and billing contextKeep the observed metadata columns and session read/write paths aligned (plugin/…/SessionStore.js• L738-752, plugin/…/SessionStore.js• L795-805)
Provider pulls more than one unanswered prompt into a generationA backlog can exceed the conversation budget before the observer answers and make the same batch loop without progressGate the next pull on the prior turn and release only after a completed turn (src/…/response-pacer.ts• L52-128, src/…/ClaudeProvider.ts• L775-842)
Observer conversation reaches its limit or the provider refuses it as too longThe current generation cannot accept more workReturn claims to pending, drop the conversation, and seed a fresh generation from stored observations (src/…/recycle-conversation.ts• L95-144)
Response stream stalls after a prompt is claimedThe batch can remain pending without another captured event, or a late answer can duplicate storageFence late frames, abort before releasing claims, and use bounded delayed resumes (src/…/response-pacer.ts• L79-128, src/…/ClaudeProvider.ts• L884-909, src/…/SessionRoutes.ts• L555-579)
Consecutive overflow recycles never produce a fitting generationEach new captured event can spawn and abort another unusable observerPause the observer after the recycle limit and clear the gate only after its cooldown (src/…/recycle-conversation.ts• L68-126, src/…/SessionRoutes.ts• L162-182)

Key files

FileWhy to read it
src/…/config.tsDefines watch validation, path handling, and native Codex capture scope.
src/…/watcher.tsShows file discovery, JSONL and compressed-frame tailing, checkpoint handling, and live watch behavior.
src/…/state.tsDefines the durable resume state for offsets, file identity, pending tools, working directories, and compressed-frame continuation.
src/…/zstd-frames.tsExplains how compressed session frames are found and decoded without reading a whole history.
plugin/…/transcript-watcher.cjsShows the shipped watcher bundle and its bounded, best-effort context refresh behavior.
src/…/processor.tsShows how normalized transcript events become session actions, observations, summaries, and context updates.
src/…/field-utils.tsDefines the schema matching and field lookup model used to adapt transcript formats.
transcript-watch.example.jsonGives the clearest end-to-end example of a provider transcript schema and watch.
src/…/shared.tsDefines the observation intake boundary and its privacy and project checks.
src/…/SessionManager.tsShows how observation and summary work enters the worker queue.
src/…/response-pacer.tsDefines the gate that limits the observer to one unanswered prompt and fences stalled responses.
src/…/recycle-conversation.tsDefines conversation retirement, memory-based restart context, overflow limits, and cooldown behavior.
src/…/ResponseProcessor.tsShows response recovery, summary eligibility, file and media evidence, local storage, confirmation, and downstream publication.
src/…/summary-content.tsDefines which summary fields count as progress for storage.
src/…/parser.tsDefines the durable observation and summary shapes produced by the observer.
src/…/SessionStore.tsShows how sessions, observations, summaries, and tool-use links become durable local records.
plugin/…/SessionStore.jsShows the shipped SQLite session store, provider-scoped session identity, durable tool-use index, summary file evidence, and session-level observed metadata used by bundled runtime code.
src/…/files.tsDefines compatibility for JSON file lists and older single-path evidence.
plugin/…/files.jsShows the shipped file-list parser used by bundled storage code.
src/…/transcript-parser.tsShows the separate backward scan used when a caller needs the latest user or assistant text from JSONL.