Heuristic:Openclaw Openclaw Cache TTL Asymmetric Strategy
| Knowledge Sources | |
|---|---|
| Domains | Performance, Reliability |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Caching pattern using asymmetric TTLs: successful responses are cached longer (5-10 minutes) while errors use shorter TTLs (30 seconds) to avoid hammering APIs during failures.
Description
Throughout the OpenClaw codebase, caches use different TTL values for successful results versus errors. Successful API responses (sender names, room info, server metadata) are cached for 5-10 minutes since this data changes infrequently. Error responses are cached for only 30 seconds, which prevents the cache from hiding recovery while still providing brief protection against cascading failures. Additionally, caches enforce count limits (e.g., max 1000 conversations, max 2000 replies) with LRU-style eviction based on `lastSeenAt` timestamps.
Usage
Apply this heuristic when caching results from external APIs (channel metadata, user profiles, server info). Use the following guidelines:
- Successful responses: 5-10 minute TTL
- Error responses: 30-second TTL
- Add a count limit (1000-2000 entries) to prevent unbounded memory growth
- Prune opportunistically (on insertion, not on a timer)
The Insight (Rule of Thumb)
- Action: Cache successful lookups for 5-10 minutes; cache errors for 30 seconds.
- Value: Success TTL: 300,000-600,000ms. Error TTL: 30,000ms. Max entries: 1000-2000.
- Trade-off: Slightly stale data for successful lookups in exchange for reduced API calls. Brief error caching prevents thundering herd on API recovery.
- Eviction: Use `lastSeenAt` timestamp for LRU eviction. Preserve legacy entries without timestamps until first access.
Reasoning
External API calls are slow (100ms+) and rate-limited. Caching successful results for 5-10 minutes reduces API pressure by 10-100x for frequently accessed data. The shorter error TTL ensures the system quickly retries after the external service recovers. Count limits prevent memory leaks from long-running gateway processes. The `lastSeenAt` strategy evicts least-recently-used entries while preserving backward compatibility with legacy data formats.
Code Evidence from `extensions/nextcloud-talk/src/room-info.ts:5-6`:
const ROOM_CACHE_TTL_MS = 5 * 60 * 1000; // 5 min success
const ROOM_CACHE_ERROR_TTL_MS = 30 * 1000; // 30s error
Count-limited cache from `extensions/bluebubbles/src/monitor.ts:44-45`:
const REPLY_CACHE_MAX = 2000;
const REPLY_CACHE_TTL_MS = 6 * 60 * 60 * 1000; // 6 hours
Conversation store pruning from `extensions/msteams/src/conversation-store-fs.ts:15-16`:
const MAX_CONVERSATIONS = 1000;
const CONVERSATION_TTL_MS = 365 * 24 * 60 * 60 * 1000; // 1 year