Default cache warming off or limit to high-use topics

[wtthornton]

Summary

tapps_init defaults warm_cache_from_tech_stack=True, which attempts to pre-fetch Context7 docs for every library in the detected tech stack. In practice this is unreliable and often wasteful.

Problem

Observed in AgentForge (10 libraries in TECH_STACK.md Context7 Priority list):

• Only 2 of 10 libraries were successfully cached — the rest silently failed, likely due to timeouts or rate limits during init
• Init already takes 10-35s — warming adds latency to an already slow startup, especially painful for timeout-prone MCP clients
• Most warmed topics go unused — the warm fetches overview for each library, but real usage hits specific topics (middleware, fixtures, dependencies), so the cache keys don't match actual lookups
• Long-tail libraries rarely need lookups — libraries like python-dotenv and python-frontmatter are simple enough that doc lookups are uncommon
• On-demand caching already works well — first call takes ~2s, subsequent calls hit cache at ~2ms. The one-time cost per library per session is negligible

Recommendation

Either:

Option A: Default warming off (warm_cache_from_tech_stack=False)

• Lazy caching (fetch on first use) is already effective
• Users who want warming can opt in explicitly
• Reclaims significant init time

Option B: Minimal warming — high-use topics only

• Limit to top 2-3 libraries by detected usage frequency (e.g., the primary framework + test framework)
• Warm only the topics most commonly looked up (e.g., overview + one domain-specific topic per library)
• Run warming async/background so it doesn't block init

Context

• Tested with AgentForge project: fastapi, pytest, react, aiosqlite, pydantic-settings, python-dotenv, python-frontmatter, uvicorn, websockets, unittest
• Cache directory showed only python/overview and fastapi/overview persisted — and the fastapi entry was from a manual tapps_lookup_docs call, not the warm
• Solo dev workflow; larger teams or CI may have different tradeoffs

🤖 Generated with Claude Code