Cora Companion
How Cora works across HeartBadge surfaces: launcher, memory, consent, safe actions, knowledge, and voice-ready runtime boundaries.
Cora is the HeartBadge companion and concierge. It is designed as one persistent AI guide across the public site, the signed-in dashboard, the support center, and the intro-video experience.
The main HeartBadge application is the authoritative runtime because it already owns member identity, session state, and the D1 data model that powers account readiness, memory, consent, and action auditing.
What Cora is responsible for
- Answering HeartBadge questions with citations
- Summarizing the current page or video chapter
- Explaining next steps in plain language
- Using private member context only after explicit consent
- Staging low-risk reversible account actions behind confirmation
- Giving operators a dedicated control plane for knowledge and rollout
Architectural layers
1. Surface layer
Cora appears as a launcher on the main site, a richer signed-in panel in Vault, a sidecar beside the intro playlist, and a separate operations panel in the OP_CAT dashboard.
2. Same-origin gateway layer
Each web surface talks to same-origin Cora APIs rather than calling an agent runtime directly from the browser. This keeps session handling, consent evaluation, and request shaping inside the host application.
HeartBadge uses Cloudflare Pages Functions for these gateway routes and binds them to D1, Workers AI, and service bindings through Pages bindings. See Cloudflare’s documentation on Pages bindings .
3. Subject, thread, memory, and consent layer
Cora does not expose raw account identifiers in its public interface. Each conversation belongs to an opaque subject. Signed-in members get a durable subject tied to their HeartBadge account. Signed-out visitors get a guest subject scoped to the current browser session.
Durable thread history, saved memories, consent grants, skill definitions, action proposals, action receipts, and knowledge metadata all live in D1.
4. Runtime layer
Text turns are currently handled through the main app’s Cora runtime. Voice mode is scaffolded through a dedicated Cloudflare Worker with a Durable Object per conversation thread, which is the correct shape for realtime audio and long-lived session state.
Cloudflare’s voice channel for Agents is built around realtime audio, automatic conversation persistence, continuous speech-to-text, and interruption handling. See the Cloudflare Agents voice docs .
The Pages app reaches that Worker through a service binding. Service bindings let one Worker call another without exposing a public URL. See Cloudflare service bindings .
5. Knowledge and citation layer
Cora’s public knowledge is organized into four versioned families:
- HeartBadge site content
- Docs content
- Engineering and architecture material from ep.heartbadge.com
- Intro-video captions and chapter summaries
Factual HeartBadge answers are expected to carry source citations. Public retrieval is separate from private member context, which is fetched on demand and not published into shared knowledge stores.
Privacy and consent model
Cora is always presented as AI. Signed-in members can allow Cora to use specific private scopes such as account readiness or MessageBox metadata, and those scopes can be revoked later.
- Thread history is durable until the member deletes it
- Reusable memory is member-managed
- Private context is turn-scoped unless the member explicitly saves it
- Receipts record scope, timestamps, and hashes rather than raw private content
For AI Gateway observability, HeartBadge plans around metadata-only logging
for sensitive turns by using the cf-aig-collect-log-payload header. Cloudflare documents that
header here:
AI Gateway logging controls
.
Safe actions
Cora’s first action set is intentionally narrow. Low-risk flows are staged as a proposal, previewed to the member, explicitly confirmed, validated on the server, executed, and then written to an audit receipt.
That posture is deliberate: Cora can help with safe, reversible work, but not with money movement, wallet changes, credential removal, or other irreversible actions.
Video companion model
On video pages, Cora is meant to understand the current chapter and cite the matching transcript window. The current architecture uses Cloudflare Stream captions as the retrieval source and the Stream Player API for playback state such as current time, play, and pause.
See Cloudflare’s docs for the Stream Player API and Stream captions .
Current rollout posture
Cora is being shipped in stages. The text companion, dashboard context, and OP_CAT control plane are the first concrete implementation surfaces. Cross-site continuity, full knowledge ingestion, live video-time syncing, and realtime voice are later rollout stages and should be described as such in implementation work.