Cache FAQ
Frequently Asked Questions
General Questions
Q: What is caching and why do I need it?
A: Caching stores frequently accessed data in memory (or Redis/file) to avoid repeated API calls to Home Assistant. This significantly improves response times and reduces load on your Home Assistant instance.
Benefits: - Faster responses: Cache hits are 50-200x faster than API calls - Reduced API calls: 60-80% reduction in API calls - Better performance: Improved overall system performance
Q: Is caching enabled by default?
A: Yes, caching is enabled by default. No configuration is needed to start using caching.
Q: Can I disable caching?
A: Yes, you can disable caching:
Q: Will caching break my API calls if it fails?
A: No, the cache system is designed to gracefully degrade. If cache operations fail, API calls proceed normally without caching. Cache failures never break API calls.
Configuration Questions
Q: Which backend should I use?
A: Choose based on your use case:
- Memory: Development, single instance, fastest performance
- Redis: Production, multiple instances, shared cache
- File: Single instance, persistence needed, no Redis
See Configuration Guide for details.
Q: How do I configure Redis backend?
A:
- Install Redis package:
pip install redis - Start Redis server:
docker run -d -p 6379:6379 redis:latest - Configure:
export HASS_MCP_CACHE_BACKEND=redis - Set Redis URL:
export HASS_MCP_CACHE_REDIS_URL=redis://localhost:6379/0
See Configuration Guide for details.
Q: How do I configure file backend?
A:
- Install aiofiles package:
pip install aiofiles - Create cache directory:
mkdir -p .cache - Configure:
export HASS_MCP_CACHE_BACKEND=file - Set cache directory:
export HASS_MCP_CACHE_DIR=.cache
See Configuration Guide for details.
Q: Can I use a configuration file instead of environment variables?
A: Yes, you can use a JSON or YAML configuration file:
See Configuration Guide for details.
TTL Questions
Q: What is TTL?
A: TTL (Time-To-Live) is the duration in seconds that cached data remains valid. After TTL expires, the cache entry is removed and fresh data is fetched.
Q: How do I set TTL for specific endpoints?
A: Use the configuration file:
See Configuration Guide for details.
Q: What are the default TTL values?
A:
- Very Long (1 hour): Areas, zones, system config
- Long (30 minutes): Automations, scripts, scenes
- Medium (5 minutes): Integrations, statistics
- Short (1 minute): Entity states
See Architecture Documentation for details.
Performance Questions
Q: What hit rate should I expect?
A: Target hit rates:
- Static data: >95%
- Stable data: >85%
- Semi-dynamic data: >70%
- Overall: >75%
See Performance Guide for details.
Q: How much memory does caching use?
A:
- Per entry: ~1-5 KB
- 1000 entries: ~1-5 MB
- 10,000 entries: ~10-50 MB
See Performance Guide for details.
Q: How do I monitor cache performance?
A: Use the cache statistics API:
from app.api.system import get_cache_statistics
stats = await get_cache_statistics()
print(f"Hit rate: {stats['statistics']['hit_rate']:.2%}")
See User Guide for details.
Invalidation Questions
Q: When is cache invalidated?
A: Cache is automatically invalidated when data is modified:
- Entity states: When performing entity actions or calling services
- Automations: When creating, updating, or deleting automations
- Areas: When creating, updating, or deleting areas
- And more: See Architecture Documentation for details
Q: How do I manually invalidate cache?
A: Use the cache manager:
from app.core.cache.manager import get_cache_manager
manager = await get_cache_manager()
await manager.invalidate("entities:*")
See User Guide for details.
Q: What are invalidation patterns?
A: Invalidation patterns use wildcards to match cache keys:
entities:*- Invalidates all entity cachesentities:state:*- Invalidates all entity state cachesentities:state:id=light.living_room*- Invalidates specific entity state
See Architecture Documentation for details.
Troubleshooting Questions
Q: Cache is not working. What should I check?
A:
- Check if caching is enabled:
echo $HASS_MCP_CACHE_ENABLED - Verify backend is initialized
- Check logs for cache errors
- Verify cache directory is writable (file backend)
See Troubleshooting Guide for details.
Q: I'm seeing stale data. How do I fix it?
A:
- Reduce TTL values
- Verify cache invalidation is working
- Clear cache manually
- Check invalidation patterns
See Troubleshooting Guide for details.
Q: My hit rate is low. How do I improve it?
A:
- Increase TTL values for stable data
- Reduce cache invalidation frequency
- Optimize cache keys
- Review cache invalidation patterns
See Troubleshooting Guide for details.
Q: Redis connection is failing. What should I do?
A:
- Check Redis URL:
echo $HASS_MCP_CACHE_REDIS_URL - Verify Redis is running:
redis-cli ping - Check network connectivity
- Verify Redis authentication
See Troubleshooting Guide for details.
Development Questions
Q: How do I add caching to a new endpoint?
A: Add the @cached decorator:
from app.core.cache.decorator import cached
from app.core.cache.ttl import TTL_LONG
@cached(ttl=TTL_LONG)
async def get_data():
...
See Developer Guide for details.
Q: How do I invalidate cache on mutations?
A: Add the @invalidate_cache decorator:
from app.core.cache.decorator import invalidate_cache
@invalidate_cache(pattern="data:*")
async def create_data(config: dict):
...
See Developer Guide for details.
Q: How do I test cache behavior?
A: Test cache hit/miss behavior:
import pytest
from app.core.cache.manager import get_cache_manager
@pytest.mark.asyncio
async def test_cache():
manager = await get_cache_manager()
await manager.clear()
# First call: Cache miss
result1 = await get_data()
assert manager.get_statistics()["misses"] == 1
# Second call: Cache hit
result2 = await get_data()
assert manager.get_statistics()["hits"] == 1
See Developer Guide for details.
Backend Questions
Q: Can I use multiple backends at once?
A: No, only one backend can be active at a time. However, you can migrate between backends.
See Migration Guide for details.
Q: What happens if Redis is unavailable?
A: The system automatically falls back to memory backend with a warning. API calls continue normally.
Q: What happens if file backend fails?
A: The system automatically falls back to memory backend with a warning. API calls continue normally.
Q: Can I share cache between multiple instances?
A: Yes, with Redis backend. Memory and file backends are per-instance.
Data Questions
Q: What data is cached?
A: See User Guide for a complete list. Generally:
- Cached: Entity metadata, automations, scripts, scenes, areas, zones, system config
- Not cached: Logbook, history, statistics, events, execution logs
Q: What data is not cached?
A: Highly dynamic, time-sensitive data is not cached:
- Logbook entries
- Entity history
- Statistics calculations
- Events
- Automation execution logs
- Error logs
See User Guide for details.
Q: How long is data cached?
A: Depends on the data type:
- Very stable data: 1 hour
- Stable data: 30 minutes
- Moderately stable data: 5 minutes
- Semi-dynamic data: 1 minute
See Architecture Documentation for details.
Getting Help
If you have questions not covered in this FAQ:
- Check documentation: See Architecture, Configuration, User Guide
- Review examples: See Examples
- Troubleshooting: See Troubleshooting Guide
- GitHub Issues: Create an issue on GitHub