Skip to content
HeartBadge docs

Implement Cora

Preview

A practical guide to wiring Cora into HeartBadge surfaces with same-origin APIs, consented context, safe actions, and a voice-ready Cloudflare runtime.

This guide covers the implementation shape for Cora on HeartBadge properties. It is written to help us add new Cora surfaces without weakening privacy, auth boundaries, or action safety.

Implementation goals

  • One companion identity across HeartBadge surfaces
  • Source-backed answers for HeartBadge content
  • Durable, member-managed conversation history
  • Explicit consent before private context is used
  • A narrow allowlist of reversible or low-risk actions
  • A separate operations plane for knowledge, flags, and testing

1. Start with the runtime boundary

The browser should talk to same-origin Cora APIs. Those APIs are responsible for:

  • resolving the current member or guest subject
  • evaluating consent grants
  • selecting private versus public routing
  • persisting threads, memory, and receipts
  • forwarding to the dedicated agent Worker when voice or worker-runtime turns are enabled

On Cloudflare, that means a Pages app for the site gateway and a separate Worker for the agent runtime. Pages should bind to the Worker through a service binding, not through a public URL. See Pages bindings and service bindings .

2. Keep identity host-only and subject-based

Do not widen the main HeartBadge session cookie for Cora. The host should continue to own its own session cookie. Cora should map authenticated members to an opaque subject id and signed-out visitors to a guest subject.

That gives us three useful properties:

  • the UI never needs raw member ids for conversation state
  • guest history can exist without full sign-in
  • cross-site continuity can be added later as an explicit subject exchange rather than by sharing cookies

3. Model the core records in D1

The durable schema should cover:

  • subjects
  • threads and messages
  • saved memories
  • consent grants
  • action proposals and action receipts
  • support-case drafts
  • skill definitions and configuration versions
  • knowledge sources, versions, documents, graph rows, and ingestion jobs

Keep public knowledge storage and private member context separate. Message bodies, account state, and other private context should be fetched on demand for the current member and current turn only.

4. Build the public surfaces first

Register and version Cora's public knowledge sources independently. The engineering source is ep.heartbadge.com, alongside the main HeartBadge site, HeartBadge Docs, and approved video transcripts.

Global launcher

Every major page can expose Cora through a lightweight launcher with a few surface-specific prompts. Keep it keyboard-accessible and explicit that Cora is AI.

Vault companion

The dashboard version should be deeper. This is where readiness context, saved memory, private consent toggles, and low-risk account actions make the most sense.

Video companion

On video pages, attach chapter title, description, and playback context to each turn. The long-term shape is to pair Stream playback state with caption-backed retrieval and voice interruptions.

OP_CAT operations panel

Keep Cora operations in a separate panel rather than burying them inside a larger dashboard module. Operators need a clean place to inspect source health, feature flags, skill state, and ingestion jobs.

5. Make private context opt-in

Cora should not silently read from account or MessageBox data. Use explicit scopes such as:

  • account readiness
  • MessageBox metadata
  • MessageBox body or search
  • video context
  • voice profile
  • cross-site history

The UI should show what private scopes are active and let members turn them off. When a scope is used, the assistant response should disclose what kind of context was used and how it was handled.

6. Keep actions narrow and confirmable

Cora’s first action layer should stop at reversible or clearly low-risk work:

  • resend verification email
  • mark selected MessageBox messages read or unread
  • archive or unarchive a Cora thread
  • save a support-case draft

Every write should follow the same lifecycle:

  1. propose
  2. preview
  3. explicit confirmation
  4. deterministic server validation
  5. execute
  6. write an audit receipt
  7. offer Undo when reversible

Avoid first-release support for money movement, wallet changes, passkey deletion, 2FA removal, or administrative actions.

7. Treat voice as a separate rollout

Voice mode should run through a dedicated Worker + Durable Object runtime, not just the browser. Cloudflare’s Agents voice stack is built for realtime audio, continuous transcription, and interruption handling.

Use it behind a separate feature flag until the Worker bridge is the default runtime for voice-enabled surfaces. See the Agents voice docs .

8. Use Stream captions as the video knowledge source

Cloudflare Stream already gives us the right primitives for a video-aware companion:

  • player playback state such as currentTime, play, and pause
  • caption generation or WebVTT upload
  • caption retrieval for transcript-backed answers

See the Stream Player API and caption docs .

9. Keep observability useful without leaking payloads

For sensitive turns, keep operational metadata while skipping raw prompt and response payload logging. Cloudflare documents the cf-aig-collect-log-payload header for this exact case in the AI Gateway logging docs .

10. Roll out in stages

  1. internal OP_CAT controls and knowledge scaffolding
  2. public text-only launcher
  3. signed-in durable memory and read-only private context
  4. safe actions and MessageBox opt-in
  5. support continuity
  6. voice and full video companion behavior

The main implementation discipline here is honesty: document what is live, flag what is preview, and avoid presenting research or planned privacy work as if it were already guaranteed in production.

Related

Edit this page on GitHub Report an issue