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 / interactive-viewer-client

Interactive viewer client

The interactive viewer client is the local web application for reading and managing captured coding memory. It combines durable HTTP reads with a live event stream so an engineer can browse timelines and sessions, inspect context, change runtime settings, view diagnostics, and request safe management actions from one local surface.

Viewer role

Local viewer boundary

The viewer is served by the local worker at /viewer. The browser uses the same worker for memory data, settings, context previews, media, logs, sync state, and user actions. It is therefore a view and control surface for local runtime state, not a separate data service. See Local runtime API for the worker boundary and HTTP API and auth for request access rules.

The worker also serves My Work at / and /work-view, plus an inert /restart page. A GET to /restart does not restart the worker. The restart page waits for a different process that is ready before it reports success. If an install has no viewer files, the worker returns a clear recovery page instead of an empty application.

References: src/…/ViewerRoutes.ts• L20-84 src/…/ViewerRoutes.ts• L223-303

Viewer navigation

The client has a timeline view and a sessions view. The timeline combines observations, session summaries, and user prompts. The sessions view lists captured sessions and opens one session as a filtered timeline. The URL hash stores this view state, so a session has a stable browser address without a server-side page route.

The client keeps the last timeline or session scope while the user visits the sessions list. This lets the user return to a still-valid feed without losing its loaded history. The header connects these views to project filtering, theme and language choices, context settings, help, logs, processing state, and cloud-sync freshness.

References: src/…/App.tsx• L101-132 src/…/App.tsx• L509-690 src/…/Header.tsx• L80-211 src/…/sessions.ts• L92-121

Memory browsing

Timeline feed

The timeline presents three memory kinds in newest-first order: observations, summaries, and prompts. It joins rows received from the live stream with older pages read from the worker. Project and session scope narrow the same feed rather than creating a second memory model.

Each kind has its own older-page progress. The client loads more history as the reader reaches the end. A search or kind filter searches the rows already loaded and asks the reader before it loads more history. Repeated prompts can fold into one row while the count still represents every memory.

The feed supports kind filters and word search. Observation cards can show a summary, facts, or narrative. Summary cards can fold their sections. Long prompts can expand in place. These controls change how the client reads a memory; they do not change stored data.

Long histories use a windowed list. Loaded records remain available for search and counts, while only rows near the visible area are drawn. The client keeps the reader's place when rows change size, arrive, or are deleted.

References: src/…/App.tsx• L285-323 src/…/Feed.tsx• L105-270 src/…/feed-display.ts• L12-43 src/…/ObservationCard.tsx• L102-224 src/…/WindowedFeed.tsx• L141-165

Session catalog

The session catalog gives captured work a session-level entry point. Each entry shows the project, source, session identity, title when known, item count, and start time. The catalog reads older pages as the list grows and keeps live sessions visible while a page is being read.

The viewer identifies a session by the pair (platform_source, content_session_id). This prevents equal content IDs from different hosts from being merged. The pair also travels through hash routes, feed scope, pagination, live events, and deletion requests.

The catalog merges live additions, count changes, title changes, and deletions with pages that are in flight. It removes duplicates and confirms a refresh when overlapping changes could make a page look current. Session search covers the loaded catalog only; older sessions load when the reader asks for them.

References: src/…/useSessionCatalog.ts• L17-25 src/…/useSessionCatalog.ts• L56-165 src/…/SessionList.tsx• L58-199 src/…/sessions.ts• L1-63 src/…/sessions.ts• L173-247

Session detail

The session detail view reuses the timeline feed for one session. It adds a session header with the title, project, source, ID, count, and time span. This keeps browsing consistent while giving a session its own context.

The detail view supports category filters and word search over loaded rows. The newest summary can stay pinned above the list. Filter counts show the loaded portion and mark the total as partial when older rows remain on the worker. Changing sessions clears the old filters so they do not silently affect a new session.

References: src/…/SessionDetailPage.tsx• L53-109 src/…/SessionDetailPage.tsx• L112-212 src/…/CategoryFilter.tsx• L25-103

Observation media

An observation can carry bounded media references without carrying image data in the main row. The client resolves each reference through the media API, shows a small card strip, and opens a larger gallery when the reader selects an image.

The viewer separates media readiness from the memory feed. It distinguishes processing, downloading, ready, rejected, failed, unavailable, and read-error states. Pending states are checked for a bounded time and then offer a retry. A failed thumbnail does not hide a usable full-size image, and source details load only after an explicit request.

References: src/…/ObservationMedia.tsx• L41-107 src/…/ObservationMedia.tsx• L124-205 src/…/useMediaStates.ts• L13-90 src/…/media.ts• L16-100

API and event connections

HTTP data connections

The viewer uses the worker's local HTTP API for durable reads and writes. Reads provide memory pages, session pages, projects, context output, settings, media state, logs, processing state, and backup status. Writes save settings, delete memory or sessions, clear logs, record visible viewer activity, and request a restart.

The main browser-facing connections are:

PurposeConnection
Memory pagesGET /api/observations, /api/summaries, /api/prompts
Session pages and deletionGET /api/sessions, DELETE /api/sessions/:platformSource/:contentSessionId
Projects and contextGET /api/projects, GET /api/context/preview
MediaGET /api/media/:id, /viewer, /llm, and /details
Settings and backupsGET and POST /api/settings, GET /api/backup/status
Processing stateGET /api/processing-status
LogsGET /api/logs, POST /api/logs/clear
Viewer presencePOST /api/work-view/activity
Worker restartPOST /api/admin/restart from /restart

Media metadata is the browser's readiness contract. The viewer uses it to choose an image, a status, polling, or a retry. Source details are a separate owner-only read and are not part of normal browsing.

References: src/…/api.ts• L1-8 src/…/types.ts• L1-195 src/…/useMediaStates.ts• L27-61 src/…/useSettings.ts• L41-93

Server-sent events

The /stream endpoint is a server-sent events (SSE) connection. SSE is a long-lived HTTP response through which the worker sends small JSON events to open viewer tabs. The stream provides the initial project catalog, new memory rows, processing state, sync state, durable-change notices, and deletion notices.

The stream is a change signal, not a replay log. When the client reconnects or receives data_changed, it rereads the affected memory pages and session catalog. Live rows stay separate until a durable read makes them part of the baseline. This lets the worker remain the authority even when an event does not contain the changed row.

The client reconnects after a stream error. A visible local page also renews a viewer-activity lease and stops renewing when hidden or closed. A delete in one tab reaches other tabs through the stream, so open views remove the same memory or session.

This diagram shows how durable reads, live worker events, and local viewer actions meet in the browser.

flowchart LR
    W[Local worker] -->|HTTP pages and status| V[Viewer client]
    W -->|/stream SSE events| V
    V -->|Visible activity lease| W
    V --> T[Timeline]
    V --> S[Sessions and session detail]
    V --> C[Context and settings]
    V --> M[Management actions]
    M -->|HTTP writes| W
    W -->|Change and delete events| V

References: src/…/ViewerRoutes.ts• L305-346 src/…/useSSE.ts• L31-51 src/…/useSSE.ts• L168-314 src/…/types.ts• L113-132

Processing status

Processing status describes worker activity rather than stored memory. The worker sends whether work is active and how much work is waiting. The header uses this data for its activity and queue display.

The client also reads /api/processing-status when the stream opens, while a visible page is open, and when the page regains focus. A read cannot replace a newer stream value. A temporary read failure keeps the last known status.

References: src/…/ViewerRoutes.ts• L331-345 src/…/useSSE.ts• L141-166 src/…/useSSE.ts• L275-295 src/…/Header.tsx• L102-129

Sync status

The viewer presents cloud-sync freshness as a browser-safe status. It separates local feed connection from cloud evidence, so an open SSE connection does not by itself mean that cloud data is current.

The header can show current, catching up, paused, unavailable, incomplete, unknown, or stale. The display uses the worker's evidence time and a browser monotonic clock. Old evidence becomes stale even when the browser remains connected.

References: src/…/useSSE.ts• L127-137 src/…/useSSE.ts• L204-231 src/…/sync-presentation.ts• L79-129 src/…/Header.tsx• L34-77

Context settings

Context preview

The settings dialog shows the context that the worker would prepare for a selected project. The reader can choose one source or all sources, then view the resulting text in a terminal-style preview. A short delay after a choice avoids sending a request for every keystroke or selection change.

The preview uses the worker's context path that also serves session-start context. It is a read-only explanation of expected startup context and does not create a memory row. The viewer marks the preview as loading until it matches the current source and project selection, so old output is not shown under a new label.

The preview can report that it was shortened. The user can copy the shown text or open the selected project in the timeline to read the full source memories. See Observation generation and provider runtime for the provider path and Smart file read gate for the file-read setting.

References: src/…/useContextPreview.ts• L35-171 src/…/ContextSettingsModal.tsx• L314-324 src/…/TerminalPreview.tsx• L42-109 src/…/settings-preview.ts• L14-57

Context controls

The dialog groups settings by their effect on context, capture, display, provider use, backups, and worker operation:

  • Loading controls recent observations and sessions and whether startup context includes all sources.
  • Display controls expanded observation detail and whether token values appear.
  • Context controls the last summary, last message, and smart file-read behavior.
  • Images controls whether new screenshots and images stay available to the viewer.
  • Backups controls automatic snapshots, interval, retention, and current backup status.
  • AI provider controls memory capture, provider choice, model, and provider credentials or endpoint choices.
  • Fallbacks controls what serves observation work when the selected provider or credential cannot serve it.
  • Advanced contains worker and related work-view settings that are not part of the main context choice.

The form keeps edits local until Save. It validates number ranges before submission and disables saving until the first settings read succeeds. The client sends only changed writable values from the settings last loaded by that tab. Masked secrets remain unchanged unless the user deliberately replaces them. File-only and team-owned values stay read-only. Some saved changes, such as backup scheduling, need a worker restart before they take effect.

The settings dialog now presents these groups as an accessible tab interface. On narrow screens the tabs form a horizontal row; on wider screens they form a vertical list. Arrow keys, Home, and End move between sections. The selected section resets its scroll position, and keyboard selection brings the chosen tab into view. The dialog also asks for confirmation before closing with unsaved changes, restores focus when the user keeps editing, and shows load or save causes under a details disclosure instead of replacing the main status with raw error text.

The dialog exposes provider and fallback choices as part of the same settings contract. OpenAI-compatible endpoint presets provide a shared label, endpoint, and default model view. An unknown or blank preset uses the custom endpoint behavior. The viewer must keep these choices aligned with the worker's provider settings.

References: src/…/ContextSettingsModal.tsx• L274-475 src/…/ContextSettingsModal.tsx• L478-653 src/…/ContextSettingsModal.tsx• L655-946 src/…/ContextSettingsModal.tsx• L948-1099 src/…/useSettings.ts• L36-149 src/…/settings-form.ts• L8-68 src/…/openai-compat-presets.ts• L18-52

User-initiated management actions

Memory deletion

The viewer can delete an observation or summary from its card. The worker commits the change before it broadcasts the deletion. This order prevents another tab from hiding data that the worker did not remove.

The client removes the row from live and paged data and moves the page position back when a loaded row disappears. A delete refusal stays on the card so the reader can understand that the item remains.

References: src/…/App.tsx• L411-441 src/…/ObservationCard.tsx• L184-223 src/…/feed-deletion.ts• L1-51

Session deletion

The sessions view can delete a complete inactive session and its captured rows. The worker refuses the action when the session is still running, contains rows owned by another synced device, or cannot record the delete for cloud sync.

The browser asks for confirmation and keeps the card when the worker refuses. A successful delete removes the session from the catalog and every loaded feed. If another tab deletes the open session, the detail view returns to the sessions list. A later incarnation of the same session identity is not removed by an older HTTP response.

References: src/…/SessionCard.tsx• L20-79 src/…/SessionCardMenu.tsx• L11-46 src/…/App.tsx• L443-480 src/…/sessions.ts• L124-153

Log management

The memory log drawer is a local diagnostic surface. It reads the recent worker log window, filters by level, component, text, or alignment, can follow new lines, and can show a selected line in full. It does not change memory data.

Clearing logs is a separate confirmed action. If the worker does not answer in time, the drawer rereads the log file and reports that the result is unknown instead of claiming that the clear succeeded.

References: src/…/LogsModal.tsx• L112-249 src/…/LogsModal.tsx• L272-329 src/…/LogsModal.tsx• L406-546

Worker restart

The restart page turns a clear button press into POST /api/admin/restart. It then waits for a successor process with a different process ID and a ready worker state. This avoids treating the old process, a bound port, or a shallow health response as proof that the restart finished.

The page is inert on load and refuses framing. These limits reduce the chance that another local web page can cause a restart without a clear user action. See Server jobs and process supervision for the worker lifecycle around this action.

References: src/…/ViewerRoutes.ts• L86-212 src/…/ViewerRoutes.ts• L282-303

Change checklist

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

  • Keep (platform_source, content_session_id) aligned across catalog rows, hash routes, feed filters, delete URLs, and session_deleted events.
  • When a stream event changes, update the shared event shape, worker broadcaster, browser decoder, and reconnect refresh behavior together.
  • Treat data_changed as invalidation. Keep its kind names aligned with the three feed reads and the catalog refresh path.
  • Keep live-row retention separate from loaded-page history. A bound change must not change pagination recovery.
  • Preserve the feed's stable row keys, measured heights, focus neighbors, and scroll anchor when windowing changes.
  • Keep search semantics aligned with prompt folding, loaded-row counts, session counts, and partial-total labels.
  • When a settings field changes, update the form, type, default, validation, masking, writable allowlist, and preview inputs together.
  • Keep settings saves diff-based. Do not let an old tab post unchanged values over newer settings.
  • Keep settings section names, tab/panel relationships, responsive orientation, keyboard movement, and close-confirmation focus behavior aligned when the settings dialog changes.
  • Keep viewer endpoint presets aligned with worker presets. Unknown and blank IDs must retain custom endpoint behavior.
  • Keep media status mapping aligned with metadata states, variant routes, bounded polling, and retry behavior.
  • Keep source-detail requests explicit. Normal media browsing must use safe metadata only.
  • Keep deletion order and page offsets aligned: commit first, broadcast second, then rebase loaded pages after removed rows.
  • Keep delete refusal messages aligned with worker responses for active sessions, remote rows, missing sessions, and sync outages.
  • Keep sync freshness separate from feed connection state. Stale or limited evidence must not render as current.
  • Keep visible-page activity local and bounded. Stop renewal when the page is hidden or closed.

Important failure modes

TriggerConsequenceGuard
The worker database is not ready when /stream is requestedThe viewer gets 503 Service initializing and has no live updatesThe worker checks store readiness and the client reconnects after stream errors
A reconnect or data_changed event is treated as a row replayDurable rows can be missed or an old page can remain visibleThe client rereads affected pages and keeps live rows until the baseline catches up
A session uses only content_session_idEqual IDs from different hosts can mergeEvery session operation uses the source and content ID pair
A session is active or contains another device's rowsThe worker refuses deletion and the card must remainConfirmation is followed by worker refusal text rather than optimistic removal
Cloud sync cannot record a deleteLocal data is not removed because other devices could keep itThe worker performs a sync safety check before mutation
A settings save posts viewer defaults before the first read completesStored provider, port, or secret values can be overwrittenThe form stays disabled until the initial settings read succeeds
A stale settings tab posts its full local copyA newer change can be silently restored overThe client posts only values changed from that tab's last read
A settings tab or panel loses its accessibility relationshipKeyboard or assistive-technology users can change sections without a clear active panelKeep the tablist, selected tab, controlled panel, orientation, and focus movement as one contract
A media replica is still downloading or conversion is slowThe card can show a false failure or broken imageThe client distinguishes pending and downloading states, polls for a limit, and offers retry
A source-detail request runs during normal image browsingLocal source paths can be exposed without intentThe viewer requests owner details only from the explicit source-details action
A page response arrives after the project or session changedRows from the old view can enter the new viewRequests carry scope ownership and stale responses are ignored
A catalog page overlaps live additions or deletionsSessions can duplicate, return, or skipThe catalog journals live changes and merges by the full session identity
Sync evidence becomes old while the stream stays openThe header can falsely report current cloud dataThe client ages evidence with a monotonic clock and shows stale or unknown state
The restart request answers before the old process exitsThe page can report success for the dying workerThe restart page requires a different process and readiness
Viewer files disappear during an install updateThe user gets a blank or stale pageThe worker returns a 503 recovery page and points to worker restart

Key files

FileWhy to read it
src/…/App.tsxShows how routes, live rows, paged rows, filters, refreshes, and deletes form the main client flow.
src/…/useSSE.tsDefines the live connection, reconnect signal, processing state, sync state, and viewer activity.
src/…/useSessionCatalog.tsExplains session paging and the merge between live changes and catalog pages.
src/…/Feed.tsxShows timeline browsing, filtering, search, card selection, and load-more states.
src/…/WindowedFeed.tsxShows how long histories preserve position while drawing only nearby rows.
src/…/SessionList.tsxShows session search, paging, empty states, and the handoff to session actions.
src/…/SessionDetailPage.tsxShows how one session reuses the feed and adds session context and filters.
src/…/sessions.tsDefines session identity, routes, titles, deletion requests, and catalog merging.
src/…/ObservationMedia.tsxShows how media references become thumbnails, a gallery, and optional source details.
src/…/useMediaStates.tsExplains media readiness, bounded polling, retries, and image-load errors.
src/…/ContextSettingsModal.tsxShows the user-facing context, provider, image, backup, fallback, worker, and accessible settings controls.
src/…/useContextPreview.tsConnects source and project choices to context preview output.
src/…/useSettings.tsDefines settings loading, diff-based saves, and protection against early or read-only writes.
src/…/sync-presentation.tsDefines the safe sync-status shape and freshness labels used by the header.
src/…/LogsModal.tsxShows local log browsing, filtering, refresh, and clear behavior.
src/…/ViewerRoutes.tsShows how the worker serves the viewer, stream, health page, and restart page.