Pixie Companion Framework — Product Overview for MAIE
MAIE · Identity Framework · Tier 2
The Pixie Companion
A living, responsive avatar that is the face of every user's MAIE experience. Not a decoration — a real-time mirror of identity, workflow state, and earned reputation, fully customizable and portable across contexts.
Live phase →
Theme →
Three-tier identity architecture
Tier 1
UserIdentity
Immutable provenance layer. Owns the identity glyph and stamps all creator assets. Never altered by cosmetic changes.
identity_id
glyph seed
provenance
Tier 2
PixieCompanion ← you are here
Visual and behavioral companion. Carries the identity glyph but is fully replaceable. Changing archetype, theme, or skin never touches Tier 1.
archetype
theme_id
pixie_name
preferences
asset_id
Tier 3
Runtime State
Ephemeral phase layer. Never persisted. Driven live from AgentWorkflowPanel callbacks — phase, mode, progress, and temperament.
phase
mode
progress %
temperament
The five archetypes
Workflow phase → animation mode mapping
idle
ambient
planning
tools
review
tools
executing
active + progress ring
completed
active → ambient
failed
ambient / subdued
Persistence model
Tablepixie_companions
Preferences storageJSONB (no migration per dim.)
Preference mergeArchetype defaults + user overrides
CachelocalStorage (maie_pixie_{userId})
Optimistic updatesYes — auto rollback on failure
Runtime stateNever persisted
Customization dimensions (free tier)
Archetype5 options
Color theme13 built-in palettes
Animation styleorbit / wave / pulse / neural / static
Core shapecircle / hexagon / diamond / shield
Particle densitysparse / normal / dense
Ring count1 / 2 / 3
Living reputation echoes
Achievement and milestone events mint permanent satellite marks that orbit the Pixie canvas. Each echo carries physics: fresher echoes pulse faster and sit closer in; older ones drift outward and slow. More significant events render larger and brighter. These are memory nodes — stable against wake distortion and mouse magnetism — so they read as a permanent, legible record of the user's history on the platform.
ACHIEVEMENT_ARTIFACT
LEGACY_ECHO
resonance: drives glow · createdAt: drives orbit radius + pulse speed
Export and portability
PNG snapshot
Lossless canvas capture at any scale via toDataURL()
Animated SVG
Procedural SVG with CSS keyframes for embedding anywhere
Drag-and-drop
Native HTML drag events pipe a PNG blob to any drop target
Marketplace skins
AGENT_SKIN assets composite onto canvas, clipped to core shape
Marketplace integration
AGENT_SKINPremium visual texture, composited
IDENTITY_THEMEBundle: animation + shape + palette
ACHIEVEMENT_ARTIFACTMinted on approval — reputation echo
LEGACY_ECHOMilestone marker — permanent orbit
Migration status
Feature flagPIXIE_V2=true
ReplacesUserAgentPersona + useAgentPersona
API (old)GET/PUT /api/agent/persona
API (new)GET/PUT /api/pixie
DB migrationpixie_companions table (Alembic)