Gap Context Recovery: Acknowledging Returning Users¶
Last Updated: January 9, 2026
Overview¶
When users return after an extended absence, Sage acknowledges the gap naturally instead of pretending nothing happened. This makes conversations feel more human and maintains relationship continuity.
Problem solved: Real friends acknowledge when they haven't talked in a while. Sage pretending nothing happened after a week of silence feels like amnesia.
Gap Categories¶
| Hours Since Last Message | Category | Acknowledgment |
|---|---|---|
| < 72 hours (< 3 days) | recent |
No acknowledgment needed |
| 72-168 hours (3-7 days) | few_days |
Casual: "hey! been a few days" |
| 168+ hours (7+ days) | long_absence |
Warm: "omg hi!! it's been a minute" |
Threshold: 72 hours (3 days) is the minimum before Sage acknowledges a gap.
How It Works¶
Detection Flow¶
User Message Arrives
↓
_track_session_start()
↓
conversation_history.is_new_session(chat_id)
↓
Returns: (is_new_session: bool, hours_since_last: float)
↓
If hours >= 72:
Create gap_context dict
↓
Pass to response_generator
↓
Add greeting guidance to system prompt
Gap Context Structure¶
gap_context = {
"hours_since_last": 120.5, # Hours since last message
"gap_category": "few_days", # recent|few_days|long_absence
"should_acknowledge": True # Whether to acknowledge in greeting
}
Greeting Guidance by Category¶
few_days (3-7 days)¶
System prompt guidance:
GREETING GUIDANCE:
- Acknowledge the gap naturally (don't ignore it, but don't be dramatic)
- Suggested opener: 'hey! been a few days' - casual acknowledgment
- Can ask how they've been, but don't overdo it
- Keep it brief - one line acknowledging the gap, then respond to their message
- DON'T make them feel guilty for being away
Example responses: - "hey! been a few days, how's it going?" - "oh hey stranger haha what's up?"
long_absence (7+ days)¶
System prompt guidance:
GREETING GUIDANCE:
- Acknowledge the gap naturally (don't ignore it, but don't be dramatic)
- Suggested opener: 'omg hi!!' or 'hey stranger!' - be warm and excited
- Ask what's new or follow up on something they mentioned before
- Keep it brief - one line acknowledging the gap, then respond to their message
- DON'T make them feel guilty for being away
Example responses: - "omg hi!! it's been a minute, what's new?" - "hey stranger! missed u, how've u been?"
Key Principles¶
DO¶
- Acknowledge the gap briefly (one line)
- Be warm and welcoming
- Follow up on previous topics if relevant
- Then respond to their actual message
DON'T¶
- Make them feel guilty ("where have you been?!")
- Be dramatic about the absence
- Dwell on the gap for multiple messages
- Ignore the gap entirely (feels robotic)
Integration Points¶
1. Session Tracking (message_handler.py)¶
def _track_session_start(...) -> Optional[Dict[str, Any]]:
is_new_session, hours_since_last = self.conversation_history.is_new_session(chat_id)
gap_context = None
if is_new_session and hours_since_last and hours_since_last >= 72:
gap_context = {
"hours_since_last": hours_since_last,
"gap_category": self._categorize_gap(hours_since_last),
"should_acknowledge": True
}
return gap_context
2. Gap Categorization (message_handler.py)¶
def _categorize_gap(self, hours: float) -> str:
if hours < 72: return "recent" # < 3 days
if hours < 168: return "few_days" # 3-7 days
return "long_absence" # 7+ days
3. System Prompt Injection (response_generator.py)¶
Gap context is added after the relationship stage in the system prompt:
gap_text = f"""
# CONVERSATION GAP CONTEXT
⏰ Last conversation: {hours:.0f} hours ago ({category})
This is a returning user after a break.
GREETING GUIDANCE:
- Acknowledge the gap naturally...
"""
File Locations¶
| Component | Location |
|---|---|
| Gap detection | app/orchestrator/message_handler.py (_track_session_start) |
| Gap categorization | app/orchestrator/message_handler.py (_categorize_gap) |
| Prompt injection | app/orchestrator/response_generator.py (_build_system_prompt) |
Example Conversation Flows¶
3-Day Gap¶
[User hasn't messaged in 4 days]
User: "hey"
Sage: "hey! been a few days, how's it going?"
User: "good! been busy with work"
Sage: "ahh yeah i feel that. anything exciting happen?"
Week+ Gap¶
[User hasn't messaged in 10 days]
User: "hi sage"
Sage: "omg hi!! it's been a minute 💜 what's new?"
User: "so much lol, got a new job"
Sage: "wait WHAT that's amazing!! tell me everything"
No Gap (Normal)¶
Analytics Integration¶
Gap information is also sent to analytics for tracking:
self.analytics_tracker.track_conversation_started(
user_phone=user_phone,
chat_guid=chat_id,
persona_id=persona_id,
is_group=is_group,
hours_since_last=hours_since_last # Tracked for analysis
)
This allows monitoring of: - Re-engagement rates after gaps - Typical gap lengths before users return - Impact of gap acknowledgment on conversation length