molroo API

molroo API is an emotion middleware that gives AI characters psychologically grounded, evolving emotional states. Instead of prompt-hacking emotions or relying on memory tricks, molroo computes emotions using established psychological models — and returns LLM-ready prompts you can inject directly.

What It Does

Your App  →  molroo API  →  Your LLM
   ↓              ↓              ↓
Messages     5-Stage       prompt_data
             Pipeline      (system + context
             Computation    + instruction)

Pick a preset or define a custom persona with Big Five personality traits
Send messages through the simplified turn API
Get back computed emotional state + prompt_data with structured prompts ready for your LLM

Key Features

Feature	Description
Persona Presets	5 built-in personality templates — start in seconds
Simplified Turn	Just send `{ sessionId, message }` — no event wrappers needed
prompt_data	LLM-ready structured prompts (system, context, instruction) in every response
WebSocket	Real-time emotion updates via Durable Objects with hibernation
Relationship Tracking	Trust, attachment style, and unhealthy pattern detection
Proactive Behavior	Characters that initiate — attachment seeking, emotional overflow, need deficits
Appraisal Vectors	Direct appraisal input for game events and non-text interactions
Webhooks	HMAC-SHA256 signed push notifications for proactive actions and stage transitions

API Endpoints

Method	Path	Description
`POST`	`/v1/persona`	Create a session (supports presets)
`GET`	`/v1/persona`	List sessions (cursor-based pagination)
`GET`	`/v1/persona/:id`	Get session metadata
`DELETE`	`/v1/persona/:id`	Delete a session
`GET`	`/v1/presets`	List 5 persona presets
`POST`	`/v1/turn`	Process a conversation turn
`POST`	`/v1/turn/appraisal`	Process from appraisal vector
`GET`	`/v1/state/:id`	Get full emotional state snapshot
`GET`	`/v1/proactive/:id`	Check pending proactive actions
`PUT`	`/v1/proactive/:id/preferences`	Configure proactive behavior
`GET`	`/v1/relationship/:id`	Get relationship state
`POST`	`/v1/webhook/:id`	Register webhook
`GET`	`/v1/webhook/:id`	List webhooks
`DELETE`	`/v1/webhook/:id/:webhookId`	Delete webhook
`GET`	`/v1/ws/:id`	WebSocket upgrade (real-time)
`GET`	`/v1/health`	Health check (no auth)

Psychology Engine

Every interaction flows through a 5-stage computation pipeline:

Appraisal (Scherer CPM) — Evaluate emotional significance across 6 cognitive dimensions
Dynamics (Sprott ODE) — Physics-based inertia, decay, and personality-driven response
Resources (SDT + Energy) — Track psychological energy and core needs
Regulation (Gross Model) — Apply personality-appropriate coping strategies
Transition (Cusp Catastrophe) — Detect nonlinear state changes with hysteresis

Built on 9 peer-reviewed psychological theories. Zero external dependencies. Deterministic and explainable.

Next Steps

Quick Start — First API call in under a minute
Authentication — Set up your API key
Persona Presets — Explore the 5 built-in templates
prompt_data — How to use LLM-ready prompts
API Reference — Full endpoint documentation

Overview