Feature Flags & Gating Reference¶

Applies to: All PRDs that affect access, limits, or feature availability Last Updated: February 2026 Provider: LaunchDarkly (SDK key configured via LAUNCHDARKLY_SDK_KEY)

How to Reference Feature Flags in PRDs¶

Any PRD section that introduces a limit, gate, or toggleable behavior should include:

**Feature flag:** `flag.key.name` (default: value)
**Enforcement:** [service/file that checks the flag]

Master Switches¶

Flag	Default	Purpose	Enforcement
`free_tier.enabled`	`true`	Enable free tier restrictions globally	`subscription_access_service.py`
`rate_limit.enabled`	`true`	Enable all rate limiting	`rate_limit_service.py`
`superpower.enabled`	`false` (prod) / `true` (dev)	Master switch for all superpowers	Feature flag evaluation
`superpower.user_created.enabled`	`false` (prod) / `true` (dev)	Enable user-created custom superpowers	Feature flag evaluation
`llm.force_basic_mode`	`false`	Emergency kill-switch: caps all tokens at 200, disables expensive features	`llm_client.py`

Free Tier & Subscription Flags¶

Flag	Default	Purpose	PRDs Affected
`free_tier.daily_message_limit`	`50`	Max messages per day for free users	5, 6, 12
`free_tier.superpowers_disabled`	`false`	Block superpowers in 1:1 for free users (deprecated — free users now get 1 slot)	1, 2, 3, 6, 12
`free_superpower_slots`	`1`	Number of superpower slots for free-tier users	1, 3, 6, 12
`payment.monthly_price_cents`	`799`	Monthly subscription price ($7.99)	6, 12
`payment.annual_price_cents`	`5000`	Annual subscription price ($50.00)	6, 12
`payment.stripe_enabled`	`true`	Enable Stripe payment processing	6, 12
`payment.paywall_enabled`	`false`	Require payment before feature access	6, 12
`payment.topup_enabled`	`true`	Enable credit top-ups (legacy, not user-facing)	12

Rate Limiting Flags¶

Flag	Default	Purpose	PRDs Affected
`rate_limit.message_budget_threshold`	`5`	1 AI unprompted message per N human messages	5, 10
`rate_limit.commands_per_minute`	`10`	Max commands per minute per user	1, 2
`rate_limit.miniapp_actions_per_minute`	`20`	Max miniapp actions per minute	1
`rate_limit.user_messages_per_minute`	`20`	Max user messages per minute	5, 8
`rate_limit.photos_per_hour`	`50`	Max photo uploads per hour	6, 7
`rate_limit.strict_mode_enabled`	`false`	Reduce all limits by multiplier	8
`rate_limit.strict_mode_multiplier`	`0.5`	Limit multiplier when strict mode on	8

LLM Token Flags¶

Flag	Default	Purpose	PRDs Affected
`llm.max_tokens.reflex`	`1500`	Max tokens for reflex responses	1, 5
`llm.max_tokens.deep_reasoning`	`2000`	Max tokens for complex reasoning	7, 10
`llm.max_tokens.default`	`1000`	Max tokens for standard responses	All
`llm.max_tokens.vision`	`1500`	Max tokens for vision/photo analysis	6, 7

Pipeline Flags¶

Flag	Default	Purpose	PRDs Affected
`pipeline.classifier_v2_enabled`	`false`	Combined classifier v2 (cost optimization)	All
`context.reduced_history_enabled`	`false`	Reduced conversation history mode	7
`context.max_messages`	`10`	Max messages in LLM context window	7, 10
`media.photo_batching_enabled`	`false`	Batch photo analysis for cost savings	6
`media.photo_batch_size`	`3`	Photos per batch	6

Caching Flags¶

Flag	Default	Purpose	PRDs Affected
`cache.response.enabled`	`true`	Redis-backed response caching	All
`cache.memory.ttl_seconds`	`300`	Memory search cache TTL (5 min)	7
`cache.llm_response.ttl_seconds`	`3600`	LLM response cache TTL (1 hour)	All

Progression & Relationship Flags (PRD 3)¶

Flag	Default	Purpose	PRDs Affected
`enable_relationship_tracking`	`true`	Master switch for 4-stage relationship state	3, 5, 7
`enable_level_system`	`false`	10-level formula-based progression (gates all of PRD 3)	3, 4, 10, 12
`enable_level_derivation`	`false`	Derive relationship stages from levels (replaces independent stage tracking)	3
`enable_persona_modifiers`	`false`	Memory-driven behavioral tuning via `derive_persona_modifiers()`	3
`enable_micro_bans`	`false`	Level-gated voice constraints in system prompts	3
`enable_superpower_tiers`	`false`	Bronze/Silver/Gold tier progression for superpowers	3
`enable_streak_tracking`	`false`	Consecutive-day streak system	3
`streak_saver_enabled`	`false`	Proactive streak-saving messages at 9pm	3, 10
`enable_companion_switching`	`false`	Allow Superpowers+ users to switch companions (per-companion levels preserved, new companion starts L1)	3, 6
`max_superpower_slots_paid_base`	`3`	Superpowers+ starting slot limit (grows to 6 at L10 when level system enabled)	3, 12
`max_superpower_slots_paid_cap`	`6`	Superpowers+ maximum slot limit at Level 10	3, 12
`enable_continuation_coordinator`	`true`	Proactive conversation continuations	3, 5

Onboarding & Growth Flags (PRD 6)¶

Flag	Default	Purpose	PRDs Affected
`enable_onboarding_survey`	`true`	Survey flow on ikiro.ai	6
`enable_companion_picker`	`true`	Companion picker with live previews (false = auto-assign best match)	6
`enable_cold_text_path`	`false`	Stranger mode + natural warm-up for cold texters	6
`cold_text_activation_message_count`	`3`	Number of back-and-forth exchanges before `pending_activation` → `activated`	6
`suppress_capability_hints_before_activation`	`true`	Block capability hints until `account_status == "activated"` AND stranger mode feature reveal completed. Prevents feature discovery from breaking the stranger-texting-a-person illusion.	1, 6
`enable_group_recognition`	`false`	Group chat implicit referral recognition (Path 3)	5, 6
`enable_assistant_switching`	`false`	Switch companion mechanic	3, 6
`enable_pregenerated_response`	`true`	Pre-generate Path 1 first response at companion selection (latency optimization, not an activation gate)	6
`enable_open_loop_triggers`	`true`	Conv 1 → Conv 2 open loop patterns	6
`enable_proactive_first_checkin`	`true`	18-22h proactive first check-in after Conv 1	6, 10
`enable_personality_read`	`true`	Personality test superpower's "read" moment	6
`enable_conversational_photos`	`true`	Assistant asks for photos in early conversations	6
`enable_onboarding_stage_2`	`true`	Stage 2 profile collection directives after name confirmed	6
`enable_onboarding_decline_detection`	`true`	Detect and respect user pushback on onboarding questions	6
`enable_referral_rewards`	`true`	3-referrals = 1-free-month reward system	6, 12
`referrals_per_free_month`	`3`	Number of activated referrals needed to earn 1 free month	6, 12

Group Chat Flags (PRD 5)¶

Flag	Default	Purpose	PRDs Affected
`enable_group_mode`	`false`	Master switch for group chat support	5
`group_message_budget_threshold`	`20`	MessageBudget N value: 1 unsolicited response per this many human messages	5
`group_max_responses_per_window`	`1`	Max unsolicited Luna responses per budget window (explicit invocations bypass)	5
`group_cooldown_after_friction`	`7200`	Seconds of silence after friction detected (e.g., "luna shut up")	5
`group_relevance_filter_enabled`	`true`	Edge agent logistics keyword + mention filter (~70% drop rate)	5
`group_memory_logistics_only`	`true`	Extraction-only policy: only store logistics-relevant content in group memory	5, 7
`group_poll_enabled`	`false`	Poll / consensus builder	5
`group_reminder_enabled`	`false`	Group-scoped reminder commitments	5
`group_checklist_enabled`	`false`	Trip / checklist broadcast	5
`group_bill_split_enabled`	`false`	Bill split in group context (requires dual gating: room owner sub + invoker loadout)	5, 12
`group_viral_tracking_enabled`	`false`	Exposure → conversion tracking (`group_exposure` table)	5
`group_first_contact_message_enabled`	`false`	Send norms message on first group appearance	5
`group_escalation_to_dm_enabled`	`false`	Redirect personal requests from group to 1:1 DM	5, 6

Memory System Flags (PRD 7)¶

Flag	Default	Purpose	PRDs Affected
`enable_memory_system`	`true`	Master switch for memory storage and recall	7
`memory_importance_threshold`	`4`	Minimum importance score (1-10) to store a memory	7
`memory_search_limit`	`10`	Max memories returned per search	7
`memory_top_k_injected`	`5`	Top-K memories injected into LLM context	7
`enable_multi_query_retrieval`	`true`	Tolan-inspired auxiliary question synthesis for broader recall	7
`enable_event_tracker`	`true`	Proactive "I Remember" — detects future events and schedules resurfacing	7, 10
`enable_memory_deduplication`	`true`	Nightly deduplication at 3am (cosine 0.85 threshold)	7
`enable_photo_memory`	`true`	GPT-5 Vision memory extraction from photos	7
`memory_dedup_similarity_threshold`	`0.85`	Cosine similarity threshold for dedup matching	7
`enable_legacy_mem0`	`false`	Legacy mem0 fallback (migration complete, not used in production)	7

Memory Import Flags (PRD 15)¶

Flag	Default	Description	PRD
`enable_memory_import`	`false`	Master gate for all memory import functionality (settings page + onboarding + conversational)	15
`enable_memory_import_onboarding`	`false`	Show Step 3.5 (memory import) in Path 1 web onboarding flow	15
`enable_memory_import_conversational`	`false`	Allow companion to offer import once during Stage 1-2 conversation	15
`memory_import_max_entries`	`200`	Maximum parsed entries per import session	15
`memory_import_importance_floor`	`3`	Minimum importance score for imported memories (vs 4 for organic)	15

Individual Superpower Flags¶

Each superpower has an independent feature flag: superpower.{name}.enabled

Proactive (user-configurable): travel_brain, reservation_prep, tickets_vault, birthday_reminder, post_event_checkin, cancellation_protector, membership_renewal, package_tracking, call_prep, focus_protector

Proactive (scheduled): calendar_morning, calendar_events, email_urgency, evening_prep, destination_prep

Agent (user-triggered): calendar_stress_agent, calendar_query_agent, calendar_list_agent, gmail_mindreader_agent

MiniApps: trip_planner, bill_split, todo_list

Life/Wellness: mood_tracker, budget_tracker, habit_tracker, daily_summary

All default to true in dev, false in prod. Enable individually via LaunchDarkly for gradual rollout.

Observability Flags¶

Flag	Default	Purpose
`metrics.token_monitoring_enabled`	`true`	Detailed token usage tracking
`metrics.detailed_logging_enabled`	`false`	Verbose request/response logging

Environment-Level Toggles (Not LaunchDarkly)¶

These are environment variables, not feature flags, but gate major subsystems:

Variable	Default	Purpose
`ENABLE_PROACTIVE_SCHEDULER`	`false`	Master on/off for the proactive scheduler service
`ENVIRONMENT`	`development`	Controls CORS, secrets validation, logging level
`POSTHOG_API_KEY`	(optional)	If unset, analytics is no-op
`SENTRY_DSN`	(optional)	If unset, error tracking is no-op