Karen AI — Oshun System Docs

What It Does

Karen is the central intelligence layer. Every inbound message — whether from WhatsApp, Instagram DM, the website widget, Telegram, or a voice call — is routed through Karen for processing and response.

Maintains full context: procedures, pricing, patient history, business persona, and care plans
Takes real actions inline: books appointments, sends care guides, escalates urgent cases, triggers emails
Follows the Forward-Thinking Protocol on every response: acknowledge the message → connect to the patient's goals → suggest a clear, actionable next step. Conversations never dead-end.
Classifies message complexity to route simple replies through cheaper models (Gemini) and complex reasoning through OpenRouter
Self-evaluates draft responses via reflection pass before delivery when confidence is low

External Service Details

OpenRouter — primary LLM gateway. Routes to the configured model (default: Claude). Handles all patient-facing chat and complex reasoning tasks.
Gemini — cheaper fallback for lower-complexity tasks (summaries, classifications). Uses a free pool key with a paid fallback.

Required environment variables:

OPENROUTER_API_KEY — OpenRouter authentication
OPENROUTER_MODEL — model string (e.g. anthropic/claude-3-5-sonnet)
GEMINI_API_KEY — free pool Gemini key
GEMINI_PAID_KEY — paid Gemini fallback

Journeys

Karen AI is the active intelligence in every patient journey:

Key Source Files

src/ai.js — Orchestrator. Entry point: chat() at line 125. Re-exports from all AI sub-modules. Note: this is the split version locally (547 lines) — server runs the monolithic version (2300+ lines).
src/context-builder.js — Assembles memory, permissions, and conversation history into the prompt context. Entry: buildContext() at line 20.
src/prompt-builder.js — Constructs the full system prompt and selects which actions are available for the current context. Key exports: buildDefaultPrompt() (line 217), selectActionsForContext().
src/model.js — OpenRouter API calls and response parsing. Key exports: callOpenRouter(), parseActionTags(), classifyComplexity().
src/reflection.js — Post-generation self-evaluation. Key exports: shouldTriggerReflection(), reflectOnResponse().
src/prompts.js — All prompt template constants: AVAILABLE_ACTIONS, MEMORY_INSTRUCTIONS, ACTION_CATEGORIES.
src/gemini.js — Gemini API client for cheaper task routing.

Known Issues

Local ai.js is SPLIT — always pull from server before editing. The local copy is a refactored split version (547 lines). The server runs the monolithic original (2300+ lines). Editing locally without pulling first will cause merge conflicts and overwrite server-side logic. Always ssh hetzner and pull the current file before making changes.

core_memory.js:161 — owner_tenant_id bug outstanding. There is an unresolved bug on line 161 of src/core_memory.js related to owner_tenant_id. This affects how per-tenant core memory (persona, goals) is read back. Do not rely on getCoreMemory() returning the correct owner context until this is patched.