explAIn’s behavior comes from two distinct LLM layers — the advisor (private) and the mediator (shared) — plus a catalog of mediator personas, each with genuinely different behavior rather than just a different prompt.
The advisor
The advisor is your private counsel. One advisor exists per user per conversation.
- Configurable: model, a style hint (e.g. “be terse”, “expand my thoughts”), and an active/inactive toggle.
- Triggered while you type: on a debounced timer, 600ms after your last keystroke (tuned up from 400ms to reduce overlapping advisor calls during normal typing).
- Streams to you only: suggestions arrive on an owner-only channel; the peer never sees them.
- You stay in control: send the original draft, send the advisor’s suggestion, or send an edited blend of the two.
- Choices are recorded: the send-mode is logged, which eventually powers stats like “user accepted the advisor 73% of the time.”
The mediator and its personas
The mediator is the shared layer. Its persona is agreed by both parties and processes each message after it is sent. Personas are not just different system prompts — each touches different parts of the system.
| Persona | Action | Behavior |
|---|---|---|
| Moderator | annotate | Passes the sent text through verbatim; attaches inline annotations (tone flags, clarity warnings, “this could read as accusatory”). Never rewrites. |
| Arbiter | transform | Rewrites the message for neutrality. Both parties see the original alongside the rewrite; the receiver gets the rewrite as primary content. |
| Judge | block-capable | Evaluates each message against a per-conversation charter. Violations are blocked: the sender sees the block and reason; the recipient never sees the message. The only persona with veto power. |
| Chronicler | passthrough + side-effect | Does not modify messages. Asynchronously writes parallel “chapter” summaries every N messages or on a time interval, surfaced as collapsible cards in the timeline. |
| Dungeon Master | narrate | Most messages pass through unchanged. On a cadence (or when narrative pacing calls for it) the DM injects a system-authored message with no human sender — scene transitions, NPC dialogue, environmental description. The only persona that creates messages on its own. |
Persona details
- Moderator — for difficult conversations where neither party wants the mediator rewriting them, but a third-party gut-check is welcome. Schema: writes
mediator_output(the annotation),final_rendered = sent_text. - Arbiter — for mediation between parties with strong emotional charge. The original is always visible in the “show your work” panel.
- Judge — for structured negotiations and conflict resolution with explicit ground rules. The charter is free-text agreed at conversation start (e.g. “no personal attacks, no bringing up the past”). Can set
status='blocked'and writemediator_reasoning. - Chronicler — for long-running creative collaborations, relationship logs, and TTRPG campaigns. Writes to a separate
chroniclestable; never touchesmessages. Chronicle privacy is per-conversation: shared (one canonical log) or per-user (each side sees its own framing). - Dungeon Master — for TTRPG-as-chat and collaborative fiction. Injects
messagesrows withsender_id=null.
Persona switching
Personas are switchable mid-thread. Either user can propose a switch; the other accepts or rejects. An accepted switch creates a conversation_events row of type='persona_switch', rendered as a visible system message in the timeline. From that message forward, the new persona is active.
Why switchable? Conversations evolve. A relationship chat might benefit from Moderator early, Arbiter when things get heated, and Chronicler over time. Forcing a single persona at creation makes the product brittle.
Multi-provider strategy
v0.1 ships DeepSeek only (cheap, OpenAI-compatible). The packages/llm abstraction already supports DeepSeek and Anthropic — switching providers is a one-line edit in the edge functions plus a different env-var key. v0.2 lifts the per-call provider and model into config so users can pick per conversation.
Related
- Product Vision — why transparency is the contract
- Architecture — the message lifecycle and how personas map to the schema
- Source of truth:
docs/design.md