Configuration Update

Add the userNotification block to your config.json:

Before:

{
  "channels": ["imessage"],
  "model": "claude-opus-4.6",
  "compaction": {
    "enabled": true,
    "thresholdTokens": 75000,
    "strategy": "semantic-summary"
  }
}

After:

{
  "channels": ["imessage"],
  "model": "claude-opus-4.6",
  "compaction": {
    "enabled": true,
    "thresholdTokens": 75000,
    "strategy": "semantic-summary",
    "userNotification": {
      "enabled": true,
      "message": "Context window filling up — what should I remember from this session?",
      "thresholdTokens": 60000,
      "responseTimeoutSeconds": 120,
      "resumeOnTimeout": true
    }
  }
}

Configuration Field Reference

Code Modification

If implementing the feature directly in the OpenClaw source, modify CompactionManager.ts:

// Location: src/core/CompactionManager.ts

async triggerCompaction(session: Session): Promise {
  const config = this.config.compaction;
  const tokenCount = await this.tokenCounter.getCount(session);

  // NEW: Check if user notification should fire first
  if (
    config.userNotification?.enabled &&
    tokenCount >= config.userNotification.thresholdTokens
  ) {
    await this.sendUserNotification(session, config.userNotification);
  }

  // Original compaction logic continues
  return this.executeMemoryFlush(session);
}

async sendUserNotification(
  session: Session,
  notificationConfig: UserNotificationConfig
): Promise<UserResponse | null> {
  const channel = this.channelManager.getActiveChannel(session);

  // Send visible message to user
  await channel.send({
    type: 'user-notification',
    content: notificationConfig.message,
    metadata: {
      compactionPending: true,
      tokenCount: await this.tokenCounter.getCount(session),
      timeoutSeconds: notificationConfig.responseTimeoutSeconds
    }
  });

  // Wait for user response
  try {
    const response = await this.waitForUserResponse(
      session,
      notificationConfig.responseTimeoutSeconds
    );

    if (response && response.content) {
      // Inject user's priorities into compaction context
      await this.injectUserPriorities(session, response.content);
    }

    return response;
  } catch (TimeoutError) {
    if (notificationConfig.resumeOnTimeout) {
      this.logger.warn('User notification timeout — proceeding with compaction');
      return null;
    }
    throw new CompactionAbortedError('User did not respond within timeout window');
  }
}

async injectUserPriorities(session: Session, userContent: string): Promise {
  // Append user's guidance to compaction extraction context
  const priorityContext = {
    type: 'user-priority',
    content: userContent,
    source: 'user-notification-response',
    timestamp: Date.now()
  };

  await session.updateMetadata({
    userPriorities: [
      ...(session.metadata.userPriorities || []),
      priorityContext
    ]
  });
}

CLI Equivalent (Manual Trigger)

For immediate testing without config reload:

# Test user notification manually
openclaw compaction notify --session-id <session_id> \
  --message "Context window filling up — what should I remember from this session?"

# Verify notification sent
openclaw compaction status --session-id <session_id>

Test Scenarios

1. Notification Firing Verification

# Start a session and monitor compaction events
openclaw session start --channel imessage --model claude-opus-4.6

# In another terminal, monitor events
openclaw events stream --filter compaction --format json

Expected output:

{
  "event": "compaction-notification-sent",
  "sessionId": "sess_abc123",
  "tokenCount": 60234,
  "thresholdTokens": 60000,
  "channel": "imessage",
  "timestamp": "2025-01-15T14:32:01Z"
}

{
  "event": "user-response-received",
  "sessionId": "sess_abc123",
  "responseLength": 342,
  "responseTimeoutSeconds": 118,
  "timestamp": "2025-01-15T14:33:45Z"
}

2. User Priority Injection Verification

# After user responds, check if priorities were captured
openclaw session inspect --session-id sess_abc123 --show-metadata | jq '.userPriorities'

Expected output:

[
  {
    "type": "user-priority",
    "content": "Always use Box 16 for state wages, not Box 1 federal wages. Also remember to check for dual-state filings.",
    "source": "user-notification-response",
    "timestamp": 1705326825000
  }
]

3. Compaction Store Content Verification

# After compaction completes, verify user priorities are in the store
openclaw compaction inspect --session-id sess_abc123 | jq '.extractedContexts'

Expected output:

{
  "semanticSummary": "Tax preparation session covering W-2 processing...",
  "userGuidance": "Always use Box 16 for state wages, not Box 1 federal wages...",
  "extractedBlocks": [...],
  "priorityIndicators": ["user-guidance"]
}

4. Timeout Behavior Verification

# Trigger notification with short timeout for testing
openclaw compaction notify --session-id sess_abc123 \
  --timeout-seconds 10 \
  --resume-on-timeout true

# Verify compaction proceeds after timeout
openclaw events stream --filter compaction --max-events 5

Expected output:

{
  "event": "compaction-started",
  "sessionId": "sess_abc123",
  "reason": "notification-timeout",
  "timestamp": "2025-01-15T14:35:12Z"
}

Exit Code Reference

Configuration Errors

• thresholdTokens too close to compaction threshold
  userNotification.thresholdTokens must be lower than thresholdTokens. If equal or higher, the notification never fires before compaction.

  // ❌ INCORRECT — notification threshold equals compaction threshold
  "thresholdTokens": 75000,
  "userNotification": {
    "thresholdTokens": 75000  // Never fires in time
  }
  // ✅ CORRECT — notification fires before compaction
  “thresholdTokens”: 75000,
  “userNotification”: {
  “thresholdTokens”: 60000  // Fires at 60% context
  }

• responseTimeoutSeconds too short for async channels
  iMessage and similar async channels may have delivery delays. A 30-second timeout may expire before the user can respond.

  // ❌ INCORRECT — too short for async channels
  "responseTimeoutSeconds": 30
  // ✅ CORRECT — adequate time for user consideration
  “responseTimeoutSeconds”: 120
  

Environment-Specific Traps

• macOS Focus Assist blocking iMessage delivery
  When Focus is enabled, iMessage notifications may not reach the user. The responseTimeoutSeconds will expire silently.

  # Alternative: Use a synchronous channel for critical sessions
  "channels": ["imessage", "terminal"],  // Terminal as fallback
  

• Docker container network isolation
  In Docker deployments, the notification channel must be exposed correctly:

  # Ensure channel ports are mapped
  docker run -p 9229:9229 -p 3000:3000 openclaw/openclaw:latest
  Verify channel accessibility
  openclaw channels list –verbose
  

• Windows Defender/firewall blocking notification delivery
  Windows environments may block outbound notification ports. Configure firewall rules or switch to a local notification method.

User Behavior Pitfalls

• Users providing unhelpful responses
  If users reply with "idk" or "nothing", the MemoryExtractor receives empty guidance. Consider adding prompt validation:

  // Minimum response length check (optional enhancement)
  if (response.content.length < 20) {
    // Send follow-up: "Please provide more detail so I can preserve what matters."
  }
  

• Users becoming notification-fatigued
  Frequent notifications may cause users to ignore them. Balance token threshold against notification frequency.

Edge Cases

• Multiple rapid session switches
  If the user switches between sessions rapidly, notifications may arrive for the wrong session context. The sessionId in the notification metadata ensures correct targeting.
• Notification sent during active tool execution
  If the agent is mid-execution when notification fires, the user's response should be queued until the tool completes.

Contextual Error References

• COMPACTION_001: Threshold Exceeded
  Standard compaction trigger. Related when understanding the difference between compaction thresholds and notification thresholds.
• COMPACTION_002: Memory Extraction Failed
  MemoryExtractor errors. The userNotification feature provides an additional layer: if extraction fails, the user's guidance is preserved in session.metadata.userPriorities for retry.
• CHANNEL_003: Delivery Timeout
  Channel-specific timeouts. Often misdiagnosed as notification failures when the issue is channel availability.
• CONTEXT_007: Reset During Active Tool
  Context reset while tool is executing. The userNotification delay does not prevent this, but user guidance may be preserved in the new session.
• TOKEN_002: Counter Discrepancy
  Token counting errors. If TokenCounter misreports counts, the notification may fire at unexpected points.

Historical Context

The silent compaction behavior described in this issue has been a persistent pain point in OpenClaw sessions exceeding 2 hours. Community discussion threads (Issue #847, Discussion #1203) document similar experiences:

• "Compaction fires mid-tax-season without warning"
• "Model reverts to generic responses after compaction"
• "No way to tell the agent what's important before memory wipe"

The userNotification feature addresses the fundamental asymmetry: the model cannot reliably infer human values, so human guidance must precede machine memory management.

Further Reading

• OpenClaw Compaction Architecture — Deep dive into the CompactionManager pipeline
• MemoryExtractor Heuristics — Understanding how context blocks are scored
• Channel Configuration Guide — Setting up notification delivery across platforms