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 / hosted-viewer-service

Hosted viewer service

The hosted viewer service gives an owner browser access to a cloud copy of My Work. It authenticates the owner at the edge, limits which worker actions can cross the public boundary, and records small viewer-use events without exposing the owner's memory or identity to the analytics system.

Service boundary

Hosted viewer replica

The hosted viewer runs one worker replica for one owner. The replica pulls the owner's synced records and serves the same work-view experience as a local worker. It does not capture new sessions or run work-view refresh jobs by default, so the owner's devices remain the source of new work data.

The gate is the only public path to the replica. It keeps the worker on loopback and forwards approved browser requests to it as local requests. This design keeps sync credentials and machine controls out of the browser.

flowchart LR
    A[Owner browser] --> B[Hosted viewer gate]
    B -->|approved request| C[Owner's cloud worker]
    C --> D[Synced My Work records]
    B --> E[Hosted viewer usage]
    E --> F[PostHog]

References: services/…/index.ts• L1-21 services/…/index.ts• L41-59 services/…/index.ts• L78-93

Access control

The sign-in service creates a short-lived link token for the signed-in owner. The viewer accepts that token only once at /auth, checks that its owner matches the configured viewer owner, and exchanges it for a longer-lived HttpOnly session cookie. The browser does not keep using the link token after this exchange.

The link and session use separate token audiences. A token with the wrong audience, owner, signature, or expiry is rejected. This prevents a link from being reused as a session or used to open another owner's viewer.

References: services/…/token.ts• L1-19 services/…/token.ts• L27-44 services/…/gate.ts• L22-24 services/…/gate.ts• L124-161

Request gate

The gate requires a valid owner session before it serves the viewer or forwards an API request. A browser page without a session goes to the sign-in page; a non-HTML API request receives an unauthorized response instead.

After authentication, the gate applies a method and path policy. It permits work-view reads, blocks machine settings and maintenance paths, and permits only the My Work actions that save review, focus, rule, suggestion, completion, or usage state. Other writes stay on the owner's computer.

References: services/…/gate.ts• L25-38 services/…/gate.ts• L108-116 services/…/gate.ts• L169-207

Browser request origin

The gate protects state-changing requests from cross-site use. A write must carry the public viewer origin and must not be marked as a cross-site fetch. The gate then removes browser cookies, proxy headers, and public origin data before it sends the request to the loopback worker.

This creates two separate checks: the gate proves that the browser may act for the owner, and the worker receives a local request that cannot inherit the browser's network identity. Response cookies from the worker do not pass back to the browser.

References: services/…/gate.ts• L40-49 services/…/gate.ts• L203-243 services/…/gate.test.ts• L149-212

Hosted work-view access

Shared focus pages

The hosted viewer is the browser-facing side of a shared focus page. The local worker publishes a filtered snapshot for an eligible kept or done focus area, and a background publisher keeps that page current even when My Work is not open. The hosted service controls who can open the resulting experience and which My Work changes can be saved from it.

The page therefore shows shared work state rather than the owner's raw memory. The publisher removes owner prompts, evidence, conversations, products, and machine names before the snapshot reaches the hosted page. It sends only changed page content, and it stops a link when its area is no longer shareable. See TeamBrain and work-view for the work-view model and Work-view experience for the browser experience.

References: src/…/focus-share-publisher.ts• L1-16 src/…/focus-share-publisher.ts• L61-99 src/…/focus-share-publisher.ts• L102-161 src/…/to-shared-focus.ts• L67-112 src/…/focus-share.ts• L1-9 src/…/focus-share.ts• L72-127

Worker availability

The public health endpoint reports that the hosted service is up while separately describing whether its worker is ready, busy, or down. It does not require an owner session and does not wait for a long worker operation. If the worker is unavailable, an authenticated page request receives a short starting response while the host process restarts the worker.

References: services/…/gate.ts• L136-149 services/…/gate.ts• L219-235 services/…/index.ts• L63-73

Usage accounting

Viewer event reports

The hosted page sends a page view when the document opens, then reports the page that opens or the page that the person switches to. The report contains only a closed page name and, for a switch, the previous page name. Reopening the same page is not counted as a switch, and one document open is sent only once.

The hosted gate accepts only page view, open, and switch reports for known My Work pages. It converts them to the hosted viewer's PostHog events and answers the browser without sending them to the worker. Analytics failure does not block the work view, and the page does not retry a failed ingest.

References: src/…/usage.ts• L6-16 src/…/usage.ts• L31-62 services/…/gate.ts• L174-196 services/…/usage.ts• L55-81

Anonymous measurement

Hosted usage uses a random browser identifier stored in an HttpOnly cookie. It does not use the cmem account ID, create a person profile, run a browser analytics SDK, record sessions, or collect page content. The host marks events as hosted and includes the viewer hostname so hosted activity remains distinct from local worker telemetry.

References: services/…/usage.ts• L1-18 services/…/usage.ts• L37-41 services/…/usage.ts• L84-103 services/…/usage.test.ts• L23-39

The hosted viewer depends on the work-view projection and the shared-page publisher, but it does not create the work data that it displays. Read TeamBrain workflows for the surrounding TeamBrain actions and Work-view experience for the local and hosted browser flows.

Change checklist

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

  • Keep the link-token format and audience checks aligned with the service that mints sign-in links.
  • Keep the configured owner identity aligned with the synced worker identity. A mismatch must not expose another owner's records.
  • Keep the public path allowlist aligned with the My Work actions that are safe to sync back. New worker writes must not become public by default.
  • Keep browser-origin checks separate from loopback worker headers. Public cookies and proxy identity must not reach the worker.
  • Keep the shared-page shape aligned between the local publisher and the hosted page. A page must remain free of owner evidence and machine data.
  • Keep periodic publishing aligned with share state. A stopped link must not be recreated by a late update, and an area that is no longer eligible must lose its link.
  • Keep the hosted event allowlist and page-name set aligned with the viewer's usage sender.

Important failure modes

TriggerConsequenceGuard
A link token is reused or has the wrong ownerThe viewer refuses the exchange and sends the person back to sign-inSigned audience and owner checks plus one-use link tracking
A browser sends a state-changing request from another originA work-state change could be made through a cross-site requestPublic-origin and cross-site checks at the gate
A new worker write is not added to the gate allowlistThe hosted viewer cannot save that action, or a broad policy change could expose machine stateExplicit read and write path policy
The worker is down or busy during a page requestThe owner sees a bounded starting response instead of a hung proxy requestSeparate health check and worker restart path
The local work view cannot be read during a share updateThe hosted page keeps its last good snapshot instead of receiving a partial updatePublisher read-health check and per-area error state
An area is merged, dismissed, or returned to suggestionsIts old public link could remain available after the area is no longer shareableEligibility check plus a fresh read before stopping the link
A stop races with a periodic publishA stopped link could be recreated or an old update could replace a newer sharePer-area request ordering and update-only periodic publishing
Hosted usage ingest failsViewer analytics lose that event, but the work page still loadsBest-effort ingest and a successful empty response

Key files

FileWhy to read it
services/…/index.tsShows the hosted process boundary and the one-owner worker relationship.
services/…/gate.tsDefines authentication, request policy, origin checks, and proxy behavior.
services/…/token.tsDefines the shared link and session token contract.
services/…/usage.tsDefines the hosted usage event contract and anonymous measurement.
src/…/focus-share-publisher.tsKeeps eligible shared pages current and stops links that no longer match the owner's work view.
src/…/usage.tsShows which browser events the hosted page sends and when it sends them.
src/…/to-shared-focus.tsShows the safe shape of a shared focus page before hosting.
src/…/focus-share.tsShows how local work state becomes a hosted shared page and how sharing stops.