In-Memory Transport Cleanup

Status: ✅ FALSE ALARM - Already Handled Priority: 🔴 HIGH (Resolved) Risk Level: LOW Impact: Memory leak prevention via lazy cleanup

← Back to Enhancements

---

Problem Statement (Initial Assessment)

Initial analysis suggested a potential memory leak in the MCP transport management system:

Location: src/mcp/mcp.ts:18

Initial Concern:

const transports: Record<string, StreamableHTTPServerTransport> = {};

Hypothesized Issue:

• Redis session entries expire via TTL (default: 24 hours)
• In-memory transports map only cleaned on explicit DELETE /mcp
• If session expires via TTL, Redis entry removed but in-memory entry persists
• Over time, transports map could grow unbounded

Example Scenario:

Day 1: 100 sessions created → 100 in memory, 100 in Redis
Day 2: 100 old sessions expire in Redis → 100 in memory, 100 new in Redis
Day 3: 100 old sessions expire in Redis → 200 in memory, 100 new in Redis
...
Month 1: 3000 orphaned transports in memory

---

Actual Implementation (Already Solved)

Upon code review, the issue is already handled via lazy cleanup pattern:

Location: src/mcp/mcp.ts:60-73

// Get session ID from header
const sessionId = req.headers["mcp-session-id"] as string | undefined;

if (sessionId && transports[sessionId]) {
  // Check if session still valid in Redis
  const sessionStore = getSessionStore();
  const sessionMetadata = await sessionStore.get(sessionId);

  if (!sessionMetadata) {
    // Session expired in Redis → Clean up in-memory
    delete transports[sessionId];
    logger.info("Cleaned up expired transport", { sessionId });
    return res.status(404).json({
      jsonrpc: "2.0",
      error: { code: -32001, message: "Session not found or expired" },
      id: null,
    });
  }

  // Session valid → Use existing transport
  const transport = transports[sessionId];
  await transport.handleRequest(req, res);
  return;
}

How It Works:

1. Every MCP request checks Redis for session validity
2. If session expired in Redis → Delete from in-memory map
3. If session valid → Refresh Redis TTL (sliding window)
4. Automatic cleanup without periodic sweeps

---

Why This Works

Lazy Cleanup Pattern

Advantages:

• Zero overhead when no expired sessions accessed
• O(1) cleanup per expired session access
• No background jobs consuming CPU/memory
• Natural expiration aligned with access patterns

Trade-offs:

• Expired sessions remain in memory until next access attempt
• Memory usage proportional to inactive sessions
• Acceptable for typical session patterns (users access regularly or don't access at all)

Memory Bounds Analysis

Worst-case scenario:

1000 active sessions × 50KB per transport = 50MB
1000 expired sessions × 50KB per transport = 50MB (temporary)
Total: 100MB peak memory

Cleanup triggers:

• User attempts to resume expired session → Immediate cleanup
• Session deletion via DELETE /mcp → Immediate cleanup
• Server restart → All in-memory state cleared

Real-world behavior:

• Users with expired sessions typically:
  1. Attempt to resume → Cleanup triggered
  2. Never return → Memory usage acceptable
• Active sessions refresh TTL → Never expire unexpectedly

---

Alternative Approaches Considered

Option 1: Periodic Cleanup Job

setInterval(async () => {
  const sessionStore = getSessionStore();
  const sessionIds = Object.keys(transports);

  for (const sessionId of sessionIds) {
    const exists = await sessionStore.get(sessionId);
    if (!exists) {
      delete transports[sessionId];
      logger.info('Cleaned up orphaned transport', { sessionId });
    }
  }
}, 60000); // Every minute

Why not implemented:

• Adds constant CPU overhead (Redis queries every minute)
• Redundant with lazy cleanup
• Doesn't significantly improve memory usage
• Complexity without clear benefit

Option 2: Redis Keyspace Notifications

// Subscribe to Redis expiration events
redis.subscribe('__keyevent@0__:expired', (channel, key) => {
  if (key.startsWith('session:')) {
    const sessionId = key.replace('session:', '');
    delete transports[sessionId];
  }
});

Why not implemented:

• Requires Redis keyspace notifications enabled (performance impact)
• Adds complexity to Redis configuration
• Doesn't work with Redis Cluster without additional setup
• Lazy cleanup sufficient for this use case

---

Current Status: ✅ No Action Required

Conclusion:

• Initial assessment identified a theoretical memory leak
• Code review revealed existing lazy cleanup implementation
• Current approach is correct and efficient
• No changes needed

Verification:

• ✅ Lazy cleanup on session access
• ✅ Redis TTL as source of truth
• ✅ Explicit cleanup via DELETE /mcp
• ✅ Clean shutdown closes all transports

---

Monitoring Recommendations

To verify memory behavior in production:

Prometheus Metrics:

# In-memory session count
mcp_sessions_active

# Memory usage trend
process_resident_memory_bytes

# Session cleanup rate (if metric added)
rate(session_cleanup_total[5m])

Alert Conditions:

• Memory usage growing without bound (> 500MB)
• Session count exceeding expected maximum (> 10,000)
• Large gap between in-memory and Redis session counts

---

Related Architecture

• Session Management - Session lifecycle and storage
• MCP Server - Transport management details

---

False Alarm Analysis

Why the initial concern?

• Gap analysis reviewed code structure but missed lazy cleanup logic
• Pattern looked suspicious without runtime behavior context
• Similar patterns in other codebases do cause memory leaks

Lessons learned:

• Always verify suspected issues with complete code path analysis
• Lazy cleanup is valid pattern for infrequent operations
• Memory leaks require both retention AND lack of cleanup

Updated status: This item should be removed from gap analysis as "False Alarm - Already Handled"