**TLDR;** A real-time review layer for the digital twin that feeds corrections back into the PKG via Heimdall, the PKG's dedicated ingestion agent. A development-only internal tool for refining the digital twin's voice and knowledge. Calibration mode overlays inline review controls onto the normal chat interface, allowing each of the twin's responses to be approved, commented on, or rewritten in place. That structured feedback flows into the Personal Knowledge Graph (PKG) as targeted improvement proposals. **ELI5** The digital twin learns who Chris is from a knowledge base: his opinions, how he talks, things that matter to him. When a response misses the mark, calibration lets him flag it in the moment and leave a note about what was off. A separate system picks those notes up, decides what to update, and applies the changes before the next conversation. ## 'Reinforcement Learning' The twin draws its personality from the PKG, but massive knowledge gaps still exist in the PKG today: tone that's slightly off, missing context, responses that are technically accurate but don't sound right. The instinct of "that's not how I'd say it" is sharpest in the moment, during a live exchange and the calibration is built around this exact instinct. Rather than editing knowledge files after the fact, **feedback is given in real-time with the conversation.** ## What a session looks like Calibration mode is gated behind an environment flag and only available in development. When active, a toggle appears in the top corner of the interface.

A toolbar appears at the top of the viewport with a pulsing status indicator, a row of persona selector chips, and an end button. The chat interface underneath stays exactly the same. Conversation with the twin happens normally, the way any visitor would experience it. The difference is what appears below each of the twin's responses: inline review controls. **Approve**: the response is fine. **Comment**: opens a text field for noting feedback for reinforcement learning. **Rewrite**: opens a text field for writing an exact response if required.

Ending the session saves all reviews and outputs a structured .md of the twin's messages and annotated feedback. A second pathway skips the live conversation entirely. A dedicated calibration agent can be invoked in the development environment to conduct a structured interview, surfacing new knowledge through targeted back-and-forth, producing a staging document as output. ![The calibration agent in the development environment, receiving a request to interview Chris about his Apple origin story and produce a PKG staging document](/docs/ai-flow-documentation/screenshots/calibration/calibration_agent.png) ![The calibration agent conducting a structured interview with multiple-choice responses](/docs/ai-flow-documentation/screenshots/calibration/agent_interview.png) ## Feeding the learnings back to the PKG **The PKG lives in its own repository and serves as a host-agnostic knowledge base.** The portfolio is one of several hosts that read from it. So the portfolio can propose improvements based on calibration, **but it doesn't and cannot directly modify the PKG, this is intentional.** Feedback flows through three stages. After ending a session, the system packages them into a markdown file with metadata: what verdicts were given, the original and rewritten responses, and writes it to the PKG's designated intake directory. These staging files are picked up by Heimdall, the PKG's dedicated ingestion agent. Heimdall reads the full knowledge base alongside the staging proposal, classifies each signal (factual correction, tone correction, new knowledge, behavioral note), identifies which PKG file would be affected, and renders a verdict. Changes to core identity files require explicit confirmation.

Approved changes are applied to the appropriate PKG files. The staging entry is archived, the changelog records what changed, and the twin draws from the updated knowledge on its next conversation. ![Heimdall's completion output: every changed PKG file listed, staging entries archived, the bridge clear](/docs/ai-flow-documentation/screenshots/calibration/heimdall_complete.png) ## Built with the full pipeline in mind The calibration agent for the portfolio was intentionally built with knowledge of the entire pipeline, including Heimdall's mechanics. This means its scope extends beyond producing a staging document; it structures the handoff specifically for how Heimdall works. Rather than leaving Heimdall to infer context from the raw changes, the staging document includes a dedicated notes section: flagging which additions are genuinely new, which are relocations, where framing needs correction, and what requires extra scrutiny against PKG rules. The two systems are designed to work together. ![The staging document's Notes for Heimdall section: structured guidance that flags new content, relocated passages, and framing corrections before Heimdall begins its review](/docs/ai-flow-documentation/screenshots/calibration/heimdall_notes.png) The result is a tighter review loop. Heimdall receives exactly what it needs to make confident decisions, with less ambiguity about intent and less risk of misclassification. ![Heimdall's inline commentary acknowledging the quality of the proposal; the notes-for-Heimdall section made judgment easier](/docs/ai-flow-documentation/screenshots/calibration/heimdall_comment.png) :::eli5 The calibration system is how Chris tests and corrects the AI twin's responses. In developer mode, a review panel appears next to each AI response with three options: Approve it (good as-is), Comment on it (flag something to address), or Rewrite it (provide a better version directly). These corrections feed back into the PKG, the knowledge base the twin draws from.

Ingestion is handled by a separate agent called Heimdall, which reviews what has been submitted and decides whether it should actually change the PKG. This gatekeeping stops bad edits from slipping through.

The loop is: Chris talks to the twin, notices something off, provides a correction, Heimdall reviews it, and the PKG gets updated. A better PKG means better responses next time. :::