Real-time Timeline Events (SSE)

Relevant source files

The following files were used as context for generating this wiki page:

• src/services/worker/SSEBroadcaster.ts
• src/services/worker/events/SessionEventBroadcaster.ts
• src/services/worker-service.ts
• src/services/worker/SDKAgent.ts
• src/services/worker/README.md

The Real-time Timeline Events system in Claude-Mem utilizes Server-Sent Events (SSE) to provide an asynchronous, unidirectional stream of updates from the Worker Service to client interfaces, such as the Web Viewer UI. This mechanism ensures that as the AI agent processes tool usage, generates observations, or completes session summaries, the visual representation of the project timeline is updated instantly without requiring client-side polling.

The architecture relies on a centralized broadcaster within the worker service that manages client connections and pushes event payloads whenever specific lifecycle events or data mutations occur. Sources: src/services/worker/README.md, src/services/worker-service.ts:246-265

Architectural Overview

The SSE implementation is structured around a decoupled event-driven pattern. Data-producing components (like the SDKAgent) perform their primary tasks and then delegate the notification responsibility to a broadcaster service.

Components and Responsibilities

Component	Responsibility
Worker Service	Hosts the /stream endpoint and manages the lifecycle of the SSEBroadcaster instance.
SSEBroadcaster	Maintains the set of active HTTP response objects (clients) and provides methods to push JSON-formatted events.
SessionEventBroadcaster	A high-level wrapper that orchestrates specific session-related broadcasts like processing status and queue depth.
SDKAgent	The primary event producer; it triggers broadcasts after successfully saving new observations or summaries.

Sources: src/services/worker/README.md, src/services/worker-service.ts:258-271, src/services/worker/SDKAgent.ts:275-285

Data Flow Diagram

The following diagram illustrates how an observation generated by the SDK Agent flows through the system to reach connected UI clients via SSE.

The flow ensures that data persistence in SQLite happens before the real-time notification is sent. Sources: src/services/worker/SDKAgent.ts:243-290, src/services/worker-service.ts:1016-1033

Event Types and Payloads

The system broadcasts specific event types categorized by the nature of the update. Each event is sent as a JSON string prefixed with the SSE data: identifier.

Data Mutation Events

These events occur when the SDKAgent completes the processing of an AI response.

• new_observation: Broadcast when a tool use observation is persisted. The payload includes the observation ID, session metadata, type, title, and the narrative content. Sources: src/services/worker/SDKAgent.ts:275-299
• new_summary: Broadcast when a session progress summary is generated. It includes the investigated topics, learned facts, and next steps. Sources: src/services/worker/SDKAgent.ts:333-352

Status and Metadata Events

These events manage UI state and system responsiveness indicators.

• processing_status: Broadcast by the WorkerService whenever the queue depth or active processing state changes. This is used by the UI to show or hide loading spinners. Sources: src/services/worker-service.ts:1016-1033
• session_deleted: Triggered when a session is removed, allowing the UI to prune its local state. Sources: src/services/worker-service.ts:269-271

Implementation Details

Server-Side Broadcasting

The SSEBroadcaster (located in src/services/worker/SSEBroadcaster.ts) manages a collection of active HTTP connections. When a broadcast is requested, it iterates through all connected clients and writes the event data to the response stream using the text/event-stream content type.

Connection Management

Connections are established via the ViewerRoutes. The worker service sets appropriate headers to keep the connection open and prevent browser caching:

• Content-Type: text/event-stream
• Cache-Control: no-cache
• Connection: keep-alive

The WorkerService also handles the processing_status broadcast, which aggregates information from the SessionManager regarding both queued and actively processing messages. Sources: src/services/worker/README.md, src/services/worker-service.ts:1016-1033

Integration with AI Agents

The SDKAgent acts as the primary driver for real-time updates. Within the processSDKResponse method, after an observation or summary is successfully stored in the database and synced to Chroma, the agent calls the broadcaster.

// src/services/worker/SDKAgent.ts:275-285
if (worker && worker.sseBroadcaster) {
  worker.sseBroadcaster.broadcast({
    type: 'new_observation',
    observation: {
      id: obsId,
      // ... metadata and content fields
      created_at_epoch: createdAtEpoch
    }
  });
}

Sources: src/services/worker/SDKAgent.ts:275-285, src/services/worker/SDKAgent.ts:333-345

Conclusion

Real-time Timeline Events via SSE provide the essential link between the background AI processing worker and the user interface. By centralizing event distribution in the SSEBroadcaster and leveraging the SDKAgent as a primary event source, the system achieves a responsive "live stream" feel for memory capture, while maintaining a clean separation between data persistence and UI notification layers. Sources: src/services/worker-service.ts:1016-1033, src/services/worker/README.md